django-spec-cli 0.1.0__py3-none-any.whl

django_spec_cli/__init__.py

@@ -0,0 +1,31 @@
+"""A registry of specs as a management command."""
+
+from django_spec_cli.argv.add_spec_arguments import add_spec_arguments
+from django_spec_cli.argv.describe_parameters import describe_parameters
+from django_spec_cli.argv.parameter_descriptor import ParameterDescriptor
+from django_spec_cli.argv.parsed_arguments import parsed_arguments
+from django_spec_cli.exit_code_for import exit_code_for
+from django_spec_cli.render.render_json_lines import render_json_lines
+from django_spec_cli.render.render_result import render_result
+from django_spec_cli.render.render_table import render_table
+from django_spec_cli.render.wants_table import wants_table
+from django_spec_cli.report.unguarded_message import unguarded_message
+from django_spec_cli.spec_command import SpecCommand
+from django_spec_cli.types.exit_code import ExitCode
+from django_spec_cli.version import __version__
+
+__all__ = [
+    "__version__",
+    "ExitCode",
+    "ParameterDescriptor",
+    "SpecCommand",
+    "exit_code_for",
+    "render_json_lines",
+    "render_result",
+    "render_table",
+    "wants_table",
+    "add_spec_arguments",
+    "describe_parameters",
+    "parsed_arguments",
+    "unguarded_message",
+]

django_spec_cli/apps.py

@@ -0,0 +1,31 @@
+"""The app a project lists to have its open specs reported by ``manage.py check``."""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+from django.core.checks import register
+
+from django_spec_cli.checks import check_unguarded_specs
+
+
+class DjangoSpecCliConfig(AppConfig):
+    """Registers the unguarded-spec system check, and does nothing else.
+
+    Optional: the package works unlisted, and a project that does not list it
+    gets no check and no sign that it is missing. It owns no models, so it
+    sets no ``default_auto_field``.
+
+    The check carries no tag, and in particular not ``Tags.security``: a
+    ``SpecCommand`` is a mistake-prevention and attribution surface, not an
+    authorization boundary, and a security tag would say it is one.
+
+    The import of the check is at the top of this module, which Django
+    imports before the app registry is ready. That holds because nothing the
+    package imports reaches a model or ``get_user_model`` at import time
+    (test_importing_the_app_before_setup_loads_no_model).
+    """
+
+    name = "django_spec_cli"
+
+    def ready(self) -> None:
+        register(check_unguarded_specs)

django_spec_cli/argv/__init__.py

@@ -0,0 +1,13 @@
+"""How a spec's parameters become command-line options, and come back as its arguments."""
+
+from django_spec_cli.argv.add_spec_arguments import add_spec_arguments
+from django_spec_cli.argv.describe_parameters import describe_parameters
+from django_spec_cli.argv.parameter_descriptor import ParameterDescriptor
+from django_spec_cli.argv.parsed_arguments import parsed_arguments
+
+__all__ = [
+    "ParameterDescriptor",
+    "add_spec_arguments",
+    "describe_parameters",
+    "parsed_arguments",
+]

django_spec_cli/argv/add_spec_arguments.py

@@ -0,0 +1,169 @@
+"""``add_spec_arguments`` - one argparse option per parameter a command line can send."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Collection
+from typing import Any
+
+from django.core.exceptions import ImproperlyConfigured
+from django_service_specs import UNSET, Parameters
+
+from django_spec_cli.argv.describe_parameters import describe_parameters
+from django_spec_cli.argv.parameter_descriptor import ParameterDescriptor
+from django_spec_cli.argv.utils import destination, option_string
+
+
+def add_spec_arguments(
+    parser: argparse.ArgumentParser, parameters: Parameters, *, reserved: Collection[str] = ()
+) -> None:
+    """Add an option to ``parser`` for each parameter a command line can send.
+
+    The option is ``--`` and the name with ``_`` as ``-``: ``due_at`` is
+    ``--due-at``. Argparse only collects strings here, and every decision about
+    them is the kernel's, so a command line refuses what an HTTP caller would
+    be refused, in the same words:
+
+    - **No value is converted.** No option sets ``type=``; every value stays
+      the string typed, and [`coerce_flat`][django_service_specs.parameters.coerce_flat.coerce_flat]
+      reads it as it reads a query string.
+    - **No option is required by argparse.** The shape check owns "missing",
+      so a required parameter is refused as HTTP refuses it, beside every other
+      mistake in the call, and ``--help`` marks it ``(required)``.
+    - **No choice is enforced by argparse.** The choices are listed in
+      ``--help`` and the shape check refuses any other value. Argparse's own
+      ``choices=`` would answer one mistake with a second message and exit
+      code, and only for a parameter whose choices are all strings.
+    - **An omitted option is absent from the namespace**, never ``None``: its
+      default is ``argparse.SUPPRESS``. That keeps it apart from an empty
+      string and from ``--no-flag``.
+    - A ``boolean`` is a ``--flag``/``--no-flag`` pair, and an ``array`` is a
+      repeated option, ``--ids 1 --ids 2``, each value one element.
+    - Each value lands under a namespaced destination rather than the
+      parameter's name, so a parameter named ``verbosity`` or ``settings``
+      cannot overwrite ``BaseCommand``'s own. Read the namespace back with
+      [`parsed_arguments`][django_spec_cli.argv.parsed_arguments.parsed_arguments].
+
+    A parameter with no honest flat spelling - an object, an array of objects,
+    a file - gets no option: see
+    [`ParameterDescriptor`][django_spec_cli.argv.parameter_descriptor.ParameterDescriptor].
+
+    ``reserved`` is the option strings the command owns itself, such as
+    ``--as-user`` and Django's ``--verbosity``; ``--help`` is always reserved,
+    since every parser owns its own.
+
+    Raises:
+        ImproperlyConfigured: naming the parameter and the option, when an
+            option would be one in ``reserved``, or one another parameter maps
+            to as well - ``a_b`` and ``a-b``, or a boolean ``x``, whose
+            ``--no-x`` is a parameter ``no_x``'s option. Every option is
+            checked before the first is added, so a refused spec leaves the
+            parser as it was.
+    """
+    descriptors = [d for d in describe_parameters(parameters) if d.argv]
+    _check_options(descriptors, frozenset(reserved) | {"--help"})
+    for descriptor in descriptors:
+        _add_option(parser, descriptor)
+
+
+def _option_strings(descriptor: ParameterDescriptor) -> list[str]:
+    """Every option string a parameter claims: a boolean claims its negative too."""
+    option = option_string(descriptor.name)
+    if descriptor.type == "boolean":
+        return [option, "--no-" + option[2:]]
+    return [option]
+
+
+def _check_options(descriptors: list[ParameterDescriptor], reserved: frozenset[str]) -> None:
+    claimed: dict[str, str] = {}
+    for descriptor in descriptors:
+        for option in _option_strings(descriptor):
+            if option in reserved:
+                raise ImproperlyConfigured(
+                    f"Parameter {descriptor.name!r}: the option {option!r} is the command's "
+                    "own; rename the parameter."
+                )
+            if option in claimed:
+                raise ImproperlyConfigured(
+                    f"Parameters {claimed[option]!r} and {descriptor.name!r} both map to the "
+                    f"option {option!r}; rename one of them."
+                )
+            claimed[option] = descriptor.name
+
+
+def _add_option(parser: argparse.ArgumentParser, descriptor: ParameterDescriptor) -> None:
+    option = option_string(descriptor.name)
+    common: dict[str, Any] = {
+        "dest": destination(descriptor.name),
+        "default": argparse.SUPPRESS,
+        "help": _help(descriptor),
+    }
+    if descriptor.type == "boolean":
+        # No ``metavar``, ``type`` or ``choices``: a flag takes no value, and
+        # Python 3.12 deprecates passing them to this action.
+        parser.add_argument(option, action=argparse.BooleanOptionalAction, **common)
+        return
+    parser.add_argument(
+        option,
+        action="append" if descriptor.type == "array" else "store",
+        # Set, or argparse prints the namespaced destination in its place.
+        metavar=_metavar(descriptor),
+        **common,
+    )
+
+
+def _metavar(descriptor: ParameterDescriptor) -> str:
+    """What one value is: an array's is its element's, and a format names a string's."""
+    if descriptor.format is not None:
+        return descriptor.format.upper()
+    kind = descriptor.items if descriptor.type == "array" else descriptor.type
+    # An ``any``, and an array declaring no element, take any value.
+    return "VALUE" if kind in (None, "any") else kind.upper()
+
+
+def _help(descriptor: ParameterDescriptor) -> str | None:
+    notes: list[str] = []
+    if descriptor.type == "array":
+        notes.append("repeat the option for each element")
+    if descriptor.choices is not None:
+        pairs = descriptor.choice_labels or ()
+        notes.append("one of: " + ", ".join(_choice(c, pairs) for c in descriptor.choices))
+    for label, bound in (("minimum", descriptor.minimum), ("maximum", descriptor.maximum)):
+        if bound is not None:
+            notes.append(f"{label} {bound}")
+    for label, length in (("at least", descriptor.min_length), ("at most", descriptor.max_length)):
+        if length is not None:
+            notes.append(f"{label} {length}")
+    if descriptor.required:
+        notes.append("required")
+    if descriptor.default is not UNSET:
+        notes.append(f"default: {_text(descriptor.default)}")
+    # ``str``: a help text may be a lazy translation, rendered here.
+    parts = [str(descriptor.help)] if descriptor.help else []
+    if notes:
+        parts.append("(" + "; ".join(notes) + ")")
+    # Argparse %-formats every help string, so a literal ``%`` - in the
+    # declared help, a choice, a label or a default - is doubled to print as
+    # written: test_a_percent_sign_in_any_help_text_is_printed_as_written.
+    return " ".join(parts).replace("%", "%%") if parts else None
+
+
+def _choice(choice: Any, pairs: tuple[tuple[Any, str], ...]) -> str:
+    """A choice as typed, with its label where one is declared."""
+    # Matched by type as well as value, as the declaration keeps them apart:
+    # ``1`` and ``True`` are equal to Python and two choices to a caller. Each
+    # condition is held by its own case of test_a_choice_is_shown_with_its_own_label:
+    # [equal-across-types] (the type) and [unlabelled] (the value).
+    label = next((lb for v, lb in pairs if type(v) is type(choice) and v == choice), None)
+    return _text(choice) if label is None else f"{_text(choice)} ({label})"
+
+
+def _text(value: Any) -> str:
+    """A value as it is typed: a string bare, anything else as its JSON.
+
+    An empty string is quoted, since bare it would read as no value at all.
+    """
+    # Each condition is held by its own test: test_an_empty_string_default_is_shown_quoted
+    # (the emptiness) and test_a_choice_that_is_not_a_string_is_listed_as_json (the type).
+    return value if isinstance(value, str) and value else json.dumps(value)

django_spec_cli/argv/describe_parameters.py

@@ -0,0 +1,80 @@
+"""``describe_parameters`` - a spec's Parameters, as a command line sees them."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from django_service_specs import UNSET, Parameter, Parameters
+
+from django_spec_cli.argv.parameter_descriptor import ParameterDescriptor
+
+_FLAT_TYPES = ("string", "integer", "number", "boolean", "any")
+"""The types one string on a command line spells: ``coerce_flat`` reads it as one
+of these, and an ``any`` is handed on as the string it is."""
+
+_FLAT_ELEMENTS = (None, "string", "integer", "number", "boolean")
+"""An array's elements a repeated option spells: a declared scalar, or no
+declared ``items``, whose elements stay the strings given."""
+
+
+def describe_parameters(parameters: Parameters) -> tuple[ParameterDescriptor, ...]:
+    """One [`ParameterDescriptor`][django_spec_cli.argv.parameter_descriptor.ParameterDescriptor] per parameter, in declaration order.
+
+    Never refuses a declaration: a parameter with no flat spelling is
+    described with ``argv=False`` rather than left out, so a command can still
+    say in ``--help`` that a spec takes something argv cannot send.
+    """
+    return tuple(_describe(param) for param in parameters)
+
+
+def _describe(param: Parameter) -> ParameterDescriptor:
+    return ParameterDescriptor(
+        name=param.name,
+        type=param.type,
+        format=param.format,
+        items=param.items if isinstance(param.items, str) else None,
+        # The shape check's own rule for an absent argument, so the help says
+        # "(required)" exactly where an omission is refused. Each condition is
+        # held by its own test: test_required_means_an_omitted_option_is_refused
+        # (the declaration) and test_a_required_parameter_with_a_default_is_not_required
+        # (the default, reported or not).
+        required=param.required and param.default is UNSET,
+        default=_shown_default(param.default),
+        choices=param.choices,
+        choice_labels=param.choice_labels,
+        minimum=param.minimum,
+        maximum=param.maximum,
+        min_length=param.min_length,
+        max_length=param.max_length,
+        help=param.help,
+        argv=_has_flat_spelling(param),
+    )
+
+
+def _has_flat_spelling(param: Parameter) -> bool:
+    # Read from the type rather than from ``nested``, which alone is narrower
+    # than "no honest option": an object with no ``fields`` and an array of
+    # ``object``, ``array`` or ``file`` elements have no nested Parameters and
+    # still no string that spells them. Held by
+    # test_a_parameter_with_no_flat_spelling_has_no_option, one case per type,
+    # and test_every_parameter_a_command_line_can_send_has_an_option.
+    if param.type == "array":
+        return param.items in _FLAT_ELEMENTS
+    return param.type in _FLAT_TYPES
+
+
+def _shown_default(default: Any) -> Any:
+    """The default, where JSON spells it; otherwise ``UNSET``, so nothing is shown.
+
+    One check rather than a list of exclusions: ``json.dumps`` refuses
+    ``UNSET``, a callable and any other object it has no spelling for, and
+    ``allow_nan=False`` refuses NaN and the infinities, which Python's encoder
+    would otherwise write as tokens no JSON reader takes. Each is a case of
+    test_a_default_with_no_json_spelling_is_not_reported.
+    """
+    try:
+        json.dumps(default, allow_nan=False)
+    except (TypeError, ValueError):
+        return UNSET
+    return default

django_spec_cli/argv/parameter_descriptor.py

@@ -0,0 +1,61 @@
+"""``ParameterDescriptor`` - one parameter, as a command line sees it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from django_service_specs import UNSET
+
+from django_spec_cli.argv.utils import option_string
+
+
+@dataclass(frozen=True)
+class ParameterDescriptor:
+    """A [`Parameter`][django_service_specs.parameters.parameters.Parameter] seen from argv.
+
+    What a command line can say about a parameter, built by
+    [`describe_parameters`][django_spec_cli.argv.describe_parameters.describe_parameters]:
+    the option it is sent with, and what ``--help`` can honestly show about
+    the value. Each field is the declaration's, read for a person typing it,
+    and three are narrower than the ``Parameter`` they come from:
+
+    - ``required`` is whether **an omitted option is refused**: a parameter
+      declared required with a default is not, since the shape check lets the
+      Validator supply the default. A spec declared ``partial`` refuses no
+      omission at all, which the declaration cannot see; the command that
+      knows its spec says so.
+    - ``default`` is the declared default **only where JSON can spell it**:
+      ``None`` included, and never a callable, a sentinel or NaN, whose
+      ``repr`` in the help would be a concrete falsehood. ``UNSET`` means
+      nothing is shown, not that nothing is declared.
+    - ``items`` is an array's element type, or ``None``: an element that is a
+      row of nested Parameters is no type a command line could show.
+
+    ``argv`` is ``False`` for a parameter that has no honest flat spelling -
+    an object, an array of objects, of arrays or of files, and a file - so
+    no option is invented for it: a dotted option for a nested field would be
+    a syntax only this command spoke. Sent anyway, under its name by a
+    caller that fills the arguments itself, it still reaches ``coerce_flat``'s
+    refusal; left out, the shape check's ``required``.
+    """
+
+    name: str
+    type: str
+    format: str | None = None
+    items: str | None = None
+    required: bool = False
+    default: Any = UNSET
+    choices: tuple[Any, ...] | None = None
+    choice_labels: tuple[tuple[Any, str], ...] | None = None
+    minimum: int | float | None = None
+    maximum: int | float | None = None
+    min_length: int | None = None
+    max_length: int | None = None
+    help: str | None = None
+    argv: bool = True
+
+    @property
+    def option(self) -> str | None:
+        """The option string, ``--due-at`` for ``due_at``, or ``None`` with no option."""
+        return option_string(self.name) if self.argv else None

django_spec_cli/argv/parsed_arguments.py

@@ -0,0 +1,50 @@
+"""``parsed_arguments`` - the options argparse read, as the raw arguments ``coerce_flat`` takes."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from django_service_specs import Parameters
+
+from django_spec_cli.argv.utils import destination
+
+
+def parsed_arguments(namespace: argparse.Namespace, parameters: Parameters) -> dict[str, Any]:
+    """The spec's arguments from a namespace filled by [`add_spec_arguments`][django_spec_cli.argv.add_spec_arguments.add_spec_arguments]'s options.
+
+    The raw dict a command hands to
+    [`coerce_flat`][django_service_specs.parameters.coerce_flat.coerce_flat],
+    keyed by parameter name, so argv crosses the one coercion and the one
+    shape check every transport shares and is refused, or validated, exactly
+    as the same values off a JSON wire would be:
+
+    - **An omitted option is absent**, so the shape check decides what its
+      absence means, as it does for a JSON caller who left the key out.
+    - A ``boolean`` is the string ``"true"`` or ``"false"``: one of the four
+      spellings ``coerce_flat`` reads, rather than a Python ``bool`` only this
+      transport would hand on.
+    - An ``array`` is the list of strings given, one per repeated option.
+    - Everything else is the string given, an empty one included.
+
+    Only the namespaced destinations are read, so a command's own options in
+    the same namespace - ``verbosity``, ``settings`` - never become arguments.
+    A value set there by a caller other than argparse, as ``call_command``
+    does with keyword arguments, is handed on as it was set, except that a
+    ``bool`` for a ``boolean`` is spelled as argparse's would have been.
+    """
+    values = vars(namespace)
+    raw: dict[str, Any] = {}
+    for param in parameters:
+        key = destination(param.name)
+        if key not in values:
+            continue
+        value = values[key]
+        # Each condition is held by its own case of
+        # test_a_value_given_by_destination_rather_than_argv_is_handed_on: a
+        # string for a boolean stays the string, and a ``bool`` for an ``any``
+        # stays the ``bool``.
+        if param.type == "boolean" and isinstance(value, bool):
+            value = "true" if value else "false"
+        raw[param.name] = value
+    return raw

django_spec_cli/argv/utils.py

@@ -0,0 +1,21 @@
+"""Helpers ``argv/`` and ``SpecCommand`` share: how a parameter's name becomes argv and back."""
+
+from __future__ import annotations
+
+DESTINATION_PREFIX = "spec_arg__"
+"""Where a spec argument lands in argparse's namespace.
+
+A spec parameter may be named ``verbosity``, ``settings`` or ``traceback``, and
+``BaseCommand`` keeps its own options in the same namespace under exactly those
+names. Prefixed, the two never meet, so a spec argument cannot change how the
+command itself runs. ``parsed_arguments`` is the only reader."""
+
+
+def destination(name: str) -> str:
+    """The namespace attribute a parameter's option stores its value under."""
+    return DESTINATION_PREFIX + name
+
+
+def option_string(name: str) -> str:
+    """The option a parameter is sent with: ``due_at`` is ``--due-at``."""
+    return "--" + name.replace("_", "-")

django_spec_cli/checks.py

@@ -0,0 +1,133 @@
+"""The system check reporting every spec a ``SpecCommand`` serves that authorizes nothing."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from typing import Any
+
+from django.apps import AppConfig
+from django.core.checks import CheckMessage, Warning
+from django.core.management import get_commands, load_command_class
+from django_service_specs import UnguardedSpec, unguarded_specs
+
+from django_spec_cli.report.unguarded_message import unguarded_message
+from django_spec_cli.spec_command import SpecCommand
+
+_HINT = (
+    "Declare a PermissionCheck that refuses someone in the spec's permissions, or add "
+    "'django_spec_cli.W001' to SILENCED_SYSTEM_CHECKS if the spec is meant to be open."
+)
+
+
+def check_unguarded_specs(
+    app_configs: Sequence[AppConfig] | None, **kwargs: Any
+) -> list[CheckMessage]:
+    """Warn once per spec that authorizes nothing, in every ``SpecCommand`` of the project.
+
+    Registered by the app's ``ready()``, so a project gets it by listing
+    ``django_spec_cli`` in ``INSTALLED_APPS`` and not otherwise. There is
+    no global registry to read: each ``SpecCommand`` subclass names its own,
+    so the check finds them the way ``manage.py`` does, by loading every
+    command the installed apps serve and keeping the ``SpecCommand`` ones.
+    Loading a command imports its module and constructs it, third-party
+    commands included; Django's own are not loaded, since none is a
+    ``SpecCommand``.
+
+    - ``django_spec_cli.W001``, one per spec that
+      [`unguarded_specs`][django_service_specs.registry.unguarded_specs.unguarded_specs]
+      reports, naming the command an operator types and the spec, with the
+      command class as ``obj``. A ``Warning``, never an ``Error``: an open
+      spec is a decision or an accident the check cannot tell apart, and an
+      ``Error`` would stop ``migrate`` on a project working as intended.
+      ``SILENCED_SYSTEM_CHECKS`` silences it by id, so for every spec at once.
+    - ``django_spec_cli.W003``, one per command that could not be loaded or
+      whose parser could not be built, naming it and the error. Without this
+      app nothing loads that command until somebody runs it, so failing the
+      check on it would make a broken command nobody runs stop ``migrate``;
+      and dropping it silently would leave its specs unchecked with nothing
+      saying so.
+
+    With ``app_configs``, as ``manage.py check <app_label>`` passes, only
+    those apps' commands are loaded.
+
+    The check runs wherever system checks run: ``manage.py check``, and
+    every ``manage.py`` command that keeps ``requires_system_checks``.
+    ``call_command`` skips system checks for every command but ``check``
+    itself, so a command invoked through it does not run this.
+    """
+    messages: list[CheckMessage] = []
+    for name, app_name, loaded in _spec_commands(app_configs):
+        if isinstance(loaded, Exception):
+            messages.append(
+                Warning(
+                    f"The command {name!r} from {app_name} could not be set up, so its specs "
+                    f"were not checked: {type(loaded).__name__}: {loaded}",
+                    hint=(
+                        f"Run manage.py {name} to see the traceback. Until it loads, the specs "
+                        "it serves are not checked."
+                    ),
+                    id="django_spec_cli.W003",
+                )
+            )
+            continue
+        command, specs = loaded
+        messages.extend(
+            Warning(
+                unguarded_message(spec, name),
+                hint=_HINT,
+                obj=type(command),
+                id="django_spec_cli.W001",
+            )
+            for spec in specs
+        )
+    return messages
+
+
+def _spec_commands(
+    app_configs: Sequence[AppConfig] | None,
+) -> Iterator[tuple[str, str, tuple[SpecCommand, tuple[UnguardedSpec, ...]] | Exception]]:
+    """Each ``SpecCommand`` the project serves with its unguarded specs, or why it would not load.
+
+    The one place that reads Django's management internals: ``get_commands``
+    maps each command name to the app serving it, and
+    ``load_command_class`` imports that module and constructs its
+    ``Command``. Neither is documented API, so
+    ``tests/test_checks.py``'s ``TestTheDjangoInternalsTheWalkReads`` pins the
+    shape this relies on.
+
+    Reading the registry is inside the same ``try``, so a ``SpecCommand``
+    that names none is reported like one that would not construct.
+    """
+    wanted = None if app_configs is None else {config.name for config in app_configs}
+    for name, app_name in get_commands().items():
+        # One arc to coverage, so each operand is named by the test that fails
+        # without it: ``django.core`` by test_django_s_own_commands_are_not_loaded,
+        # the ``wanted`` clause by test_an_app_not_named_has_its_commands_skipped,
+        # and its ``not in`` by test_the_app_named_has_its_commands_checked.
+        # Django's own commands are skipped by app rather than by name, since a
+        # project command overriding one maps to the project's app
+        # (test_a_project_command_under_a_core_name_is_walked); loading them
+        # all costs more than the rest of the walk.
+        if app_name == "django.core" or (wanted is not None and app_name not in wanted):
+            continue
+        try:
+            command = load_command_class(app_name, name)
+            if not isinstance(command, SpecCommand):
+                continue
+            # Built as ``manage.py`` builds it, so a command whose parser
+            # cannot be built (a parameter taking an option the command owns,
+            # two specs sharing a subcommand name) is reported here and not
+            # first found by the operator running it.
+            command.create_parser("manage.py", name)
+            loaded: tuple[SpecCommand, tuple[UnguardedSpec, ...]] | Exception = (
+                command,
+                unguarded_specs(command.registry),
+            )
+        # Anything a module, a constructor or the parser's construction
+        # raises: an ``ImportError`` from a missing dependency, an
+        # ``ImproperlyConfigured`` from a registry refusing a spec at import,
+        # or the command's own bug. Not ``BaseException``, so an interrupt
+        # still stops the check.
+        except Exception as error:
+            loaded = error
+        yield name, app_name, loaded

django_spec_cli/exit_code_for.py

@@ -0,0 +1,49 @@
+"""``exit_code_for`` - the exit status a refusal ends a ``SpecCommand`` run with."""
+
+from __future__ import annotations
+
+from django_service_specs import (
+    AdditionalInputRequired,
+    DispatchError,
+    NotPermitted,
+    PrincipalUnavailable,
+    ServiceConflict,
+    ServiceError,
+    ServiceNotFound,
+    ServiceValidationError,
+)
+
+from django_spec_cli.types.exit_code import ExitCode
+
+_CODES: tuple[tuple[type[Exception], ExitCode], ...] = (
+    (NotPermitted, ExitCode.NOT_PERMITTED),
+    (PrincipalUnavailable, ExitCode.PRINCIPAL_UNAVAILABLE),
+    (DispatchError, ExitCode.INVALID_ARGUMENTS),
+    (ServiceValidationError, ExitCode.INVALID_ARGUMENTS),
+    (ServiceNotFound, ExitCode.NOT_FOUND),
+    (ServiceConflict, ExitCode.CONFLICT),
+    (AdditionalInputRequired, ExitCode.INPUT_REQUIRED),
+    (ServiceError, ExitCode.REFUSED),
+)
+"""Each refusal's code, read top to bottom, first match wins.
+
+A subclass sits above its base, or the base's row would answer for it. Only
+rows that change the answer are listed: ``InvalidArguments`` and
+``ActionUnavailable`` take their base's code, so the base's row is theirs.
+Coverage sees one expression, not eight rows, so each row is held by its own
+case of test_every_refusal_the_kernel_raises_has_its_code."""
+
+
+def exit_code_for(error: BaseException) -> ExitCode:
+    """The [`ExitCode`][django_spec_cli.types.exit_code.ExitCode] ``error`` ends a run with.
+
+    Every [`DispatchError`][django_service_specs.types.dispatch_error.DispatchError]
+    and [`ServiceError`][django_service_specs.services.service_error.ServiceError]
+    has a code, a subclass a later release adds included: it takes its
+    nearest listed base's, so a new refusal of the call is ``INVALID_ARGUMENTS``
+    as the HTTP transport answers it 400, and a new refusal by the operation
+    ``REFUSED``. Anything else is ``ERROR``, which a ``SpecCommand`` never
+    catches: an exception nobody declared is a bug, and its traceback is how
+    it is found.
+    """
+    return next((code for kind, code in _CODES if isinstance(error, kind)), ExitCode.ERROR)

django_spec_cli/render/__init__.py

@@ -0,0 +1,13 @@
+"""How a command writes a presented result: a table for a terminal, JSON lines for a pipe."""
+
+from django_spec_cli.render.render_json_lines import render_json_lines
+from django_spec_cli.render.render_result import render_result
+from django_spec_cli.render.render_table import render_table
+from django_spec_cli.render.wants_table import wants_table
+
+__all__ = [
+    "render_json_lines",
+    "render_result",
+    "render_table",
+    "wants_table",
+]