feat: adds reusable actions

[baywet]

This pull request adds action templates.

fixes #33
fixes #136
fixes #270

closes #238

This is another attempt to solve a scale limitation in the current specification. Action templates are better than the previous parameters proposal because:

• They do not introduce a matrix projection, people may use the template multiple times.
• They do not require "declaring" which environment variables to read in advance.
• They limit the string literal replacement to the templates, which does not impact how actions currently work.
• The template reference mechanism works like OpenAPI references.
• The template resolution mechanism can be isolated as a pre-processing step, and the resolved actions can then be fed to the existing code processing actions.
• It introduces a string literal replacement syntax which can be expanded upon for other sources or used at other places in the future.

The pull request is incomplete as it is, it's a draft, I want to collect feedback on the approach before making any further investments.

[ralfhandl]

I like the general direction.

[baywet]

Feedback from the meeting from both @lornajane and @ralfhandl :

• add a peer block to parameters for the environment variables, this allows to set defaults and "declare" which variables are used. But this declaration is optional.
• add a peer "actions" in the components, that's defined as everything except for the target. So people can specify the target on reference. Reusable actions may use action templates in turns.

[ralfhandl]

Mostly wording and capitalization

[baywet]

@ralfhandl @lornajane I pushed another update a couple of minutes ago. I wasn't happy about the whole reusable actions vs action templates kind of thing. After chatting with @mikekistler internally I realized we could simply define a an action template reference object as "you can override anything from the resolved template in the reference" like JSON schema does to some extent. And keep things extra simple.

Let me know what you think!

[baywet]

Update, I've had some more time to spend on this. I believe I've addressed all the feedback and got this to a place much closer to a finalized version/ready for a formal vote.
I suggest we go through another round of review/update before we move to a formal vote.

Noteable changes:

• updated the terminology to "reusable actions"
• moved to a single concept (no more template vs component actions divide)
• stuck with local references only for now, we can always open this up in a subsequent release, as per other authors' feedback
• added the schema changes
• added the schema tests
• triple checked the examples
• updated additional wording based on @mikekistler excellent suggestions

Let me know if you have any additional comments or questions.

[baywet]

Note: I've just added a lot of tests to improve the coverage. This is going to temporarily make the review more difficult. I've extracted the tests for the current schema (not the changes in this pull request) in #317 in the hope that we merge that one first, making the diff here smaller.

[baywet]

collecting notes from my implementation work: it might be better to restrain this to string instead of any json value. Having any json value poses a couple of issues:

• string interpolation is not "just string interpolation" anymore (you need to consider the object tree), and that brings a higher chance of ending up with an invalid resolved value in the end
• environment variables would never be able to support that.

So both in the name of simplicity and uniformity I suggest we change this, and the parameter value field to string types instead of json values.

[baywet]

@handrews I think that also effectively means that any reusable action (entries under components/actions) MUST have / and ~ encoded according to the JSON pointer semantics. I think we should call this out explicitly in the components section, what do you think?

[baywet]

Here we need to restrict the interpolation syntax to apply only to string fields (Target, Copy, Description), because for others (Remove) it breaks the JSON schema validation of the document).

And for Update, it poses a lot of additional questions (env vs params, what happens if the resulting JSON doesn't match the structure we expect (requirement for this field), etc...

[baywet]

Finalized the implementation of the current version of the spec over here BinkyLabs/openapi-overlays-dotnet#276

(some LLMs were hurt in the process)