pyscriptc 0.1.0__py3-none-any.whl

pyscriptc/coverage.py

@@ -0,0 +1,388 @@
+"""Collect-all fence report behind `pyscriptc coverage`.
+
+Lowering already keeps going after a fence inside a body, a class, or a module
+statement. This module runs it on a file or a package tree, then classifies
+each fence into a feature family, attaches a refactor hint and a code frame,
+and groups the fences by the definition that holds them. It never changes how
+`compile` treats a fence.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pyscriptc.errors import IRError, format_diagnostic
+from pyscriptc.lower import lower_file
+from pyscriptc.package import _discover, lower_directory
+
+SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class Family:
+    key: str
+    hint: str
+    derived: bool = False
+
+
+_FAMILIES = {
+    family.key: family
+    for family in (
+        Family(
+            "union-types",
+            "Narrow the annotation to one arm, or split the function per arm. A tagged union is a compiler epic.",
+        ),
+        Family(
+            "optional-types",
+            "Accept or return T and signal absence with a sentinel. Optional[T] needs the tagged-union epic.",
+        ),
+        Family(
+            "generic-alias", "Use list[T], dict[K, V] or tuple[...] in the signature instead of the abstract generic."
+        ),
+        Family(
+            "dynamic-annotation",
+            "Annotate with the concrete type. object, Any, Protocol, TypeVar and Callable do not lower.",
+        ),
+        Family("forward-reference", "Define the class before use and write the annotation unquoted."),
+        Family(
+            "unlowered-type-name",
+            "Replace the alias or imported name with a lowered type, or lower the class it names.",
+        ),
+        Family("param-inference", "Annotate the parameter. Unannotated parameters need local type inference."),
+        Family("local-inference", "Add an annotation where the name is first assigned."),
+        Family("return-inference", "Add a return annotation."),
+        Family("uninitialized-field", "Give the field an initial value in __init__ or at the assignment."),
+        Family("value-type", "Use list[T], dict[K, V] or a lowered class for this annotation."),
+        Family(
+            "annotation-other",
+            "Rewrite the annotation with int, float, bool, str, bytes, list, dict, tuple or a lowered class.",
+        ),
+        Family("decorators", "Remove the decorator or inline what it does. Only a closed set of decorators lowers."),
+        Family(
+            "parameter-forms",
+            "Use plain positional parameters. Keyword-only, positional-only, *args and **kwargs do not lower.",
+        ),
+        Family("class-keywords", "Use one lowered base class and no class keywords such as metaclass."),
+        Family("class-body", "Declare fields with an annotation and no value and set them in __init__."),
+        Family("except-as", "Name a lowered exception and drop the `as` binding or the bare except."),
+        Family("with-as", "Use a lowered context manager without `as`, or open and close explicitly."),
+        Family("async", "Async definitions do not lower. Use a synchronous definition."),
+        Family("enum", "Write the enum as integer constants in a plain class body."),
+        Family(
+            "module-statements",
+            "Module scope holds imports, functions, classes and constant assignments only. "
+            "Move the statement into a function.",
+        ),
+        Family("module-assign", "A module assignment must be a constant the lowering can fold."),
+        Family(
+            "import-table",
+            "The imported module is outside the closed import table. Avoid it or wait for it to be queued.",
+        ),
+        Family("queued-stdlib", "The stdlib module is queued and not lowered yet."),
+        Family("name-resolution", "The name is not a local, a parameter or a lowered global. Declare it or import it."),
+        Family("typing-value", "A typing name is used as a value. Keep typing names in annotations only."),
+        Family("module-value", "A module is used as a value. Call its lowered functions instead."),
+        Family("unlowered-call", "Call a lowered function, or rewrite the call with lowered constructs."),
+        Family("keyword-args", "Pass the arguments positionally."),
+        Family("call-arity", "Match the lowered arity of the call."),
+        Family("operator", "Convert the operands to a supported type pair."),
+        Family("non-latin1", "Use Latin-1 text. Other strings do not lower."),
+        Family("type-mismatch", "Convert the operand explicitly."),
+        Family("fall-off-end", "End every path with a return or a raise."),
+        Family("field-lookup", "Access only fields the class declares."),
+        Family("construct-other", "Rewrite the statement with lowered constructs."),
+        Family(
+            "export-cascade", "Follows from a fence in the exporting module. Fix that definition first.", derived=True
+        ),
+        Family("class-cascade", "Follows from a fence inside the class. Fix the class first.", derived=True),
+    )
+}
+
+
+def _stdlib_family(match: re.Match[str]) -> str:
+    return f"stdlib:{match.group(1)}"
+
+
+# Order matters: the first matching rule wins. A rule is (code or None, message regex, family).
+_RULES: tuple[tuple[str | None, str, str], ...] = (
+    ("PS1101", r"", "union-types"),
+    ("PS1102", r"", "optional-types"),
+    ("PS1103", r"", "generic-alias"),
+    ("PS1104", r"", "dynamic-annotation"),
+    ("PS1105", r"", "forward-reference"),
+    ("PS1106", r"", "unlowered-type-name"),
+    ("PS1201", r"", "decorators"),
+    ("PS1202", r"", "parameter-forms"),
+    ("PS1203", r"", "class-keywords"),
+    ("PS1204", r"", "class-body"),
+    ("PS1205", r"", "except-as"),
+    ("PS1206", r"", "with-as"),
+    ("PS1001", r"^parameter .+ needs an annotation$", "param-inference"),
+    ("PS1001", r"needs an annotation before use$", "local-inference"),
+    ("PS1001", r"needs a return annotation$", "return-inference"),
+    ("PS1001", r"needs an initial value$|needs __init__$|does not assign", "uninitialized-field"),
+    ("PS1001", r"is not a value type in the IR", "value-type"),
+    ("PS1001", r"", "annotation-other"),
+    ("PS1003", r"", "type-mismatch"),
+    ("PS1004", r"", "fall-off-end"),
+    ("PS2001", r"is not a field$|has no fields$", "field-lookup"),
+    ("PS2001", r"is not in the lowered subset of ([\w.]+)", "stdlib"),
+    ("PS2001", r"", "construct-other"),
+    ("PS2002", r"is not exported by this package", "export-cascade"),
+    ("PS2002", r"^this class .+ is not lowered", "class-cascade"),
+    ("PS2002", r"is not in the closed import table", "import-table"),
+    ("PS2002", r"is not a local or parameter", "name-resolution"),
+    ("PS2002", r"is a typing name and is not a value", "typing-value"),
+    ("PS2002", r"^module .+ is not lowered|module .+ is not a value", "module-value"),
+    ("PS2002", r"^call to .+ is not lowered|call of attribute is not lowered", "unlowered-call"),
+    ("PS2002", r"AsyncFunctionDef|async ", "async"),
+    ("PS2002", r"\benum\b", "enum"),
+    ("PS2002", r"at module scope is not lowered", "module-statements"),
+    ("PS2002", r"module assignment", "module-assign"),
+    ("PS2002", r"decorators? ", "decorators"),
+    ("PS2002", r"", "construct-other"),
+    ("PS2003", r"keyword arguments", "keyword-args"),
+    ("PS2003", r"", "call-arity"),
+    ("PS2004", r"", "operator"),
+    ("PS2005", r"", "non-latin1"),
+    ("PS2101", r"", "queued-stdlib"),
+)
+
+
+def family_of(code: str, message: str) -> str:
+    for rule_code, pattern, family in _RULES:
+        if rule_code is not None and rule_code != code:
+            continue
+        match = re.search(pattern, message)
+        if match is None:
+            continue
+        if family == "stdlib":
+            return _stdlib_family(match)
+        return family
+    return "construct-other"
+
+
+def hint_for(family: str, message: str) -> str:
+    known = _FAMILIES.get(family)
+    if known is not None:
+        if family == "param-inference":
+            name = re.search(r"parameter (\S+) needs", message)
+            if name:
+                return f"Annotate parameter `{name.group(1)}`. Unannotated parameters need local type inference."
+        return known.hint
+    if family.startswith("stdlib:"):
+        return f"Use a lowered attribute of {family.split(':', 1)[1]}, or hand-write the logic."
+    return _FAMILIES["construct-other"].hint
+
+
+def is_derived(family: str) -> bool:
+    known = _FAMILIES.get(family)
+    return known is not None and known.derived
+
+
+@dataclass
+class _Def:
+    name: str
+    kind: str
+    line: int
+    end_line: int
+    body_line: int
+
+
+def _definitions(tree: ast.AST) -> list[_Def]:
+    found: list[_Def] = []
+
+    def walk(node: ast.AST, prefix: str) -> None:
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                name = f"{prefix}{child.name}"
+                kind = "class" if isinstance(child, ast.ClassDef) else "function"
+                body_line = child.body[0].lineno if child.body else child.lineno
+                found.append(_Def(name, kind, child.lineno, child.end_lineno or child.lineno, body_line))
+                walk(child, f"{name}.")
+            else:
+                walk(child, prefix)
+
+    walk(tree, "")
+    return found
+
+
+def _innermost(defs: list[_Def], line: int) -> _Def | None:
+    best: _Def | None = None
+    for item in defs:
+        if item.line <= line <= item.end_line and (best is None or item.line >= best.line):
+            best = item
+    return best
+
+
+def _read(path: str, cache: dict[str, str | None]) -> str | None:
+    if path not in cache:
+        try:
+            cache[path] = Path(path).read_text(encoding="utf-8")
+        except OSError:
+            cache[path] = None
+    return cache[path]
+
+
+def _lower(target: Path) -> tuple[dict[str, Any], list[str]]:
+    if target.is_dir():
+        module, _ = lower_directory(target)
+        files = [str(path) for _, path, _ in _discover(target)[0]]
+        return module, files
+    if target.is_file():
+        module, _ = lower_file(str(target))
+        return module, [str(target)]
+    raise IRError(f"source not found: {target}")
+
+
+def build_report(target: Path) -> dict[str, Any]:
+    module, files = _lower(target)
+    sources: dict[str, str | None] = {}
+    trees: dict[str, list[_Def]] = {}
+    total_defs: dict[str, int] = {}
+    for path in files:
+        text = _read(path, sources)
+        if text is None:
+            continue
+        defs = _definitions(ast.parse(text, filename=path))
+        trees[path] = defs
+        total_defs[path] = len(defs)
+
+    seen: set[tuple[Any, ...]] = set()
+    entries: list[dict[str, Any]] = []
+    raw = sorted(
+        module["fences"],
+        key=lambda f: (f["span"]["file"], f["span"]["line"], f["span"]["col"], f["code"]),
+    )
+    for fence in raw:
+        span = fence["span"]
+        key = (fence["code"], span["file"], span["line"], span["col"], fence["message"])
+        if key in seen:
+            continue
+        seen.add(key)
+        path = span["file"]
+        text = _read(path, sources)
+        defs = trees.get(path, [])
+        owner = _innermost(defs, span["line"])
+        family = family_of(fence["code"], fence["message"])
+        lines = text.splitlines() if text else []
+        statement = lines[span["line"] - 1].strip() if 1 <= span["line"] <= len(lines) else ""
+        entries.append(
+            {
+                "code": fence["code"],
+                "message": fence["message"],
+                "family": family,
+                "derived": is_derived(family),
+                "file": path,
+                "line": span["line"],
+                "col": span["col"],
+                "endLine": span["endLine"],
+                "endCol": span["endCol"],
+                "definition": owner.name if owner else None,
+                "statement": statement,
+                "frame": format_diagnostic(fence, text),
+                "hint": hint_for(family, fence["message"]),
+            }
+        )
+
+    by_def: dict[tuple[str, str], list[int]] = defaultdict(list)
+    for index, entry in enumerate(entries):
+        if entry["definition"] is not None:
+            by_def[(entry["file"], entry["definition"])].append(index)
+    definitions: list[dict[str, Any]] = []
+    for (path, name), indexes in sorted(by_def.items()):
+        owner = next(d for d in trees[path] if d.name == name)
+        # A fence between the def line and the first body line sits in the signature or header.
+        header = any(entries[i]["line"] < owner.body_line for i in indexes)
+        definitions.append(
+            {
+                "file": path,
+                "name": name,
+                "kind": owner.kind,
+                "line": owner.line,
+                "fences": indexes,
+                "bodyAnalyzed": not header,
+            }
+        )
+    module_fences = [i for i, e in enumerate(entries) if e["definition"] is None]
+
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "target": str(target),
+        "summary": _summary(entries, definitions, files, total_defs),
+        "fences": entries,
+        "definitions": definitions,
+        "moduleFences": module_fences,
+        "chain": _chain(entries, definitions),
+    }
+
+
+def _summary(
+    entries: list[dict[str, Any]],
+    definitions: list[dict[str, Any]],
+    files: list[str],
+    total_defs: dict[str, int],
+) -> dict[str, Any]:
+    fences_by_family = Counter(e["family"] for e in entries)
+    return {
+        "files": len(files),
+        "definitions": sum(total_defs.values()),
+        "fencedDefinitions": len(definitions),
+        "fences": len(entries),
+        "rootFences": sum(1 for e in entries if not e["derived"]),
+        "byCode": dict(sorted(Counter(e["code"] for e in entries).items())),
+        "byFamily": {
+            family: {"fences": count, "derived": is_derived(family)}
+            for family, count in sorted(fences_by_family.items(), key=lambda kv: (-kv[1], kv[0]))
+        },
+    }
+
+
+def _chain(entries: list[dict[str, Any]], definitions: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Per family: how many definitions it alone blocks, and how many root fences stay if it is fixed."""
+    root_total = sum(1 for e in entries if not e["derived"])
+    root_by_family = Counter(e["family"] for e in entries if not e["derived"])
+    alone: Counter[str] = Counter()
+    for definition in definitions:
+        families = {entries[i]["family"] for i in definition["fences"] if not entries[i]["derived"]}
+        if len(families) == 1:
+            alone[next(iter(families))] += 1
+    chain = [
+        {
+            "family": family,
+            "fences": count,
+            "definitionsUnblocked": alone[family],
+            "rootFencesLeft": root_total - count,
+        }
+        for family, count in root_by_family.items()
+    ]
+    chain.sort(key=lambda item: (-item["definitionsUnblocked"], -item["fences"], item["family"]))
+    return chain
+
+
+def render_text(report: dict[str, Any]) -> str:
+    summary = report["summary"]
+    parts = [
+        f"{report['target']}: {summary['fences']} fences "
+        f"({summary['rootFences']} root) in {summary['fencedDefinitions']} of {summary['definitions']} definitions"
+    ]
+    entries = report["fences"]
+    for entry in entries:
+        parts.append(entry["frame"])
+        owner = entry["definition"] or "<module>"
+        parts.append(f"  family: {entry['family']}{' (derived)' if entry['derived'] else ''}  in: {owner}")
+        parts.append(f"  hint: {entry['hint']}")
+    if report["chain"]:
+        parts.append("blockers, most definitions first:")
+        for item in report["chain"][:10]:
+            parts.append(
+                f"  {item['family']}: {item['fences']} fences, "
+                f"fixing it unblocks {item['definitionsUnblocked']} definitions "
+                f"and leaves {item['rootFencesLeft']} more root fences"
+            )
+    return "\n".join(parts)

pyscriptc/debug.py

@@ -0,0 +1,120 @@
+"""Compiler debug mode.
+
+`--debug` (or `PYSC_DEBUG`) prints a compact per-stage table to stderr.
+`--debug-dir DIR` additionally writes the intermediate artifacts the agent
+needs to inspect a compile: the lowered module (`ir.json`), the emitted LLVM
+text (`out.ll`), the exact cc command lines (`cc.sh`), and a machine-readable
+`summary.json`. Debug output never touches the IR or the emitted text.
+
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+_TOPICS = {"stages", "fences", "cc", "paths", "all"}
+
+
+def parse_topics(value: str | None) -> set[str]:
+    """A `--debug`/`PYSC_DEBUG` value: empty means `stages`, else a comma list."""
+    if value is None or not value.strip() or value.strip() in ("1", "true", "on"):
+        return {"stages"}
+    topics = {topic.strip() for topic in value.split(",") if topic.strip()}
+    unknown = topics - _TOPICS
+    if unknown:
+        raise ValueError(f"unknown debug topic(s): {', '.join(sorted(unknown))}")
+    return topics
+
+
+def resolve(flag: str | None, debug_dir: str | None) -> Debug | None:
+    """`--debug` wins over `PYSC_DEBUG`; `--debug-dir` alone also enables debug."""
+    value = flag if flag is not None else os.environ.get("PYSC_DEBUG")
+    if flag is None and not value and debug_dir is None:
+        return None
+    topics = parse_topics(value)
+    if debug_dir is not None:
+        topics.add("paths")
+    return Debug(topics, None if debug_dir is None else Path(debug_dir))
+
+
+class Debug:
+    def __init__(self, topics: set[str], debug_dir: Path | None) -> None:
+        self.topics = topics
+        self.debug_dir = debug_dir
+        self.stages: list[tuple[str, float]] = []
+        self.commands: list[list[str]] = []
+        self._starts: list[float] = []
+        self._t0 = time.perf_counter()
+
+    def wants(self, topic: str) -> bool:
+        return "all" in self.topics or topic in self.topics
+
+    def begin(self, name: str) -> None:
+        self._starts.append(time.perf_counter())
+
+    def end(self, name: str) -> None:
+        self.stages.append((name, (time.perf_counter() - self._starts.pop()) * 1000.0))
+
+    def render(self, module: dict[str, Any] | None, outputs: dict[str, str]) -> str:
+        lines: list[str] = []
+        if self.wants("stages"):
+            lines.append("[debug] stage           ms")
+            for name, ms in self.stages:
+                lines.append(f"[debug] {name:<12}{ms:>8.1f}")
+            total = (time.perf_counter() - self._t0) * 1000.0
+            lines.append(f"[debug] {'total':<12}{total:>8.1f}")
+        if module is not None and self.wants("fences"):
+            fences = module.get("fences", [])
+            lines.append(f"[debug] fences: {len(fences)}")
+            for fence in fences:
+                span = fence.get("span", {})
+                lines.append(
+                    f"[debug]   {span.get('file')}:{span.get('line')}:{span.get('col')}"
+                    f" {fence.get('code')} {fence.get('message')}"
+                )
+        if self.commands and self.wants("cc"):
+            lines.append("[debug] cc:")
+            for argv in self.commands:
+                lines.append(f"[debug]   {' '.join(argv)}")
+        if outputs and self.wants("paths"):
+            for key, value in outputs.items():
+                lines.append(f"[debug] {key}: {value}")
+        return "\n".join(lines)
+
+    def summary(self, module: dict[str, Any] | None, outputs: dict[str, str], status: str) -> dict[str, Any]:
+        return {
+            "stages": [{"name": name, "ms": round(ms, 3)} for name, ms in self.stages],
+            "totalMs": round((time.perf_counter() - self._t0) * 1000.0, 3),
+            "fences": [] if module is None else module.get("fences", []),
+            "functions": 0 if module is None else len(module.get("functions", [])),
+            "commands": self.commands,
+            "outputs": outputs,
+            "status": status,
+        }
+
+    def write_dir(
+        self,
+        module: dict[str, Any] | None,
+        ll_text: str | None,
+        outputs: dict[str, str],
+        status: str,
+    ) -> None:
+        if self.debug_dir is None:
+            return
+        self.debug_dir.mkdir(parents=True, exist_ok=True)
+        if module is not None:
+            (self.debug_dir / "ir.json").write_text(json.dumps(module, indent=2) + "\n", encoding="utf-8")
+        if ll_text is not None:
+            (self.debug_dir / "out.ll").write_text(ll_text, encoding="utf-8")
+        if self.commands:
+            script = "#!/bin/sh\n# exact cc invocations pyscriptc ran\n" + "\n".join(
+                " ".join(argv) for argv in self.commands
+            )
+            (self.debug_dir / "cc.sh").write_text(script + "\n", encoding="utf-8")
+        (self.debug_dir / "summary.json").write_text(
+            json.dumps(self.summary(module, outputs, status), indent=2) + "\n", encoding="utf-8"
+        )

pyscriptc/diagnostics.py

@@ -0,0 +1,179 @@
+"""Diagnostic code registry behind `pyscriptc explain`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    code: str
+    title: str
+    why: str
+    fix: str
+
+
+_ENTRIES = (
+    Diagnostic(
+        "PS0001",
+        "invalid input or IR",
+        "The source or the generated IR failed a structural check before lowering could finish.",
+        "Fix the input path or syntax error named in the message.",
+    ),
+    Diagnostic(
+        "PS1001",
+        "annotation missing or not lowered",
+        (
+            "A parameter, return, or variable needs an annotation the subset can read, "
+            "or an annotation form has no more specific code."
+        ),
+        "Annotate the name with int, float, bool, str, bytes, list[T], dict[K, V], tuple[...], or a lowered class.",
+    ),
+    Diagnostic(
+        "PS1003",
+        "type mismatch",
+        "An operation received a type the lowered subset does not accept for it.",
+        "Convert the operand explicitly, for example int(flag) before math calls.",
+    ),
+    Diagnostic(
+        "PS1004",
+        "function can fall off the end",
+        "A function with a non-None return type has a path that reaches the end without a return.",
+        "End every path with a return or a raise.",
+    ),
+    Diagnostic(
+        "PS1101",
+        "union annotation",
+        "The IR has no tagged union yet, so `A | B` and `Union[A, B]` have no representation.",
+        "Narrow the annotation to one arm, or split the function per arm.",
+    ),
+    Diagnostic(
+        "PS1102",
+        "Optional annotation",
+        "The IR has no optional value, so `Optional[T]` and `T | None` have no representation.",
+        "Return or accept T and signal absence with a sentinel value, or split the function.",
+    ),
+    Diagnostic(
+        "PS1103",
+        "generic alias annotation",
+        (
+            "A subscripted annotation such as Mapping[K, V], Sequence[T], Iterator[T], "
+            "Callable[...], or type[T] is not a lowered container."
+        ),
+        "Use list[T], dict[K, V], or tuple[...] in the signature.",
+    ),
+    Diagnostic(
+        "PS1104",
+        "dynamic or structural annotation",
+        (
+            "object, Any, Protocol, TypeVar, Generic, Callable and ABC bases describe "
+            "types the subset cannot represent natively."
+        ),
+        "Annotate with the concrete type the function really takes.",
+    ),
+    Diagnostic(
+        "PS1105",
+        "forward reference annotation",
+        "A quoted annotation such as 'Node' is not resolved by the lowering.",
+        "Define the class before use and write the name unquoted.",
+    ),
+    Diagnostic(
+        "PS1106",
+        "annotation names an unlowered type",
+        "The annotation is a plain name that is not a builtin scalar, a lowered class, or a known alias.",
+        "Import a lowered class, or replace the alias with the concrete type.",
+    ),
+    Diagnostic(
+        "PS1201",
+        "decorator",
+        "Only a closed set of decorators lowers. Other decorators change behavior the compiler cannot see.",
+        "Remove the decorator, or inline what it does.",
+    ),
+    Diagnostic(
+        "PS1202",
+        "parameter form",
+        "Positional-only, keyword-only, *args and **kwargs parameters are not lowered.",
+        "Use plain positional parameters, with defaults where needed.",
+    ),
+    Diagnostic(
+        "PS1203",
+        "class header form",
+        "Class keywords (metaclass=...) and multiple inheritance are not lowered.",
+        "Use a single lowered base class and no class keywords.",
+    ),
+    Diagnostic(
+        "PS1204",
+        "class body statement",
+        "A class body holds only annotated fields without values and method definitions.",
+        "Move assignments into __init__ and declare fields with an annotation only.",
+    ),
+    Diagnostic(
+        "PS1205",
+        "except form",
+        "`except E as name` and bare `except:` are not lowered.",
+        "Name a lowered exception class and drop the `as` binding.",
+    ),
+    Diagnostic(
+        "PS1206",
+        "with-as binding",
+        "`with ... as name` is lowered only for a closed set of context managers.",
+        "Use a lowered context manager without the binding, or open and close explicitly.",
+    ),
+    Diagnostic(
+        "PS2001",
+        "stdlib name not lowered",
+        "The module imports, but this attribute is outside its lowered surface.",
+        "Use a lowered attribute of the module, or hand-write the logic.",
+    ),
+    Diagnostic(
+        "PS2002",
+        "construct not lowered",
+        "A statement, expression, import, or definition has no lowering.",
+        "Rewrite it with the lowered constructs, as the hint for this fence says.",
+    ),
+    Diagnostic(
+        "PS2003",
+        "call arguments not lowered",
+        "A call has keyword arguments, or the wrong number of arguments, for its lowered form.",
+        "Pass positional arguments in the lowered arity.",
+    ),
+    Diagnostic(
+        "PS2004",
+        "operator or operand not lowered",
+        "The operator is not lowered for these operand types.",
+        "Convert the operands to a supported pair of types.",
+    ),
+    Diagnostic(
+        "PS2005",
+        "string literal outside Latin-1",
+        "Strings are byte sequences in the runtime, so only Latin-1 text lowers.",
+        "Use Latin-1 text, or move the literal to bytes.",
+    ),
+    Diagnostic(
+        "PS2101",
+        "queued stdlib module",
+        "The module is on the roadmap and is not lowered yet.",
+        "Avoid the module, or wait for the queue entry to land.",
+    ),
+    Diagnostic(
+        "PS3001",
+        "version mismatch",
+        "The running interpreter is not the CPython version the subset targets.",
+        "Run under the pinned CPython version.",
+    ),
+    Diagnostic(
+        "PS3002",
+        "does not fit",
+        "The emitted program exceeds a fixed limit of the backend.",
+        "Reduce the offending size or count.",
+    ),
+)
+
+DIAGNOSTICS: dict[str, Diagnostic] = {entry.code: entry for entry in _ENTRIES}
+
+
+def explain(code: str) -> str | None:
+    entry = DIAGNOSTICS.get(code.upper())
+    if entry is None:
+        return None
+    return f"{entry.code}: {entry.title}\n\nWhy: {entry.why}\n\nFix: {entry.fix}"