Description
While the usage of the output dir is technically consistent, it comes across a little confusing. Lets take the following examples:
This is not always the case though, because sometimes create-api will generate the nested directory for you:
create-api generate schema.json --package "FooKit" --output ./ --no-split:
$ tree .
.
├── FooKit
│ ├── Package.swift
│ └── Sources
│ ├── Entities.swift
│ └── Paths.swift
├── .create-api.yaml
└── schema.json
create-api generate schema.json --module "FooKit" --output ./ --no-split:
$ tree .
.
├── Entities.swift
├── Paths.swift
├── .create-api.yaml
└── schema.json
Writing generated code to the same directory as non-generated code is probably not a great idea in general, but when using --package, it seems to align with the kind of output that you might expect since a single folder with the name of the package is written into the output directory.
This however is not the case with using --module.
Making --split the default/recommended option now means that its more common to run into scenarios where you need to clean the generated outputs in the event that an entity or path was removed from the schema (because the next generator run wouldn't overwrite it).
Clean is documented (and behaves) like so:
-c, --clean Removes the output folder before continuing
Using --clean in the above two examples would cause the generator to unexpectedly(?) delete the entire contents of ./ including schema.json and .create-api.yaml, something I don't think that we ever want to happen.
For consistency, I propose that we align --package and --module behaviours so that the generated output always goes directly into --output. This should hopefully encourage people to always specify a subdirectory for their generated outputs instead of writing them into ./.
To demonstrate, with my proposed changes, it would be more common for people to run the following instead:
create-api generate schema.json --package "FooKit" --output ./Generated --no-split:
$ tree .
.
├── Generated
│ ├── Package.swift
│ └── Sources
│ ├── Entities.swift
│ └── Paths.swift
├── .create-api.yaml
└── schema.json
create-api generate schema.json --module "FooKit" --output ./Generated --no-split:
$ tree .
.
├── Generated
│ ├── Entities.swift
│ └── Paths.swift
├── .create-api.yaml
└── schema.json
While this helps with using --clean in these scenarios, it doesn't completely make clean safe. There are probably still times when you might set --output to ./, for example if you are pushing a package to a repository, you need Package.swift at the top level, but you might also want to commit the schema/config to keep everything in one place.
For the immediate problem of mistakenly deleting configs/schemas, we can add a check to make sure that when using --clean, the config and schema path aren't inside output.