eops-368-refactor(commands): drop explanatory comments and docstrings

Author: mykhaylob-de

scripts/refresh_v2_routes.py

@@ -1,20 +1,5 @@
 #!/usr/bin/env python3
-"""
-Regenerate the committed snapshot of the public API v2 route table.
-
-The CLI lives in its own repository, so it cannot import the backend to learn
-which routes exist. tests/test_route_conformance.py therefore checks the
-registered commands against a committed snapshot, and this script refreshes it
-from a backend checkout:
-
-    python scripts/refresh_v2_routes.py ~/src/dualentry/backend
-
-Django is not a CLI dependency, so the schema is built by the backend's own
-interpreter: its .venv if present, otherwise `poetry run python`. Pass a third
-argument to point at a specific interpreter instead.
-
-Re-run it whenever the public v2 API gains or loses routes.
-"""
+"""Regenerate the v2 route snapshot: refresh_v2_routes.py <backend> [python]."""
 
 from __future__ import annotations
 
@@ -71,7 +56,6 @@ def main(argv: list[str]) -> int:
         sys.stderr.write(result.stderr)
         return result.returncode
 
-    # Django logs to stdout on startup, so take only the marked payload.
     _, _, payload = result.stdout.rpartition(_MARKER)
     try:
         routes = json.loads(payload)

src/dualentry_cli/commands/__init__.py

@@ -138,9 +138,6 @@ def make_resource_app(
     app = typer.Typer(help=f"Manage {name}", no_args_is_help=True, cls=HelpfulGroup)
     enabled_filters = filters or set()
     base, detail = f"/{path}/", f"/{path}/{{}}/"
-    # Every request the registered commands can issue. Append next to the command
-    # that issues it; tests/test_route_conformance.py checks the result against the
-    # real v2 route table so a resource can never gain a command the API lacks.
     operations: list[tuple[str, str]] = [("GET", base)]
 
     @app.command("list")

src/dualentry_cli/commands/accounts.py

@@ -39,6 +39,4 @@ def get_account(
     format_output(data, resource="account", fmt=output)
 
 
-# Declared by hand because these commands are not built by make_resource_app.
-# tests/test_route_conformance.py checks them against the real v2 route table.
 app.api_operations = [("GET", "/accounts/"), ("GET", "/accounts/{}/")]

tests/test_route_conformance.py

@@ -1,17 +1,4 @@
-"""
-Every command the CLI registers must map to a route the public API v2 has.
-
-make_resource_app() registers create/update by default, which silently produced
-commands for resources that are read-only in v2 - they shipped in --help and
-returned 404 or 405 on every run. These tests close that off.
-
-The check is one-directional: each request a registered command can issue must
-exist in v2. The reverse - v2 operations with no command - is expected and
-tracked separately.
-
-The route table is a committed snapshot because the CLI is a separate
-repository from the backend; refresh it with scripts/refresh_v2_routes.py.
-"""
+"""Check registered commands against the routes public API v2 exposes."""
 
 from __future__ import annotations
 
@@ -25,13 +12,10 @@
 
 FIXTURE = Path(__file__).parent / "fixtures" / "public_api_v2_routes.json"
 PREFIX = "/public/v2"
-
-# Command groups that manage the CLI itself rather than an API resource.
 NON_RESOURCE_GROUPS = {"auth", "config"}
 
 
 def _v2_routes() -> dict[str, set[str]]:
-    """Map each v2 path to its methods, with path params normalised to '{}'."""
     routes: dict[str, set[str]] = {}
     for path, methods in json.loads(FIXTURE.read_text()).items():
         assert path.startswith(PREFIX), f"unexpected path in fixture: {path}"
@@ -41,7 +25,6 @@ def _v2_routes() -> dict[str, set[str]]:
 
 
 def _walk(typer_app, prefix: tuple[str, ...] = ()) -> tuple[list, list]:
-    """Split sub-apps into those declaring api_operations and those skipped."""
     checked, skipped = [], []
     for group in typer_app.registered_groups:
         if group.name in NON_RESOURCE_GROUPS:
@@ -52,8 +35,6 @@ def _walk(typer_app, prefix: tuple[str, ...] = ()) -> tuple[list, list]:
         if operations is not None:
             checked.append((" ".join(name), operations))
         elif sub.registered_commands:
-            # A sub-app with commands but no declared operations would pass the
-            # conformance check below simply by never being looked at.
             skipped.append(" ".join(name))
         sub_checked, sub_skipped = _walk(sub, name)
         checked.extend(sub_checked)
@@ -64,14 +45,24 @@ def _walk(typer_app, prefix: tuple[str, ...] = ()) -> tuple[list, list]:
 RESOURCES, UNCHECKED = _walk(app)
 OPERATIONS = [(command, method, path) for command, ops in RESOURCES for method, path in ops]
 
+STALE_COMMANDS = [
+    ("companies", "create"),
+    ("companies", "update"),
+    ("budgets", "create"),
+    ("budgets", "update"),
+    ("depreciation-books", "create"),
+    ("depreciation-books", "update"),
+    ("paper-checks", "create"),
+    ("paper-checks", "update"),
+    ("inbox", "get"),
+]
+
 
 def test_no_resource_app_escapes_the_check():
-    """Guard the introspection, so a sub-app cannot pass by being invisible."""
     assert UNCHECKED == [], f"these command groups declare no api_operations and are never checked: {UNCHECKED}"
 
 
 def test_resource_apps_are_discoverable():
-    """A walk that silently returned nothing would make every check below vacuous."""
     assert len(RESOURCES) > 30
 
 
@@ -83,21 +74,6 @@ def test_command_maps_to_a_real_v2_route(command: str, method: str, path: str):
     assert method in available, f"'dualentry {command}' calls {method} {path}, but v2 allows only {sorted(available)}"
 
 
-# Named explicitly so that re-adding any one of them fails here with a direct
-# message, not only as a route-table mismatch above.
-STALE_COMMANDS = [
-    ("companies", "create"),
-    ("companies", "update"),
-    ("budgets", "create"),
-    ("budgets", "update"),
-    ("depreciation-books", "create"),
-    ("depreciation-books", "update"),
-    ("paper-checks", "create"),
-    ("paper-checks", "update"),
-    ("inbox", "get"),
-]
-
-
 @pytest.mark.parametrize(("resource", "command"), STALE_COMMANDS)
 def test_stale_command_is_not_registered(resource: str, command: str):
     group = next(g for g in app.registered_groups if g.name == resource)
@@ -106,25 +82,12 @@ def test_stale_command_is_not_registered(resource: str, command: str):
 
 
 def test_accounts_declaration_covers_its_commands():
-    """
-    Accounts declares its operations by hand, so additions must update them.
-
-    Pinning the command set is the point here: a new command has to be
-    accompanied by a matching api_operations entry, or this fails.
-    """
     group = next(g for g in app.registered_groups if g.name == "accounts")
     registered = {c.name for c in group.typer_instance.registered_commands}
     assert registered == {"list", "get"}, "update api_operations in commands/accounts.py to match"
 
 
 def test_paper_checks_has_no_number_lookups():
-    """
-    Paper checks are keyed by primary key and expose no record number.
-
-    _resolve_by_internal_id() matches on 'internal_id' then refetches by
-    'number'; PublicPaperCheckSchemaOut has neither, so the number-based
-    lookups could never resolve.
-    """
     group = next(g for g in app.registered_groups if g.name == "paper-checks")
     registered = {c.name for c in group.typer_instance.registered_commands}
     assert "get" in registered