Cli Rewrite PoC

[shayanhabibi]

File Changes for orientation

Fable.Cli/Entry.fs has been removed in principle

New files:

• Spec.fs
• Settings/*.fs
• Commands/*.fs
• Entry.fs

Musings

CLI

This reworked CLI uses Spectre.Console to manage the CLI interface. Using the framework, we are able to reason about the settings more intuitively, although it uses a C# like OOP approach.

The value provided by offloading the CLI abstraction to a library for the Fable CLI tool is worth this cost.

Backwards Compatibility

This implementation permits all operations being handled from the default command, except for clean. This maintains backwards compatibility.

All previous switches and commands are supported the same.

Deprecated options such as --verbose and --silent are still functional, although now hidden. These switches are superseded by the --verbosity option. --verbosity takes precedence over the deprecated switches.

Future Proofing

As more targets mature in Fable, the need to separate CLI options and switches for the different targets will grow.

While the backing compilation system is not changed, the CLI interface is designed for this eventuality.

flowchart
    subgraph Interfaces
        subgraph targetAgnostic [Target Agnostic Args]
            ICommonArgs
            ICompilingArgs
        end
        subgraph targetSpecific [Target Specific Args]
            IJavaScriptArgs
            ITypeScriptArgs
            IPythonArgs
            IRustArgs
            IPhpArgs
            IDartArgs
        end
        ICommonArgs --> ICompilingArgs
        ICompilingArgs --> IJavaScriptArgs
        ICompilingArgs --> ITypeScriptArgs
        ICompilingArgs --> IPythonArgs
        ICompilingArgs --> IRustArgs
        ICompilingArgs --> IPhpArgs
        ICompilingArgs --> IDartArgs
        IJavaScriptArgs --> ICliArgs
        ITypeScriptArgs --> ICliArgs
        IPythonArgs --> ICliArgs
        IRustArgs --> ICliArgs
        IPhpArgs --> ICliArgs
        IDartArgs --> ICliArgs
    end
    subgraph Settings
        ICliArgs --Superset of interfaces implemented
        by base settings class without
        exposing any options--> FableBase
        FableBase --Exposes all
        interface args
        as options--> Fable
        FableBase --Same as Fable
        but has watch switch on--> Watch
        FableBase --Only exposes
        the ICommonArgs subset
        of args as options--> Clean
        FableBase --Exposes common
        compiling args as
        options, but excludes
        options that are preset
        by commands like language
        and watch related options--> CompilingBase
        CompilingBase --Exposes JavaScript
        specific args as options--> JavaScript
        CompilingBase --> TypeScript
        JavaScript --Exposes watch related
        options--> JavaScriptWatch
        TypeScript --> TypeScriptWatch
        ...Others --> ...OthersWatch
        CompilingBase --> ...Others
    end
    Interfaces ---> Settings

Loading

This provides a structure that is compatible with the current compiler backing, as all Setting types are compatible with the superset of args. This is a non issue for the CLI consumers, as each Setting type only exposes their specific options via attributes.

The structure lends itself to iteration towards allowing targets to safely add their own switches as desired, and also create consuming functions of the CLI interface for different targets to handle their subset of Cli args only, with intellisense completions that are not polluted by other target language options.

Aggregate Validation Errors

The validation of args occurs almost entirely in the base settings class for all arguments/options. This is handy for providing aggregated validation errors.

Previous behaviour

Progress

The CLI interface is almost completely hooked into the previous compilation system. Just need to hook the --run flags in (I was originally going to look at having multiple --run flags working, but I'll probably just keep away from changing the backend atm).

Have to ensure the path normalizations done in the previous implementation are reflected in this implementation.

Also want to reorder the flags.

Images

fable --help

fable clean --help

fable watch --help

fable js --help

fable js watch --help

fable py --help

fable py watch --help

QoL

[shayanhabibi]

@MangelMaxime @dbrattli @nojaf

There's the option of doing the rewrite with Fargo instead, so that we can generate autocompletion scripts.

I'll be able to progress this PR and refine it if we are happy to use the Spectre approach. I'll be able to provide help to a pull with Fargo, but I'm time starved at the moment, and enough time has been sunk into this that I can't afford to pivot atm (but happy to assist if someone does a pull).

I don't see why we can't make a script generation of our own from Spectre, but it's just a matter of time.

This is a circumstance where I actually would value the aesthetic appeal of the tool more than the autocompletion (in my opinion), as it is sorely dated, and looks 'beta-ish'. The features with interactivity and what not in spectre can also lend themselves to developing nice to have QoL features down the line (I'm thinking project setup with multi selection, or file stats using stacked bar graphs).

But, the usability of the tool should be priority. I do agree.
With the number of commands and options that fable has, and the tendency to abstract it away with scripts, I don't see as much value to autocompletion though.

I'd appreciate a comment if you would like this PR progressed. I'll leave it as it is for the time being.

[shayanhabibi]

Actually it seems System.CommandLine will be the way to go. I believe the author of Spectre also contributes to that.

Provides the autocompletion, and enough access to the rendering to allow us to style with spectre.

[shayanhabibi]

Superseded by #4220