Emit warnings when configuration files reference unexpected or deprecated properties

[liamnichols]

Background

A while ago, I made a simple typo in my .create-api.yml file and it took me an unexpectedly long time to figure it out. And today, I came across a similar typo in one of the test fixtures so I wanted to do something about it to improve the experience when starting out with the tool 😬

In addition, we need a mechanism to clearly start deprecating preferences in some scenarios.

Changes

In this Pull Request, I build upon the new CreateOptions target and introduce a new warnings property on GenerateOptions. This allows our generator to check the warnings after loading a config and emit either warning or error messages based on the strictness of the generator run.

To do this, there were three big changes that needed to be made:

1. Make CreateOptions responsible for loading GenerateOptions from a file/data
2. Introduce an internal IssueRecorder class that can be passed down through Decoder
3. Wrap KeyedDecodingContainer with a class called StringCodingContainer
   • This allows me to use StringCodingKey which allows container.allKeys to work
   • It keeps a nicer interface in the generated init(from:) implementation
   • It allows us to record which properties were decoded and figure out which values in allKeys remained (i.e typos or unexpected keys)
   • Records issues in the IssueRecorder

With some adjustments to the sorcery generated Decodable implementation, everything plugs together relatively nicely.

After implementing all of this, the GeneratorTests.testGitHub() started failing since it runs in --strict and had a typo in the config file 😄 I fixed this, and updated the snapshots to match what we had intended in the first place.

[liamnichols]

It turns out that even overridenResponses and overridenBodyTypes suffer from typos as well, but these are already defined and in-use. It should be overriddenX instead.

In a followup PR, I will correct the typos and deprecate the old properties. More on that in a minute

[liamnichols]

This remains since we need to mutate ConfigOptions when loading it, but I don't want to make anything inside GenerateOptions mutable.

Generate.swift

let options = try GenerateOptions(data: data) { options in
    options.entities.include = Set(options.entities.include.map { Template(arguments.entityNameTemplate).substitute($0) })
    options.entities.exclude = Set(options.entities.exclude.map { Template(arguments.entityNameTemplate).substitute($0) })
}

I hope that we can rework this in the future. Maybe #52 might help if we consider moving arguments into GenerateOptions too.

[liamnichols]

It might not be quite clear from this template, especially since we're not using it yet, but this allows us to annotate properties in ConfigOptions.swift as deprecated so that they produce warnings.

For example:

// sourcery: skip, deprecated, message = "Renamed to overriddenResponses"
public var overridenResponses: [String: String] = [:]

The annotations:

• skip - Omits the property from the documentation
• deprecated - Causes it to be included in this deprecations array
• message - Extra details to be printed for the user helping to guide them away from this property