[mackoj]

Motivation

There's no way to put a macro on a generated declaration today, because generated code is rewritten on every build. Adopters either post-process the output or fork the generator.

Use cases from #383 include protocol conformances on every operation output, Combine variants of client methods, mocks generated from APIProtocol (e.g. Mockable), and @DependencyClient wrappers from swift-dependencies.

As discussed in #383, this proposal comes before the implementation.

Modifications

• Add SOAR-0016.md, proposing an attachedMacros configuration key.
• List it in Proposals.md.

The proposal follows the design agreed in #383:

• components (schemas, parameters, requestBodies, responses, headers), operations (input, output, clientMethod), apiProtocol, client, and server. server targets registerHandlers.
• Rules use case-sensitive regular expressions matched against OpenAPI names.
• Macro names are written without the @.
• Arguments are a list of label and value entries, where value is Swift source emitted verbatim.

One change from the thread: rules are a list (- match: "^Pet$") instead of a mapping keyed by regex. Decoding a YAML mapping doesn't preserve key order, so the order of macros on a declaration wouldn't be deterministic otherwise. @czechboy0, happy to discuss.

Result

Once implemented, adopters can attach macros to generated declarations from the config file, for example:

attachedMacros:
  apiProtocol:
    - name: Mockable

Without the key, the generated code is unchanged.

Test Plan

This PR only adds the proposal. A follow-up PR will add the implementation, with reference tests for each target.

[czechboy0]

Thanks, @mackoj 🙏

Just a few minor comments, once we settle these, this is ready for a wide review.

[czechboy0]

Great, thank you @mackoj, let me kick off the review now

[czechboy0]

Kicked off: https://forums.swift.org/t/proposal-soar-0016-attached-macros-on-generated-declarations/90100

[czechboy0]

Dismissing my review until the review concludes