PyPI - backstitch - Versions diffs - 0.1.0__py3-none-any.whl - Mend

backstitch 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

backstitch/__init__.py +7 -0
backstitch/__main__.py +8 -0
backstitch/analysis_llm.py +214 -0
backstitch/analysis_packets.py +202 -0
backstitch/analysis_results.py +248 -0
backstitch/cli.py +873 -0
backstitch/config.py +51 -0
backstitch/exclusions.py +526 -0
backstitch/grammar.py +49 -0
backstitch/markdown_specs.py +345 -0
backstitch/models.py +183 -0
backstitch/profiles.py +34 -0
backstitch/prompts/backstitch_style_analysis.md +36 -0
backstitch/py.typed +1 -0
backstitch/python_refs.py +380 -0
backstitch/reporting.py +90 -0
backstitch/resolver.py +926 -0
backstitch/settings.py +620 -0
backstitch/target_roots.py +88 -0
backstitch-0.1.0.dist-info/METADATA +104 -0
backstitch-0.1.0.dist-info/RECORD +24 -0
backstitch-0.1.0.dist-info/WHEEL +4 -0
backstitch-0.1.0.dist-info/entry_points.txt +2 -0
backstitch-0.1.0.dist-info/licenses/LICENSE +21 -0

backstitch/__init__.py ADDED Viewed

@@ -0,0 +1,7 @@
+"""Backstitch package."""
+from __future__ import annotations
+__all__ = ["__version__"]
+__version__ = "0.1.0"

backstitch/__main__.py ADDED Viewed

@@ -0,0 +1,8 @@
+"""Module entry point for `python -m backstitch`."""
+from __future__ import annotations
+from .cli import main
+if __name__ == "__main__":
+    raise SystemExit(main())

backstitch/analysis_llm.py ADDED Viewed

@@ -0,0 +1,214 @@
+"""Semantic analysis over packets through the ``llm`` Python API.
+Spec: docs/specs/02-backstitch-core.md [SC-7], [SC-13]
+The adapter boundary exists so tests prove prompt construction, iteration,
+parsing, and malformed-output handling with fakes; only the default adapter
+touches ``llm`` and real models. Findings are advisory [SC-7].
+"""
+from __future__ import annotations
+import json
+import re
+from collections.abc import Callable, Iterable
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+from backstitch.analysis_results import validate_analysis_row
+ModelAdapter = Callable[[str], str]
+_FENCE_RE = re.compile(r"^```[\w-]*\n(?P<body>.*)\n```\s*$", re.DOTALL)
+def default_adapter(model_name: str | None = None) -> ModelAdapter:
+    """Build the real adapter for an ``llm`` model.
+    With no name, ``llm``'s configured default model is used (whatever
+    ``llm models default`` reports).
+    """
+    import llm
+    model = llm.get_model(model_name) if model_name else llm.get_model()
+    def call(prompt: str) -> str:
+        return str(model.prompt(prompt).text())
+    return call
+def build_prompt(packet: dict[str, Any]) -> str:
+    """Compose the review prompt: instructions, then the bounded packet."""
+    body = {k: v for k, v in packet.items() if k != "instructions"}
+    return f"{packet['instructions']}\n\n{json.dumps(body)}"
+def _packet_evidence_bounds(
+    packet: dict[str, Any],
+) -> dict[str, tuple[tuple[int, int], ...]]:
+    """What the model was shown, as path -> allowed line ranges ([SC-7]).
+    Owner snippets and the spec section text are line-bounded, so evidence
+    must fall inside one of those ranges. Linked tests are named by PATH
+    only -- the model never saw their content, so a path with no ranges is
+    known to the packet but cannot carry line evidence.
+    """
+    bounds: dict[str, list[tuple[int, int]]] = {}
+    spec_path = packet.get("spec_path")
+    # Blank paths never name a packet member: an empty or whitespace-only
+    # string must not become a citable evidence path (load-time validation
+    # rejects these, but analyze_packets is also a library entry point).
+    if isinstance(spec_path, str) and spec_path.strip():
+        ranges = bounds.setdefault(spec_path, [])
+        start = packet.get("section_start_line")
+        text = packet.get("section_text")
+        if isinstance(start, int) and isinstance(text, str) and text.splitlines():
+            ranges.append((start, start + len(text.splitlines()) - 1))
+    for test in packet.get("tests", ()):
+        if isinstance(test, str) and test.strip():
+            bounds.setdefault(test, [])
+    for owner in packet.get("owners", ()):
+        if (
+            not isinstance(owner, dict)
+            or not isinstance(owner.get("path"), str)
+            or not owner["path"].strip()
+        ):
+            continue
+        ranges = bounds.setdefault(owner["path"], [])
+        start = owner.get("start_line")
+        snippet = owner.get("snippet")
+        # An EMPTY snippet (directory mappings) showed no line content:
+        # like tests, the path is known but carries no valid line evidence.
+        if isinstance(start, int) and isinstance(snippet, str) and snippet.splitlines():
+            ranges.append((start, start + len(snippet.splitlines()) - 1))
+    return {path: tuple(ranges) for path, ranges in bounds.items()}
+def _parse_model_output(raw: str, packet: dict[str, Any]) -> dict[str, Any] | str:
+    packet_id = packet["packet_id"]
+    text = raw.strip()
+    fence = _FENCE_RE.match(text)
+    if fence:
+        text = fence.group("body").strip()
+    try:
+        row = json.loads(text)
+    except json.JSONDecodeError:
+        return "model output is not valid JSON"
+    validated = validate_analysis_row(
+        row, None, allowed_evidence=_packet_evidence_bounds(packet)
+    )
+    if isinstance(validated, str):
+        return f"model output invalid: {validated}"
+    if validated.packet_id != packet_id:
+        return (
+            f"model output packet_id `{validated.packet_id}` does not match the packet"
+        )
+    assert isinstance(row, dict)
+    return row
+def _error_record(packet_id: str, message: str) -> dict[str, Any]:
+    # [SC-7]: one bad response yields one `ambiguous`/error record for the
+    # packet -- a consumer of the results JSONL never loses a packet-level
+    # result to a model failure. `packet_id` comes from the packet, never
+    # the response, and the record passes validate_analysis_row.
+    return {
+        "packet_id": packet_id,
+        "classification": "ambiguous",
+        "summary": f"analysis error: {message}",
+        "rationale": message,
+        "evidence": [],
+        "error": message,
+    }
+def analyze_packets(
+    packets: Iterable[dict[str, Any]],
+    adapter: ModelAdapter,
+    concurrency: int = 1,
+) -> tuple[list[dict[str, Any]], list[str]]:
+    """Run the adapter over every packet; collect rows and per-packet errors.
+    Every packet yields exactly one row: a failed packet yields an
+    `ambiguous`/error record ([SC-7]) and its message is also collected in
+    ``errors`` for stderr. Output rows keep packet order regardless of
+    concurrency. A failure on one packet never aborts the others.
+    """
+    packet_list = list(packets)
+    def run_one(packet: dict[str, Any]) -> tuple[dict[str, Any], str | None]:
+        packet_id = packet.get("packet_id", "<missing packet_id>")
+        if "instructions" not in packet:
+            message = "packet has no `instructions` field"
+            return _error_record(packet_id, message), f"{packet_id}: {message}"
+        try:
+            raw = adapter(build_prompt(packet))
+        except Exception as exc:  # noqa: BLE001 - adapter is an external boundary
+            message = f"model call failed: {exc}"
+            return _error_record(packet_id, message), f"{packet_id}: {message}"
+        parsed = _parse_model_output(raw, packet)
+        if isinstance(parsed, str):
+            return _error_record(packet_id, parsed), f"{packet_id}: {parsed}"
+        return parsed, None
+    if concurrency <= 1:
+        outcomes = [run_one(packet) for packet in packet_list]
+    else:
+        with ThreadPoolExecutor(max_workers=concurrency) as pool:
+            outcomes = list(pool.map(run_one, packet_list))
+    rows = [row for row, _ in outcomes]
+    errors = [error for _, error in outcomes if error is not None]
+    return rows, errors
+def analyze_exit_code(rows: list[dict[str, Any]], errors: list[str]) -> int:
+    """Exit 2 when analysis produced nothing but failures; 0 otherwise.
+    [SC-5]: exit 1 is reserved for deterministic findings about the target
+    repository, and semantic findings are advisory -- `analyze` never
+    returns 1. Total failure (every packet errored; rows include the
+    per-packet error records) is a statement about the tool or the model,
+    so it is exit 2. Partial failure still exits 0 because the output is
+    usable; total failure must be scriptable without scraping stderr.
+    """
+    return 2 if errors and len(errors) == len(rows) else 0
+def render_results_jsonl(rows: list[dict[str, Any]]) -> str:
+    """Render analysis rows as JSONL, one result per line."""
+    return "".join(json.dumps(row) + "\n" for row in rows)
+def resolve_model_name(
+    explicit: str | None = None,
+    *,
+    configured: str | None = None,
+) -> str | None:
+    """[CFG-5] model precedence: --model, LLM_MODEL, config, llm default.
+    CLI beats env beats config -- [CFG-5]'s assembly order puts environment
+    variables ABOVE the config file, so `LLM_MODEL` overrides
+    `analyze.model` whenever --model is omitted.
+    Returns ``None`` to mean "let ``llm`` use its configured default" so the
+    lazy-import boundary stays in ``default_adapter``.
+    """
+    import os
+    if explicit is not None and explicit.strip():
+        return explicit.strip()
+    env = os.environ.get("LLM_MODEL", "").strip()
+    if env:
+        return env
+    if configured is not None and configured.strip():
+        return configured.strip()
+    return None

backstitch/analysis_packets.py ADDED Viewed

@@ -0,0 +1,202 @@
+"""Bounded semantic-review packet generation from deterministic results.
+Spec: docs/specs/02-backstitch-core.md [SC-6], [SC-7]
+Packets are the semantic review boundary: the model judges only what a
+packet contains and never roams the repository [SC-7]. Generation is
+deterministic and never calls ``llm``.
+"""
+from __future__ import annotations
+import dataclasses
+import json
+from importlib import resources
+from pathlib import Path
+from typing import Any
+from backstitch.config import ProfileConfig
+from backstitch.models import Report, SpecSection
+from backstitch.python_refs import python_symbol_spans
+from backstitch.resolver import scan_repository
+MAX_SNIPPET_LINES = 120
+MAX_OWNERS_PER_PACKET = 8
+MAX_SECTION_LINES = 100
+def _instructions() -> str:
+    return (
+        resources.files("backstitch") / "prompts" / "backstitch_style_analysis.md"
+    ).read_text(encoding="utf-8")
+def _is_test_path(path: str) -> bool:
+    pure = Path(path)
+    if pure.name.startswith("test_"):
+        return True
+    return bool(pure.parts) and pure.parts[0] == "tests"
+def _section_text(
+    section: SpecSection,
+    file_lines: list[str],
+    siblings: list[SpecSection],
+    warnings: list[str],
+) -> str:
+    if section.kind != "heading":
+        line = file_lines[section.line - 1] if section.line <= len(file_lines) else ""
+        return line.strip()
+    next_headings = [
+        s.line for s in siblings if s.kind == "heading" and s.line > section.line
+    ]
+    end = min(next_headings) - 1 if next_headings else len(file_lines)
+    block = file_lines[section.line - 1 : end]
+    if len(block) > MAX_SECTION_LINES:
+        block = block[:MAX_SECTION_LINES]
+        warnings.append(f"section text truncated to {MAX_SECTION_LINES} lines")
+    return "\n".join(block).rstrip()
+def _owner_snippet(
+    repo_root: Path,
+    path: str,
+    symbol: str | None,
+    warnings: list[str],
+) -> tuple[str, int]:
+    target = repo_root / path
+    if not target.is_file():
+        warnings.append(f"owner `{path}` is not a file; no snippet included")
+        return "", 1
+    try:
+        lines = target.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError as exc:
+        warnings.append(f"owner `{path}` could not be read ({exc})")
+        return "", 1
+    start = 1
+    if symbol is not None and path.endswith(".py"):
+        spans = python_symbol_spans(target)
+        span = spans.get(symbol) if spans else None
+        if span is not None:
+            start, end = span
+            lines = lines[start - 1 : end]
+        else:
+            warnings.append(f"symbol `{symbol}` not found in `{path}`; using file head")
+    if len(lines) > MAX_SNIPPET_LINES:
+        lines = lines[:MAX_SNIPPET_LINES]
+        warnings.append(f"snippet for `{path}` truncated to {MAX_SNIPPET_LINES} lines")
+    return "\n".join(lines), start
+def generate_packets(
+    repo_root: Path,
+    profile: ProfileConfig,
+    report: Report | None = None,
+) -> list[dict[str, Any]]:
+    """Generate one packet per spec section that has resolved edges."""
+    root = repo_root.resolve()
+    if report is None:
+        report = scan_repository(root, profile)
+    instructions = _instructions()
+    sections_by_file: dict[str, list[SpecSection]] = {}
+    for section in report.spec_sections:
+        sections_by_file.setdefault(section.path, []).append(section)
+    spec_lines: dict[str, list[str]] = {}
+    for path in sections_by_file:
+        spec_lines[path] = (
+            (root / path).read_text(encoding="utf-8", errors="replace").splitlines()
+        )
+    edges_by_key: dict[tuple[str, str], list] = {}
+    for edge in report.edges:
+        edges_by_key.setdefault((edge.spec_path, edge.section_id), []).append(edge)
+    packets: list[dict[str, Any]] = []
+    seen_keys: set[tuple[str, str]] = set()
+    for section in report.spec_sections:
+        key = (section.path, section.section_id)
+        if key in seen_keys:
+            continue
+        seen_keys.add(key)
+        edges = edges_by_key.get(key, [])
+        if not edges:
+            continue
+        warnings: list[str] = []
+        owner_keys: list[tuple[str, str | None]] = []
+        tests: list[str] = []
+        for edge in edges:
+            if edge.kind == "backlink" and _is_test_path(edge.code_path):
+                if edge.code_path not in tests:
+                    tests.append(edge.code_path)
+                continue
+            symbol = edge.code_symbol
+            if edge.kind == "backlink" and symbol == "module":
+                symbol = None
+            owner_key = (edge.code_path, symbol)
+            if owner_key not in owner_keys:
+                owner_keys.append(owner_key)
+        if len(owner_keys) > MAX_OWNERS_PER_PACKET:
+            omitted = len(owner_keys) - MAX_OWNERS_PER_PACKET
+            owner_keys = owner_keys[:MAX_OWNERS_PER_PACKET]
+            warnings.append(f"{omitted} additional owners omitted")
+        owners = []
+        for path, symbol in owner_keys:
+            snippet, start_line = _owner_snippet(root, path, symbol, warnings)
+            owners.append(
+                {
+                    "path": path,
+                    "symbol": symbol,
+                    "start_line": start_line,
+                    "snippet": snippet,
+                }
+            )
+        owner_paths = {path for path, _ in owner_keys}
+        issues = [
+            dataclasses.asdict(issue)
+            for issue in report.issues
+            if issue.section_id == section.section_id
+            and (
+                issue.path == section.path
+                or issue.path in owner_paths
+                or issue.path in tests
+            )
+        ]
+        packets.append(
+            {
+                "packet_id": f"{section.path}#{section.section_id}",
+                "spec_path": section.path,
+                "section_id": section.section_id,
+                "title": section.title,
+                "section_text": _section_text(
+                    section,
+                    spec_lines[section.path],
+                    sections_by_file[section.path],
+                    warnings,
+                ),
+                # [SC-6]: the section's starting line anchors evidence
+                # line-locality checks against the shown section text.
+                "section_start_line": section.line,
+                "owners": owners,
+                "tests": tests,
+                "issues": issues,
+                # [SC-6] field name is contractual: consumers look for
+                # `packet_warnings` for truncation/omission context.
+                "packet_warnings": warnings,
+                "instructions": instructions,
+            }
+        )
+    return packets
+def render_packets_jsonl(packets: list[dict[str, Any]]) -> str:
+    """Render packets as JSONL, one packet per line."""
+    return "".join(json.dumps(packet) + "\n" for packet in packets)

backstitch/analysis_results.py ADDED Viewed

@@ -0,0 +1,248 @@
+"""Validation and aggregation of semantic analysis results.
+Spec: docs/specs/02-backstitch-core.md [SC-6], [SC-7], [SC-13]
+Invalid analysis rows are analysis-summary errors, never repository trace
+errors, and semantic findings never change deterministic issue severity.
+"""
+from __future__ import annotations
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+CLASSIFICATIONS = (
+    "ok",
+    "confirmed_mismatch",
+    "probable_mismatch",
+    "missing_trace",
+    "ambiguous",
+)
+@dataclass(frozen=True, slots=True)
+class AnalysisResult:
+    """One validated semantic finding for a packet."""
+    packet_id: str
+    classification: str
+    confidence: float | None
+    rationale: str
+    evidence: tuple[tuple[str, int], ...]
+    summary: str
+@dataclass(frozen=True, slots=True)
+class AnalysisLoad:
+    """Validated results plus row-level input problems."""
+    results: tuple[AnalysisResult, ...]
+    errors: tuple[str, ...]
+def validate_analysis_row(
+    row: Any,
+    known_packet_ids: set[str] | None,
+    *,
+    allowed_evidence: Mapping[str, tuple[tuple[int, int], ...]] | None = None,
+) -> AnalysisResult | str:
+    """Validate one untrusted model-output row ([SC-7]).
+    ``allowed_evidence``, when provided, keeps evidence packet-local: the
+    model may only cite paths that were in the packet it was shown, and
+    only lines inside one of that path's ``(start, end)`` inclusive
+    ranges. An empty range tuple means the path was named in the packet
+    WITHOUT line-bounded content (linked tests): it cannot carry line
+    evidence at all -- any cited line there is fabricated.
+    """
+    if not isinstance(row, dict):
+        return "row is not a JSON object"
+    packet_id = row.get("packet_id")
+    if not isinstance(packet_id, str) or not packet_id.strip():
+        return "missing or invalid `packet_id`"
+    if known_packet_ids is not None and packet_id not in known_packet_ids:
+        return f"unknown packet ID `{packet_id}`"
+    classification = row.get("classification")
+    if classification not in CLASSIFICATIONS:
+        return (
+            f"unsupported classification {classification!r}; expected one of"
+            f" {', '.join(CLASSIFICATIONS)}"
+        )
+    summary = row.get("summary")
+    if not isinstance(summary, str) or not summary.strip():
+        # Blank means absent, same as locators and rationales.
+        return "missing or invalid `summary`"
+    confidence = row.get("confidence")
+    if confidence is not None and (
+        isinstance(confidence, bool)
+        or not isinstance(confidence, int | float)
+        or not 0.0 <= confidence <= 1.0
+    ):
+        # The prompt contract asks for a confidence between 0 and 1;
+        # anything else is a malformed row, not a very confident one.
+        return "invalid `confidence`; expected a number between 0 and 1"
+    rationale = row.get("rationale", "")
+    if not isinstance(rationale, str):
+        return "invalid `rationale`; expected a string"
+    if confidence is None and not rationale.strip():
+        # The [SC-7] record contract requires a confidence OR rationale
+        # field; a row carrying neither is malformed, not low-effort.
+        return "missing `confidence` or `rationale`; rows must carry at least one"
+    evidence_raw = row.get("evidence")
+    evidence: list[tuple[str, int]] = []
+    if not isinstance(evidence_raw, list):
+        # `evidence` is a required key (an empty list is a valid value:
+        # it states explicitly that no evidence is cited).
+        return "missing or invalid `evidence`; expected a list"
+    for item in evidence_raw:
+        if (
+            not isinstance(item, dict)
+            or not isinstance(item.get("path"), str)
+            or not item["path"].strip()
+            or isinstance(item.get("line"), bool)
+            or not isinstance(item.get("line"), int)
+            or item["line"] < 1
+        ):
+            return "invalid `evidence` item; expected {non-empty path, line >= 1}"
+        if allowed_evidence is not None:
+            # [SC-7]: model output is untrusted; evidence must stay inside
+            # the packet boundary -- both the path and the line.
+            ranges = allowed_evidence.get(item["path"])
+            if ranges is None:
+                return f"evidence path `{item['path']}` is not part of the packet"
+            if not ranges:
+                return (
+                    f"evidence line {item['line']} in `{item['path']}` is"
+                    " fabricated: the packet named this path without"
+                    " line-bounded content"
+                )
+            if not any(start <= item["line"] <= end for start, end in ranges):
+                return (
+                    f"evidence line {item['line']} in `{item['path']}` is"
+                    " outside the packet's shown content"
+                )
+        evidence.append((item["path"], item["line"]))
+    return AnalysisResult(
+        packet_id=packet_id,
+        classification=classification,
+        confidence=float(confidence) if confidence is not None else None,
+        rationale=rationale,
+        evidence=tuple(evidence),
+        summary=summary,
+    )
+def load_analysis_results(text: str, known_packet_ids: set[str] | None) -> AnalysisLoad:
+    """Parse analysis JSONL; bad rows become errors, not exceptions."""
+    results: list[AnalysisResult] = []
+    errors: list[str] = []
+    for line_no, line in enumerate(text.splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError as exc:
+            errors.append(f"line {line_no}: invalid JSON ({exc.msg})")
+            continue
+        validated = validate_analysis_row(row, known_packet_ids)
+        if isinstance(validated, str):
+            errors.append(f"line {line_no}: {validated}")
+        else:
+            results.append(validated)
+    return AnalysisLoad(results=tuple(results), errors=tuple(errors))
+def packet_ids_from_report(report_data: dict[str, Any]) -> set[str]:
+    """Derive valid packet IDs from a deterministic report.
+    Packet generation ([SC-6]) emits a packet only for sections that have
+    at least one trace edge, so the valid-ID universe is edge-bearing
+    sections -- a forged analysis row for a section that never produced a
+    packet must be rejected, not summarized.
+    """
+    return {
+        f"{edge['spec_path']}#{edge['section_id']}"
+        for edge in report_data.get("edges", [])
+    }
+def render_analysis_summary(summary: Mapping[str, int], load: AnalysisLoad) -> str:
+    """Render deterministic and semantic findings, kept clearly separate.
+    ``summary`` is the deterministic report's counts mapping — either
+    ``Report.summary()`` or the ``summary`` key of a parsed JSON report.
+    Structurally valid JSON missing the count keys is malformed input
+    ([SC-5]): raise a one-line ``ValueError`` for the CLI to map to exit 2,
+    never a ``KeyError`` traceback (known fable defect fixed at port time).
+    """
+    # The [SC-6] summary contract has six count keys, not just the three
+    # this renderer happens to print.
+    count_keys = (
+        "spec_sections",
+        "code_refs",
+        "spec_mappings",
+        "errors",
+        "warnings",
+        "infos",
+    )
+    missing = [key for key in count_keys if key not in summary]
+    if missing:
+        msg = (
+            "deterministic report summary is missing required count"
+            f" keys: {', '.join(missing)}"
+        )
+        raise ValueError(msg)
+    bad = [
+        key
+        for key in count_keys
+        if isinstance(summary[key], bool)
+        or not isinstance(summary[key], int)
+        or summary[key] < 0
+    ]
+    if bad:
+        # Counts are non-negative integers; anything else would render a
+        # nonsense line like "[] warnings" instead of failing the input.
+        msg = f"deterministic report summary has non-count values for: {', '.join(bad)}"
+        raise ValueError(msg)
+    lines = [
+        "backstitch analysis summary",
+        "",
+        (
+            f"deterministic: {summary['errors']} errors,"
+            f" {summary['warnings']} warnings, {summary['infos']} infos"
+            " (unchanged by semantic analysis)"
+        ),
+        "",
+        "semantic findings (advisory):",
+    ]
+    if load.results:
+        counts: dict[str, int] = {}
+        for result in load.results:
+            counts[result.classification] = counts.get(result.classification, 0) + 1
+        lines.append(
+            "  " + ", ".join(f"{counts[c]} {c}" for c in CLASSIFICATIONS if c in counts)
+        )
+        for result in load.results:
+            confidence = (
+                f" (confidence {result.confidence:.2f})"
+                if result.confidence is not None
+                else ""
+            )
+            lines.append(
+                f"  {result.packet_id} [{result.classification}]"
+                f" {result.summary}{confidence}"
+            )
+    else:
+        lines.append("  none")
+    if load.errors:
+        lines.append("")
+        lines.append("analysis input problems:")
+        lines.extend(f"  {error}" for error in load.errors)
+    return "\n".join(lines) + "\n"