Add usage instructions for spec runner to compiler

[straight-shoota]

Currently, crystal spec --help only shows compile time options. The runtime options are missing and only show up once you have compiled a spec runner.

This separation has technical reasons but results in aweful user experience. crystal spec presents itself as an holistic interface for running specs and transparently delegates runtime options to the executable. You can pass runtime options directly to crystal spec, but they don't show up in the usage overview. So many of the options are hidden to the user. You only discover them if you are aware of running crystal spec -- --help.

This is the old (separate) output:

$ crystal spec --help
Usage: crystal spec [options] [files]

Options:
    -d, --debug                      Add full symbolic debug info
    --no-debug                       Skip any symbolic debug info
    -D FLAG, --define FLAG           Define a compile-time flag
    --error-trace                    Show full error trace
    --release                        Compile in release mode
    -s, --stats                      Enable statistics output
    -p, --progress                   Enable progress output
    -t, --time                       Enable execution time output
    -h, --help                       Show this message
    --no-color                       Disable colored output
    --warnings all|none              Which warnings detect. (default: all)
    --error-on-warnings              Treat warnings as errors.
    --exclude-warnings <path>        Exclude warnings from path (default: lib)
$ crystal run spec.cr -- --help
crystal spec runner
    -e , --example STRING            run examples whose full nested names include STRING
    -l , --line LINE                 run examples whose line matches LINE
    -p, --profile                    Print the 10 slowest specs
    --fail-fast                      abort the run on first failure
    --location file:line             run example at line 'line' in file 'file', multiple allowed
    --tag TAG                        run examples with the specified TAG, or exclude examples by adding ~ before the TAG.
    --order MODE                     run examples in random order by passing MODE as 'random' or to a specific seed by passing MODE as the seed value
    --junit_output OUTPUT_PATH       generate JUnit XML output within the given OUTPUT_PATH
    -h, --help                       show this help
    -v, --verbose                    verbose output
    --tap                            Generate TAP output (Test Anything Protocol)
    --no-color                       Disable colored output

With this patch the usage instructions for the spec runner are included in the usage instractions for the compiler spec command.

The actual OptionParser from stdlib is used for that to avoid maintaining different instructions and have them slip out of sync. There would only be a discrepancy when the compiled stdlib version has different options than the one the compiler was built with. But that's acceptable.
The only option to avoid that would be to compile or somehow extract the information from Spec module from stdlib source. This could be more feasible if a textual representation like docopt was used instead of OptionParser builing it at runtime.

In order to not include large parts of the Spec module in the compiler, the option parser configuration has been extracted to src/spec/cli.cr in a way that it does not rely on any other spec feature. The only intricacy is setting up the formatters. I've introduced Spec.configure_formatter for this which has a blank implementation in cli.cr and the real one in spec.cr overrides it for actual use.

New output of crystal spec --help:

Usage: crystal spec [options] [files]

Options:
    -d, --debug                      Add full symbolic debug info
    --no-debug                       Skip any symbolic debug info
    -D FLAG, --define FLAG           Define a compile-time flag
    --error-trace                    Show full error trace
    --release                        Compile in release mode
    -s, --stats                      Enable statistics output
    -p, --progress                   Enable progress output
    -t, --time                       Enable execution time output
    -h, --help                       Show this message
    --no-color                       Disable colored output
    --warnings all|none              Which warnings detect. (default: all)
    --error-on-warnings              Treat warnings as errors.
    --exclude-warnings <path>        Exclude warnings from path (default: lib)
    -h, --help                       Show this message

Runtime options (passed to spec runner):
    -e , --example STRING            run examples whose full nested names include STRING
    -l , --line LINE                 run examples whose line matches LINE
    -p, --profile                    Print the 10 slowest specs
    --fail-fast                      abort the run on first failure
    --location file:line             run example at line 'line' in file 'file', multiple allowed
    --tag TAG                        run examples with the specified TAG, or exclude examples by adding ~ before the TAG.
    --order MODE                     run examples in random order by passing MODE as 'random' or to a specific seed by passing MODE as the seed value
    --junit_output OUTPUT_PATH       generate JUnit XML output within the given OUTPUT_PATH
    -h, --help                       show this help
    -v, --verbose                    verbose output
    --tap                            Generate TAP output (Test Anything Protocol)
    --no-color                       Disable colored output

[Fryguy]

This is awesome! I had a very similar refactoring locally (which included a lot more than just the CLI), so I'm very happy to see this.

[bcardiff]

The runtime_options can be passed before the file, there is no need to use -- to split them. Wouldn't that be the preferred way to advertise them?

In that line of thought I would call the "Spec runner additional options" or somehing like that.
I find it confusing that they are presented as "Runtime options"

[straight-shoota]

Yes, the -- can be removed. I'd still leave it as [options] [files] [runtime_options] even though they can be mixed. Don't think there's a better way to do this and this makes at least sense from a structural PoV.

Naming is particularly hard with this one. I'm not convinced Spec runner additional options improves it, though. I would have more questions about that than Runtime options which is really just a factual description. Those are the options evaluated at runtime by the spec runner, the others are compiler options.

[straight-shoota]

I would love to see this in 1.0 as it's a really nice and cheap enhancement for developer convenience.

[sdogruyol]

Wow thank you @straight-shoota, this is great developer UX 💯 I'd also love to see this land in 1.0 if possible 🤔