py2max 0.3.3__tar.gz → 0.3.4__tar.gz

{py2max-0.3.3 → py2max-0.3.4}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.3.4]
+
+### New: Param docking in layouts
+
+- `Patcher(..., param_placement=True)` docks value/UI "param" objects (`flonum`, `number`, `message`, `toggle`, `slider`, `dial`, `live.*`) next to the single object they drive, instead of spreading them through the signal graph. During `optimize_layout()`, a param whose outgoing connections all go to one non-param target is placed perpendicular to the signal flow -- above the target for a horizontal flow, to its left for a vertical flow (and to the right / below when the flow hugs that edge) -- ordered by, and for a lone param aligned to, the inlet it feeds, then de-overlapped. Works across every built-in layout (grid, flow, columnar, matrix). Off by default; a control that fans out to more than one object is left in the flow. Implemented as `LayoutManager.place_params()`.
+
+### New: Patch linting and message-type-aware connection validation
+
+- Added `Patcher.lint()` (and the `py2max.lint` module: `lint()`, `Finding`) -- a patch-level health check returning structured findings with a `severity`, a `code`, and object/connection references. It covers invalid connections, out-of-range outlet/inlet indices, orphaned patchlines, duplicate IDs, overlapping objects, off-canvas objects, and unknown object classes.
+- **Linting runs automatically on `save()`**: error-severity findings (bad connections, out-of-range ports, orphaned lines, duplicate IDs) are logged. Pass `Patcher(strict=True)` to raise `InvalidPatchError` on any error instead. Layout warnings (overlaps / off-canvas / unknown objects) are left to an explicit `lint()` or `py2max validate` to keep normal saves quiet. This is on by default and non-breaking -- saves still succeed unless `strict=True`.
+- Connection validation is now **message-type aware and bidirectional**. The previous check only rejected a signal outlet wired into a non-signal inlet; it now also catches a control outlet (a bang from `metro` / `loadbang` / `button`) wired into an oscillator's signal inlet -- e.g. `metro -> cycle~`, which Max rejects. The rules are deliberately conservative (ambiguous cases and maxref-unknown objects are allowed) so on-by-default checking never rejects a valid patch; notably a bang into `adsr~` (a legitimate envelope trigger) is *not* flagged.
+- Port typing is now modeled in `py2max/maxref/porttypes.py`, normalizing maxref's placeholder control types (`OUTLET_TYPE` / `INLET_TYPE`) into message kinds, and resolving **argument-dependent port counts** that maxref reports as the arg-less default -- both value-scaled (`limi~ 2` -> 2 in/out) and arg-count-scaled (`select a b c` -> 4 outlets, `route`, `pack`/`unpack`, `selector~`/`switch`) -- plus curated overrides for the handful of objects maxref mis-types.
+- `py2max validate` (CLI) now reports the full lint result -- errors and warnings with codes -- and exits non-zero on any error.
+- A corpus test re-lints every shipped layout example patch and fails on any error, so Max-invalid wiring can no longer ship unnoticed.
+- Subpatchers are handled: a subpatcher/bpatcher box's inlet/outlet count is derived from the `inlet` / `outlet` objects it contains (not the maxref default), and `lint()` recurses into nested patchers -- findings inside a subpatcher are reported path-qualified (e.g. `sub-box-id/obj-1`).
+- Inlet acceptance is now derived from each object's `<methodlist>` -- its real message vocabulary in Max's own docs -- rather than the placeholder inlet `type` (Cycling '74 ships `INLET_TYPE`/`OUTLET_TYPE` for control ports, so the type attribute alone is useless). This is what distinguishes a bang into `cycle~` (no `bang` method -> rejected) from a bang into `adsr~` (has an `anything` wildcard method -> allowed), replacing hand-curation with data that generalizes to all ~1050 objects that carry method lists. The shipped `bundle.json.gz` was regenerated so no-Max users get the same data (a `test_bundle_method_data_quality` guard prevents a future regeneration from dropping it).
+
 ## [0.3.3]
 
 ### Removed: `serve` and `repl` CLI subcommands

{py2max-0.3.3 → py2max-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py2max
-Version: 0.3.3
+Version: 0.3.4
 Summary: A library for offline generation of Max/MSP patcher (.maxpat) files.
 Keywords: Max,maxpat,offline
 Author: Shakeeb Alireza

{py2max-0.3.3 → py2max-0.3.4}/py2max/__init__.py

@@ -35,7 +35,7 @@ Example:
     >>> p.save()
 """
 
-__version__ = "0.3.3"
+__version__ = "0.3.4"
 
 from .core import Box, Patcher, Patchline
 from .exceptions import (
@@ -48,6 +48,7 @@ from .exceptions import (
     PatcherIOError,
     Py2MaxError,
 )
+from .lint import Finding, lint
 
 __all__ = [
     # Version
@@ -56,6 +57,9 @@ __all__ = [
     "Patcher",
     "Box",
     "Patchline",
+    # Linting
+    "lint",
+    "Finding",
     # Exceptions
     "Py2MaxError",
     "InvalidConnectionError",

{py2max-0.3.3 → py2max-0.3.4}/py2max/cli.py

@@ -15,12 +15,12 @@ try:  # pragma: no cover - optional dependency
 except Exception:  # pragma: no cover - optional dependency
     yaml = None
 
-from .core import Patcher, Patchline
+from .core import Patcher
 from .core.common import Rect
 from .exceptions import Py2MaxError
 from .export import export_svg
 from .export.converters import maxpat_to_python, maxref_to_sqlite
-from .maxref import MaxRefCache, MaxRefDB, validate_connection
+from .maxref import MaxRefCache, MaxRefDB
 from .transformers import available_transformers, create_transformer, run_pipeline
 
 LAYOUT_CHOICES = ["horizontal", "vertical", "grid", "flow", "matrix"]
@@ -230,40 +230,18 @@ def cmd_validate(args: argparse.Namespace) -> int:
     patcher = Patcher.from_file(path)
     _coerce_rect(patcher)
 
-    errors: List[str] = []
-
-    for line in patcher._lines:
-        patchline = cast(Patchline, line)
-        src_id, dst_id = patchline.src, patchline.dst
-        src_port = int(patchline.source[1]) if len(patchline.source) > 1 else 0
-        dst_port = (
-            int(patchline.destination[1]) if len(patchline.destination) > 1 else 0
-        )
-
-        src_obj = patcher._objects.get(src_id)
-        dst_obj = patcher._objects.get(dst_id)
-
-        if not src_obj or not dst_obj:
-            errors.append(f"Dangling connection: {src_id} -> {dst_id}")
-            continue
-
-        src_name = _object_name(src_obj)
-        dst_name = _object_name(dst_obj)
-
-        is_valid, message = validate_connection(src_name, src_port, dst_name, dst_port)
-        if not is_valid:
-            errors.append(
-                f"Invalid connection {src_name}[{src_port}] -> {dst_name}[{dst_port}]: {message}"
-            )
-
-    if errors:
-        print("Connection validation failed:", file=sys.stderr)
-        for error in errors:
-            print(f"  - {error}", file=sys.stderr)
-        return 1
+    findings = patcher.lint()
+    if not findings:
+        print("Patch is clean: no lint findings.")
+        return 0
 
-    print("All connections are valid.")
-    return 0
+    errors = [f for f in findings if f.severity == "error"]
+    warnings = [f for f in findings if f.severity == "warning"]
+    stream = sys.stderr if errors else sys.stdout
+    for finding in findings:
+        print(f"  {finding}", file=stream)
+    print(f"{len(errors)} error(s), {len(warnings)} warning(s).", file=stream)
+    return 1 if errors else 0
 
 
 def _parse_transform_spec(spec: str) -> tuple[str, str | None]:

{py2max-0.3.3 → py2max-0.3.4}/py2max/core/factory.py

@@ -310,7 +310,12 @@ class BoxFactoryMixin(AbstractPatcher):
                 is_valid = not error_msg
             else:
                 is_valid, error_msg = maxref.validate_connection(
-                    src_name, src_outlet, dst_name, dst_inlet
+                    src_name,
+                    src_outlet,
+                    dst_name,
+                    dst_inlet,
+                    src_text=getattr(src_obj, "text", None),
+                    dst_text=getattr(dst_obj, "text", None),
                 )
 
             if not is_valid:

{py2max-0.3.3 → py2max-0.3.4}/py2max/core/patcher.py

@@ -16,7 +16,20 @@ Example:
 import json
 import re
 from pathlib import Path
-from typing import Any, Dict, Iterator, List, Optional, Tuple, Union, cast
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Iterator,
+    List,
+    Optional,
+    Tuple,
+    Union,
+    cast,
+)
+
+if TYPE_CHECKING:
+    from ..lint import Finding
 
 from py2max import layout as layout_module
 from py2max.log import get_logger
@@ -109,6 +122,7 @@ class Patcher(BoxFactoryMixin, SerializationMixin, AbstractPatcher):
         openinpresentation: int = 0,
         validate_connections: bool = False,
         validate_attrs: bool = False,
+        strict: bool = False,
         flow_direction: str = "horizontal",
         cluster_connected: bool = False,
         # Matrix layout configuration parameters
@@ -116,6 +130,7 @@ class Patcher(BoxFactoryMixin, SerializationMixin, AbstractPatcher):
         dimension_spacing: float = 100.0,
         semantic_ids: bool = False,
         device_type: str = "audio_effect",
+        param_placement: bool = False,
     ):
         logger.debug(
             f"Initializing Patcher: path={path}, layout={layout}, "
@@ -143,6 +158,8 @@ class Patcher(BoxFactoryMixin, SerializationMixin, AbstractPatcher):
         self._auto_hints = auto_hints
         self._validate_connections = validate_connections
         self._validate_attrs = validate_attrs
+        self._strict = strict
+        self._param_placement = param_placement
         self._pending_comments: list[
             tuple[str, str, Optional[str]]
         ] = []  # [(box_id, comment_text, comment_pos), ...]
@@ -656,5 +673,20 @@ class Patcher(BoxFactoryMixin, SerializationMixin, AbstractPatcher):
         if hasattr(self._layout_mgr, "optimize_layout"):
             self._layout_mgr.optimize_layout()
 
+        # Dock value/UI params next to the object they drive (opt-in).
+        if self._param_placement and hasattr(self._layout_mgr, "place_params"):
+            self._layout_mgr.place_params()
+
         # Process pending comments after layout optimization
         self._process_pending_comments()
+
+    def lint(self) -> "List[Finding]":
+        """Return patch-level lint findings (errors and warnings), errors first.
+
+        Checks connection validity, out-of-range ports, orphaned patchlines,
+        duplicate IDs, overlapping objects, off-canvas objects, and unknown
+        object classes. See :mod:`py2max.lint`.
+        """
+        from ..lint import lint as _lint
+
+        return _lint(self)

{py2max-0.3.3 → py2max-0.3.4}/py2max/core/serialization.py

@@ -76,6 +76,8 @@ class SerializationMixin(AbstractPatcher):
             ):
                 self.render()
 
+            self._lint_on_save()
+
             # Use resolved path for writing
             if resolved_path.suffix.lower() == ".amxd":
                 # Lazy import: m4l is a feature layer, kept off core's import path.
@@ -107,6 +109,31 @@ class SerializationMixin(AbstractPatcher):
                 operation="write",
             ) from e
 
+    def _lint_on_save(self) -> None:
+        """Lint the top-level patch on save.
+
+        Error-severity findings (bad connections, out-of-range ports, orphaned
+        lines, duplicate IDs) are logged. When the patcher was created with
+        ``strict=True`` they are raised as ``InvalidPatchError`` instead. Layout
+        warnings (overlaps / off-canvas / unknown objects) are left to an
+        explicit ``lint()`` call or ``py2max validate`` to keep saves quiet.
+        """
+        if self._parent:  # only lint the top-level patcher
+            return
+        from ..lint import lint as _lint_patch
+
+        errors = [f for f in _lint_patch(self) if f.severity == "error"]
+        if not errors:
+            return
+        for finding in errors:
+            logger.warning("lint: %s", finding)
+        if getattr(self, "_strict", False):
+            from ..exceptions import InvalidPatchError
+
+            raise InvalidPatchError(
+                f"patch has {len(errors)} validation error(s); first: {errors[0]}"
+            )
+
     def save(self) -> None:
         """Save the patch to the default file path.
 

{py2max-0.3.3 → py2max-0.3.4}/py2max/layout/base.py

@@ -3,7 +3,7 @@
 This module provides the base LayoutManager class that all layout managers inherit from.
 """
 
-from typing import Dict, Optional, Set, cast
+from typing import Any, Dict, List, Optional, Set, Tuple, cast
 
 from py2max.core.abstract import AbstractLayoutManager, AbstractPatcher
 from py2max.core.common import Rect
@@ -14,6 +14,18 @@ from .graph import PatchGraph
 # Threshold for incremental vs full layout (30% of total objects)
 INCREMENTAL_THRESHOLD = 0.3
 
+# Value/UI "param" objects: their role is to set a value on one object's inlet,
+# so they read better docked next to that object than spread through the graph.
+PARAM_MAXCLASSES = frozenset(
+    {"flonum", "number", "message", "toggle", "slider", "dial"}
+)
+
+
+def _is_param(box: object) -> bool:
+    """True for a value/UI control that parameterizes another object."""
+    mc = getattr(box, "maxclass", "") or ""
+    return mc in PARAM_MAXCLASSES or mc.startswith("live.")
+
 
 class LayoutManager(AbstractLayoutManager):
     """Basic horizontal layout manager.
@@ -237,6 +249,115 @@ class LayoutManager(AbstractLayoutManager):
 
         return iterations_performed
 
+    def place_params(self, direction: Optional[str] = None, gap: float = 8.0) -> None:
+        """Dock value/UI 'param' objects next to the single object they drive.
+
+        A param (number box, toggle, slider, dial, message, ``live.*``) whose
+        outgoing connections all go to one non-param target is repositioned
+        adjacent to that target, perpendicular to the signal flow -- above the
+        target for a horizontal flow, to its left for a vertical flow -- and
+        aligned to the inlet it feeds. This keeps value controls with their
+        object instead of spread through the signal graph.
+
+        Runs after the main layout as the final placement pass. ``direction``
+        defaults to the manager's ``flow_direction``.
+        """
+        objects = self.parent._objects
+
+        # outgoing edges per source: source_id -> [(inlet, target_id), ...]
+        out_edges: Dict[str, List[Tuple[int, str]]] = {}
+        for line in self.parent._lines:
+            source = getattr(line, "source", None)
+            destination = getattr(line, "destination", None)
+            if not source or not destination:
+                continue
+            inlet = int(destination[1]) if len(destination) > 1 else 0
+            out_edges.setdefault(source[0], []).append((inlet, destination[0]))
+
+        # a param drives exactly one non-param target -> group by that target
+        by_target: Dict[str, List[Tuple[int, Any]]] = {}
+        for src_id, edges in out_edges.items():
+            box = objects.get(src_id)
+            if box is None or not _is_param(box):
+                continue
+            targets = {t for _, t in edges}
+            if len(targets) != 1:
+                continue
+            target_id = next(iter(targets))
+            target = objects.get(target_id)
+            if target is None or _is_param(target):
+                continue
+            inlet = min(i for i, _ in edges)
+            by_target.setdefault(target_id, []).append((inlet, box))
+
+        if not by_target:
+            return
+
+        direction = direction or getattr(self, "flow_direction", "horizontal")
+        left_side = direction in ("vertical", "column")
+        for target_id, params in by_target.items():
+            params.sort(key=lambda p: p[0])
+            self._dock_params(objects[target_id], params, left_side, gap)
+
+        self.prevent_overlaps()
+
+    def _dock_params(
+        self,
+        target: Any,
+        params: List[Tuple[int, Any]],
+        left_side: bool,
+        gap: float,
+    ) -> None:
+        """Position a target's param satellites (params sorted by inlet).
+
+        Docks on the perpendicular side that has room: left of the target when a
+        vertical flow leaves space, otherwise right; above for a horizontal flow,
+        otherwise below. This keeps params clear of a flow that hugs an edge.
+        """
+        tr = target.patching_rect
+        tx, ty, tw, th = float(tr[0]), float(tr[1]), float(tr[2]), float(tr[3])
+        n_inlets = int(getattr(target, "numinlets", 1) or 1)
+
+        if left_side:
+            max_w = max(float(b.patching_rect[2]) for _, b in params)
+            x = tx - max_w - gap
+            if x < self.pad:  # no room on the left -> dock on the right
+                x = tx + tw + gap
+            y = ty
+            for _, box in params:
+                bw, bh = float(box.patching_rect[2]), float(box.patching_rect[3])
+                box.patching_rect = Rect(x, y, bw, bh)
+                y += bh + gap
+            return
+
+        max_h = max(float(b.patching_rect[3]) for _, b in params)
+        y = ty - max_h - gap
+        if y < self.pad:  # no room above -> dock below
+            y = ty + th + gap
+        if len(params) == 1:
+            inlet, box = params[0]
+            bw = float(box.patching_rect[2])
+            cx = self._inlet_center_x(tx, tw, n_inlets, inlet)
+            box.patching_rect = Rect(
+                max(self.pad, cx - bw / 2), y, bw, box.patching_rect[3]
+            )
+        else:
+            # pack params as a centered row, in inlet order
+            widths = [float(b.patching_rect[2]) for _, b in params]
+            row_w = sum(widths) + gap * (len(params) - 1)
+            x = max(self.pad, tx + tw / 2 - row_w / 2)
+            for (_, box), bw in zip(params, widths):
+                box.patching_rect = Rect(x, y, bw, float(box.patching_rect[3]))
+                x += bw + gap
+
+    @staticmethod
+    def _inlet_center_x(tx: float, tw: float, n_inlets: int, inlet: int) -> float:
+        """Approximate x of the center of ``inlet`` on a box (Max spreads inlets
+        edge-to-edge across the top)."""
+        if n_inlets <= 1:
+            return tx + tw / 2
+        return tx + tw * min(inlet, n_inlets - 1) / (n_inlets - 1)
+
     def get_connected_objects(self, obj_ids: Set[str]) -> Set[str]:
         """Get all objects connected to the given objects via patchlines.
 

py2max-0.3.4/py2max/lint.py

@@ -0,0 +1,226 @@
+"""Patch-level linting: structural and connection health checks.
+
+``lint(patcher)`` returns a list of :class:`Finding`s -- errors and warnings --
+covering connection validity, out-of-range ports, orphaned patchlines,
+duplicate IDs, overlapping objects, off-canvas objects, and unknown object
+classes. It is the productized form of the ad-hoc checks that repeatedly caught
+real bugs, and the basis for on-by-default checking on ``save()``.
+
+Only the top-level patcher is linted; nested subpatchers have their own
+coordinate space and are left to a future recursive pass.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, List, Optional, Tuple
+
+from .maxref import get_object_info
+from .maxref import porttypes
+from .utils import object_name
+
+# --- severities ---
+ERROR = "error"
+WARNING = "warning"
+
+# --- finding codes ---
+E_DUP_ID = "E-DUP-ID"
+E_ORPHAN_LINE = "E-ORPHAN-LINE"
+E_OUTLET_RANGE = "E-OUTLET-RANGE"
+E_INLET_RANGE = "E-INLET-RANGE"
+E_BAD_CONNECTION = "E-BAD-CONNECTION"
+W_OVERLAP = "W-OVERLAP"
+W_OFFCANVAS = "W-OFFCANVAS"
+W_UNKNOWN_OBJECT = "W-UNKNOWN-OBJECT"
+
+
+@dataclass
+class Finding:
+    """A single lint result."""
+
+    code: str
+    severity: str
+    message: str
+    obj_id: Optional[str] = None
+    #: (src_id, outlet, dst_id, inlet) for connection findings
+    line: Optional[Tuple[str, int, str, int]] = None
+
+    def __str__(self) -> str:
+        where = ""
+        if self.line is not None:
+            s, so, d, di = self.line
+            where = f" [{s}:{so} -> {d}:{di}]"
+        elif self.obj_id is not None:
+            where = f" [{self.obj_id}]"
+        return f"{self.severity.upper()} {self.code}: {self.message}{where}"
+
+
+def _overlap(a: Any, b: Any) -> bool:
+    return bool(
+        a[0] < b[0] + b[2]
+        and b[0] < a[0] + a[2]
+        and a[1] < b[1] + b[3]
+        and b[1] < a[1] + a[3]
+    )
+
+
+def _port(pair: Any, idx: int) -> int:
+    """Second element of a source/destination pair, defaulting to 0."""
+    return int(pair[idx]) if len(pair) > idx else 0
+
+
+def _effective_counts(box: Any, name: str) -> Tuple[Optional[int], Optional[int]]:
+    """(inlet_count, outlet_count) for a box, subpatcher-aware."""
+    sub_in, sub_out = porttypes.subpatcher_counts(box)
+    n_in, n_out = porttypes.port_counts(name, getattr(box, "text", None))
+    return (
+        sub_in if sub_in is not None else n_in,
+        sub_out if sub_out is not None else n_out,
+    )
+
+
+def lint(patcher: Any) -> List[Finding]:
+    """Return all lint findings for ``patcher`` and its subpatchers, errors first."""
+    findings: List[Finding] = []
+    _lint_level(patcher, findings, path="")
+    findings.sort(key=lambda f: 0 if f.severity == ERROR else 1)
+    return findings
+
+
+def _lint_level(patcher: Any, findings: List[Finding], path: str) -> None:
+    """Lint one patcher level; recurse into subpatchers.
+
+    ``path`` prefixes object ids so a finding inside ``p sub`` is reported as
+    ``sub-box-id/obj-1`` rather than an ambiguous ``obj-1``.
+    """
+
+    def qid(box_id: str) -> str:
+        return f"{path}{box_id}"
+
+    boxes = list(patcher._boxes)
+    by_id: dict[str, Any] = {}
+
+    # duplicate IDs
+    for b in boxes:
+        if b.id in by_id:
+            findings.append(
+                Finding(
+                    E_DUP_ID, ERROR, f"duplicate object id {b.id!r}", obj_id=qid(b.id)
+                )
+            )
+        else:
+            by_id[b.id] = b
+
+    # unknown object classes
+    for b in boxes:
+        name = object_name(b)
+        if name and get_object_info(name) is None:
+            findings.append(
+                Finding(
+                    W_UNKNOWN_OBJECT,
+                    WARNING,
+                    f"object {name!r} is not in the Max reference",
+                    obj_id=qid(b.id),
+                )
+            )
+
+    # off-canvas: object extends outside the patcher window
+    rect = patcher.rect
+    win_w, win_h = float(rect[2]), float(rect[3])
+    for b in boxes:
+        r = b.patching_rect
+        x, y, w, h = float(r[0]), float(r[1]), float(r[2]), float(r[3])
+        if x < 0 or y < 0 or x + w > win_w or y + h > win_h:
+            findings.append(
+                Finding(
+                    W_OFFCANVAS,
+                    WARNING,
+                    f"object {b.id!r} extends outside the patcher window "
+                    f"({win_w:.0f}x{win_h:.0f})",
+                    obj_id=qid(b.id),
+                )
+            )
+
+    # overlaps (dimension-aware)
+    for i in range(len(boxes)):
+        for j in range(i + 1, len(boxes)):
+            if _overlap(boxes[i].patching_rect, boxes[j].patching_rect):
+                findings.append(
+                    Finding(
+                        W_OVERLAP,
+                        WARNING,
+                        f"objects {boxes[i].id!r} and {boxes[j].id!r} overlap",
+                        obj_id=qid(boxes[i].id),
+                    )
+                )
+
+    # patchlines: orphans, out-of-range ports, message-type compatibility
+    for pl in patcher._lines:
+        src_id, outlet = pl.source[0], _port(pl.source, 1)
+        dst_id, inlet = pl.destination[0], _port(pl.destination, 1)
+        line = (qid(src_id), outlet, qid(dst_id), inlet)
+        sb, db = by_id.get(src_id), by_id.get(dst_id)
+        if sb is None or db is None:
+            findings.append(
+                Finding(
+                    E_ORPHAN_LINE,
+                    ERROR,
+                    "patchline references a missing object",
+                    line=line,
+                )
+            )
+            continue
+
+        src_name, dst_name = object_name(sb), object_name(db)
+        _, n_out = _effective_counts(sb, src_name)
+        n_in, _ = _effective_counts(db, dst_name)
+        if n_out is not None and outlet >= n_out:
+            findings.append(
+                Finding(
+                    E_OUTLET_RANGE,
+                    ERROR,
+                    f"{src_name!r} has {n_out} outlet(s); outlet {outlet} is out of range",
+                    line=line,
+                )
+            )
+            continue
+        if n_in is not None and inlet >= n_in:
+            findings.append(
+                Finding(
+                    E_INLET_RANGE,
+                    ERROR,
+                    f"{dst_name!r} has {n_in} inlet(s); inlet {inlet} is out of range",
+                    line=line,
+                )
+            )
+            continue
+
+        emit = porttypes.outlet_emits(src_name, outlet)
+        accepts, authoritative = porttypes.inlet_acceptance(dst_name, inlet)
+        bang_reject = emit == porttypes.BANG and porttypes.inlet_rejects_bang(
+            dst_name, inlet
+        )
+        if (
+            bang_reject
+            or porttypes.message_compatible(emit, accepts, authoritative) is False
+        ):
+            findings.append(
+                Finding(
+                    E_BAD_CONNECTION,
+                    ERROR,
+                    f"cannot connect {emit} outlet {outlet} of {src_name!r} "
+                    f"to inlet {inlet} of {dst_name!r}",
+                    line=line,
+                )
+            )
+
+    # recurse into subpatchers (each has its own coordinate space)
+    for b in boxes:
+        child = getattr(b, "_patcher", None)
+        if child is not None:
+            _lint_level(child, findings, path=f"{path}{b.id}/")
+
+
+def has_errors(findings: List[Finding]) -> bool:
+    """True if any finding is error-severity."""
+    return any(f.severity == ERROR for f in findings)