vinsynlib 0.2.0__py3-none-any.whl

vinsynlib/conformance.py

@@ -0,0 +1,274 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+# SPDX-FileCopyrightText: Copyright (C) 2026  vinsynlib contributors
+#
+# This file is part of vinsynlib.
+#
+# vinsynlib is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 2 of the License, or (at your option)
+# any later version.
+#
+# vinsynlib is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+# more details.
+
+"""The checks that keep the family one family.
+
+Each function here answers one question and returns the problems it found
+as a list of sentences, so a project's test can be the whole contract in a
+dozen lines:
+
+    from vinsynlib import conformance
+
+    def test_the_family_contract():
+        problems = (
+            conformance.check_flags(build_parser(), required={"port", "demo"})
+            + conformance.check_bindings(X5dedApp, channel=True)
+            + conformance.check_legend(KEY_HINTS)
+        )
+        assert not problems, "\\n".join(problems)
+
+Returning sentences rather than asserting is deliberate. A test that says
+``--midi-channel is not a name this family uses; use --device-channel`` is
+worth more than one that says ``False``.
+
+What is checked, and why only these:
+
+* **Flags.** The name, the help text and the old spelling all come from
+  :mod:`vinsynlib.spec`, so a tool cannot quietly reword ``--scan`` or drop
+  its alias without a test noticing.
+* **Bindings.** The shared keys bind the shared actions. A tool that
+  renames ``f`` has to say why, in its own test.
+* **The legend.** The shared blocks appear, in the shared order, and the
+  tool's own hints sit in the one place the family leaves room for them --
+  because a legend is a promise about which keys work, and a promise that
+  drifts is worse than no promise.
+* **Terms.** The tool declared its vocabulary, and the words it uses for
+  the concepts it has are the declared ones.
+
+Not checked, deliberately: the hardware. Which bank byte selects what is
+the instrument's business and the family's has no opinion.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+from typing import Any
+
+from . import keys as keys_module
+from . import spec
+from .terms import Terminology
+
+__all__ = [
+    "check_bindings",
+    "check_flags",
+    "check_legend",
+    "check_terms",
+]
+
+
+def check_flags(
+    parser: argparse.ArgumentParser,
+    *,
+    required: Sequence[str] = (),
+    forbidden: Sequence[str] = (),
+) -> list[str]:
+    """Every required option present, worded the family's way.
+
+    ``required`` names canonical flags from :data:`spec.CANONICAL_FLAGS`.
+    A required flag that is missing, or present with help text that does not
+    start with the family's help text, or present without its documented older
+    spelling, is a problem.
+    """
+    problems: list[str] = []
+    known = {action.dest: action for action in parser._actions}
+    by_name = {f.name: f for f in spec.CANONICAL_FLAGS}
+
+    for name in required:
+        flag = by_name.get(name)
+        if flag is None:
+            problems.append(
+                f"{name!r} is not a flag this family uses; have "
+                f"{', '.join(sorted(by_name))}"
+            )
+            continue
+        action = known.get(flag.name.replace("-", "_"))
+        if action is None:
+            problems.append(f"--{name} is missing")
+            continue
+        action_help = action.help or ""
+        # The family's help, verbatim; the family's help plus a tool's own
+        # sentence appended; or, for a tool with no settings cache, the
+        # variant the spec declares for exactly that case. Nothing else -- a
+        # shorter prefix is not accepted, so a tool cannot quietly drop half a
+        # flag's help and still pass.
+        accepted = [flag.help]
+        if flag.help_without_config:
+            accepted.append(flag.help_without_config)
+        if not (action_help in accepted or action_help.startswith(flag.help)):
+            problems.append(
+                f"--{name} help text does not match the family's:\n"
+                f"    family: {' or '.join(accepted)}\n"
+                f"    here:   {action_help}"
+            )
+        present = set(action.option_strings)
+        missing = set(flag.options()) - present
+        if missing:
+            problems.append(
+                f"--{name} no longer accepts "
+                f"{', '.join(sorted(missing))}; older command lines use it"
+            )
+
+    for name in forbidden:
+        if name.replace("-", "_") in known:
+            problems.append(f"--{name} should not be offered by this tool")
+
+    return problems
+
+
+def _bindings_of(app: Any) -> dict[str, str]:
+    """``key -> action name`` for one App class."""
+    out: dict[str, str] = {}
+    for binding in getattr(app, "BINDINGS", []):
+        key = getattr(binding, "key", None)
+        action = getattr(binding, "action", None)
+        if key and isinstance(action, str):
+            out[key] = action
+    return out
+
+
+def _shared(
+    tier: str,
+    *,
+    favourites: bool,
+    channel: bool,
+    select: bool,
+) -> list[keys_module.Key]:
+    """The shared keys that apply to a tool with these concepts.
+
+    One place decides what "applies" means, so that the key check and the
+    action check cannot drift into disagreeing about which keys a tool is
+    being asked about.
+    """
+    table = (
+        keys_module.EDITOR_KEYS
+        if tier == "editor"
+        else keys_module.BROWSER_KEYS
+    )
+    if tier != "editor" and favourites:
+        table = table + keys_module.FAVOURITE_KEYS
+
+    wanted: list[keys_module.Key] = []
+    for key in table:
+        if key.key == "enter" and not select:
+            continue
+        if not channel and key.legend in ("[ ] channel", "c set channel"):
+            continue
+        wanted.append(key)
+    return wanted
+
+
+def check_bindings(
+    app: Any,
+    *,
+    tier: str = "browser",
+    favourites: bool = True,
+    channel: bool = True,
+    select: bool = True,
+) -> list[str]:
+    """The shared keys bind the shared actions, or say why not.
+
+    The keyword flags mirror :func:`keys.legend`: a tool without a
+    favourites store is not asked for ``f``.
+    """
+    have = _bindings_of(app)
+    problems: list[str] = []
+
+    # The key side: is the family's key bound to the family's action?
+    shared = _shared(
+        tier, favourites=favourites, channel=channel, select=select
+    )
+    for key in shared:
+        action = have.get(key.key)
+        if action is None:
+            problems.append(
+                f"{key.key} is not bound; the family binds it to {key.action}"
+            )
+        elif action != key.action:
+            problems.append(
+                f"{key.key} is bound to {action}; the family binds it to "
+                f"{key.action}"
+            )
+
+    # The action side: where did each family action actually go? A key that
+    # has been *renamed* -- f moved to a -- leaves every family key unbound,
+    # and checking only the keys would report a list of unbound keys and say
+    # nothing about where the action went.
+    where: dict[str, list[str]] = {}
+    for app_key, action in have.items():
+        where.setdefault(action, []).append(app_key)
+    for key in shared:
+        if key.key in where.get(key.action, []):
+            continue
+        elsewhere = ", ".join(sorted(where.get(key.action, []))) or "nothing"
+        problems.append(
+            f"{key.action} is not reachable from {key.key}; it is bound to "
+            f"{elsewhere}"
+        )
+    return problems
+
+
+def check_legend(
+    blocks: Sequence[str],
+    *,
+    extras: Sequence[str] = (),
+    favourites: bool = True,
+    channel: bool = True,
+    select: bool = True,
+) -> list[str]:
+    """The shared hints appear, in the shared order, with extras in place."""
+    expected = keys_module.legend(
+        extras, favourites=favourites, channel=channel, select=select
+    )
+    problems: list[str] = []
+    for hint in expected:
+        if hint not in blocks:
+            problems.append(f"the legend is missing {hint!r}")
+    for hint in blocks:
+        if hint not in expected:
+            problems.append(
+                f"the legend shows {hint!r}, which is not in the family's"
+            )
+    shared = [
+        b for b in blocks if b in keys_module.CANONICAL_LEGEND or b in extras
+    ]
+    order = [
+        b
+        for b in keys_module.legend(
+            extras, favourites=favourites, channel=channel, select=select
+        )
+        if b in shared
+    ]
+    if [b for b in shared if b in order] != order:
+        problems.append(
+            "the legend's hints are not in the family's order: expected "
+            + ", ".join(order)
+        )
+    return problems
+
+
+def check_terms(terms: Terminology) -> list[str]:
+    """The declared vocabulary is the one the family allows."""
+    problems: list[str] = []
+    try:
+        Terminology(
+            app_name=terms.app_name,
+            sound=terms.sound,
+            container=terms.container,
+            device=terms.device,
+        )
+    except ValueError as exc:
+        problems.append(str(exc))
+    return problems

vinsynlib/devchecks.py

@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+# SPDX-FileCopyrightText: Copyright (C) 2026  vinsynlib contributors
+#
+# This file is part of vinsynlib.
+#
+# vinsynlib is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 2 of the License, or (at your option)
+# any later version.
+#
+# vinsynlib is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+# more details.
+
+"""Checks every project in the family should be running, written once.
+
+These are not lints. They are the invariants that let nine separately
+developed programs stay one family, and each of them was a bug that
+actually happened here:
+
+**A test must not write ``config.toml`` into the checkout.** The path is
+relative, on purpose -- it is a disposable per-checkout cache -- and being
+gitignored is exactly what makes this worth checking rather than
+remembering. One was found next to the source, dated during a test run.
+
+**A project must not import another project in the family.** ``emorphed``
+had a function that imported ``nano.config``: ``nanosyned``'s package,
+which of course is not installed next to it. It was a copy-paste slip from
+the sibling the function was ported from, and it would have raised
+``ImportError`` the moment ``--config`` was used.
+
+**A project's public vocabulary must be declared.** A tool that has not
+said what its instrument calls a stored sound has not finished being part
+of this family, and a default would let it drift unnoticed.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import sys
+from collections.abc import Iterable, Iterator, Sequence
+
+__all__ = [
+    "FAMILY_THIRD_PARTY",
+    "check_foreign_imports",
+    "config_saves_without_path",
+    "foreign_imports",
+    "iter_test_sources",
+]
+
+#: Third-party modules every project in the family legitimately imports.
+FAMILY_THIRD_PARTY = frozenset({"textual", "rtmidi", "rich", "vinsynlib"})
+
+
+def iter_test_sources(test_dir: str) -> Iterator[tuple[str, ast.Module]]:
+    """Every test module in a directory, as ``(filename, parsed)``."""
+    for name in sorted(os.listdir(test_dir)):
+        if not (name.startswith("test_") and name.endswith(".py")):
+            continue
+        path = os.path.join(test_dir, name)
+        with open(path, encoding="utf-8") as handle:
+            yield name, ast.parse(handle.read())
+
+
+def config_saves_without_path(test_dir: str) -> list[str]:
+    """Test calls of ``config.save_*`` that do not name a file.
+
+    Returns one ``file:lineno name`` string per offender. A save with no
+    path writes ``config.toml`` into whatever directory pytest was started
+    from, which is the checkout in practice.
+    """
+    offenders: list[str] = []
+    for name, tree in iter_test_sources(test_dir):
+        for node in ast.walk(tree):
+            if not (
+                isinstance(node, ast.Call)
+                and isinstance(node.func, ast.Attribute)
+                and node.func.attr.startswith("save_")
+                and isinstance(node.func.value, ast.Name)
+                and node.func.value.id == "config"
+            ):
+                continue
+            named = len(node.args) >= 2 or any(
+                kw.arg == "path" for kw in node.keywords
+            )
+            if not named:
+                offenders.append(f"{name}:{node.lineno} {node.func.attr}")
+    return offenders
+
+
+def own_namespaces(*packages: str) -> frozenset[str]:
+    """The top-level names a project owns, given its package names."""
+    return frozenset(packages)
+
+
+def foreign_imports(
+    path: str,
+    *,
+    own: Iterable[str],
+    third_party: Iterable[str] = FAMILY_THIRD_PARTY,
+) -> list[str]:
+    """Top-level imports in one file that belong to nobody here.
+
+    A name is foreign when it is not the standard library, not one of this
+    project's own packages, and not in the third-party allow-list. The
+    point is to catch a sibling project's package name in a function that
+    was ported from it -- an import that works in the project it was copied
+    from and raises ``ImportError`` in this one.
+    """
+    allowed = set(own) | set(third_party)
+    stdlib: frozenset[str] = getattr(sys, "stdlib_module_names", frozenset())
+    with open(path, encoding="utf-8") as handle:
+        tree = ast.parse(handle.read())
+
+    found: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            names = [alias.name for alias in node.names]
+        elif isinstance(node, ast.ImportFrom):
+            # `from . import x` has no module: a relative import is by
+            # definition this project's own.
+            if node.level:
+                continue
+            names = [node.module or ""]
+        else:
+            continue
+        for full in names:
+            top = full.split(".")[0]
+            if not top or top in allowed or top in stdlib:
+                continue
+            found.append(f"{os.path.basename(path)}:{node.lineno} {full}")
+
+    return sorted(set(found))
+
+
+def check_foreign_imports(
+    paths: Sequence[str],
+    *,
+    own: Iterable[str],
+    third_party: Iterable[str] = FAMILY_THIRD_PARTY,
+) -> list[str]:
+    """:func:`foreign_imports` over several files."""
+    out: list[str] = []
+    for path in paths:
+        out.extend(foreign_imports(path, own=own, third_party=third_party))
+    return out