Single source of truth for configuration options

[liamnichols]

Related Links

• Support Swift Package Plugins #48
• Update documentation #50

Background

As it stands, the GenerateOptions.swift file contains a few things:

1. A series of types under the GenerateOptionsSchema class that are all optional allowing initialisation from an empty yaml/json file
2. A series of types under the GenerateOptions class and initialisers that map from the schema type with a default value (+ some additional customisations)

In addition to that, we have an example config file in the README document.

I've identified this as a bit problematic and hard to maintain because we have two types to represent the same thing, the documentation is maintained manually (and a little out of sync) and the default values are also decoupled.

I want to explore better ways to capture schema of the options with one single source of truth (that contains the properties, their defaults, and documentation).

Approach

In this change, I'm reintroducing a new ConfigOptions type inside a new CreateOptions target (this is because it will also later be shared with the generator plugin target). This time, there are some differences: There is now just one single type where every property is defined, documented and has a default value.

Now there are reasons why we didn't do this before:

1. Decodable ignores the default values defined for each property so an empty config would fail to deserialise
2. Some types needed to be mapped into something else that couldn't be represented in JSON/YAML before we passed it into the generator

But this is where I've chosen to use Sourcery to help out.

Sourcery will generate two things:

1. Docs/ConfigOptions.md consisting of detailed documentation for every property
2. Sources/CreateOptions/ConfigOptions+DecodableWithDefault.swift consisting with a Decodable.init(from:) implementation that will fallback to the default value if it wasn't provided in the YAML/JSON

The caveat here is that whenever we modify ConfigOptions.swift, we have to re-run Sourcery (make documentation), but the upside there is that one type now acts as the single source of truth for everything.

Usually I'd probably have given up and just dealt with the manual maintenance of options/docs/mapping, but since CreateAPI has a lot of flexibility and a rich set of options, I think it's important for this to be accurate.

I then have a small wrapper around ConfigOptions that is called GenerateOptions (this will replace the old one). This wrapper currently just provides the small additional functionality of computing allAcronyms but could also be used in the future to abstract loading the config as well as tracking the file location in the event that we want to put file paths in the config files (so we can easily support relative paths).

In this PR, I've not started using the new GenerateOptions yet, that will come in a different PR. I'll also update the README in another PR too.

While the PR is open, find the documentation here: https://github.com/CreateAPI/CreateAPI/tree/ln/options-and-documentation/Docs/ConfigOptions.md

I'd love any feedback on what can be improved with the format 🙏