feat: declare the attribute contracts the CLI mixins rely on

[blaipr]

First substantive step on the typing work that #42 only set up the measurement for. It takes the CLI from 48 type diagnostics to 2, and the package from 136 to 82, without annotating a single function signature.

The reason so much falls out of so little: cli/custom.py builds its actions out of mixins. Launchable, HasStdout, AssociationMixin, RoleMixin and HasMonitor all read self.page, self.action and self.resource, and none of them declares any of the three, because the CustomAction they get mixed into supplies them. That contract lived only in the reader's head, and it accounted for 46 of the diagnostics on its own.

Each mixin now states it:

class Launchable:
    # Supplied by the CustomAction this is mixed into, which is why they are
    # annotations rather than assignments: they describe the contract without
    # creating class attributes that would shadow the real ones.
    page: 'api.pages.Page'
    action: str
    resource: str

Annotations without assignment create no class attribute, so there is no runtime change and nothing shadows what the subclasses set.

Three more, each a real finding rather than a checker being appeased:

CustomAction.action and .resource were @property methods raising NotImplementedError. Every subclass sets them as plain class attributes, action = 'launch', so the properties were never reached and they conflicted with the mixin declarations above. They are annotations now, which is what the subclasses actually satisfy. perform keeps the property, since subclasses genuinely override it as a method.

Two add_arguments overrides were narrower than what they replace. Launchable.add_arguments takes with_pk=True; BulkJobLaunch and AdhocCommandLaunch declared it without that parameter and then passed with_pk=False to the parent by hand. They now carry the parameter with a False default and pass it through, so the behaviour is identical and the signature no longer contradicts the base.

NotificationAssociateMixin.targets is not dict[str, list[str]]. The three literals suggest it is, and then six targets.update() calls add entries like ['credentials', None]. It is annotated as dict[str, list[str | None]], which is what it has always held.

Two diagnostics remain in cli/ and both are left on purpose:

• cli/format.py:151, Cannot resolve imported module 'jq'. It is the formatting extra, imported inside the function that needs it. Installing the extra in the type-check environment resolves it; the code is correct as it stands.
• cli/utils.py:29, command.name inside CustomRegistryMeta.registry. type.__subclasses__() is typed list[type], which says nothing about the name every command declares. Fixing it means a cast, and contorting a metaclass to satisfy a checker is worse than the diagnostic.

The remaining 80 are in api/, a different shape of problem centred on PseudoNamespace, and belong in their own change.

Verified with black --check, flake8, the unit suite at 355 passing, and ascender --help plus ascender job_templates --help still rendering.

[ciq-it-service-account]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.