CLI commands and arguments

[ematipico]

I wanted to kick off a discussion around the CLI, which commands and arguments we should provide and what's the end goal.

Rome classic had an amazing CLI in terms of developer experience and our CLI is not there yet, although we are slowly getting there.

Some of the features (that I am aware about) that we still miss are the following:

• progress bar while executing a task
• ETA of the processed files

Global Arguments:

• --cwd, different working directory (requires having support for configuration file)
• --log-level, showing different type of logging
• --grep to filter diagnostics containing this string
• --log-path, to save logs somewhere
• --output-logs, a way to save logs, by default json
• [UPDATE] --silent not print anything, this is useful

Rome has way more arguments but I think, for now, we can ignore them. Here's the complete list:

  --auxiliary-diagnostic-format <input> When printing diagnostics, output another format alongside - values "github-actions")
                            --benchmark Run a command multiple times, calculating average
           --benchmark-iterations <num> The amount of benchmark iterations to perform - default 10
                      --collect-markers Collect and write performance markers to disk
                           --cwd <path> Specify a different working directory
                                --fieri Head to flavortown
                         --grep <input> Only display diagnostics with messages containing this string - default ""
                             --help, -h Show this help screen
                         --inverse-grep Flip grep match. Only display diagnostics with messages that do NOT contain the grep string
                      --log-path <path> Path where to output logs. When omitted logs are not written anywhere
                         --logs <input> Output server logs - values "all" "error")
        --log-shell-completions <shell> Generate shell completion commands - values "fish" "bash" "zsh")
                          --log-workers Output worker logs
                  --markers-path <path> Path where to write markers. When ommitted defaults to Marker-TIMESTAMP.json
                --max-diagnostics <num> Cap the amount of diagnostics displayed - default 20
                   --no-profile-workers Exclude workers from profile
              --no-truncate-diagnostics Display truncated diagnostic information
             --output-color-depth <num> Change the display width. By default it is automatically inferred and updated from the terminal.
                 --output-columns <num> Change the display width. By default it is automatically inferred and updated from the terminal.
                --output-format <input> Change the output format. By default it is automatically inferred from terminal settings. - values "ansi" 
                                        "html" "none")
                --output-redirect-error Redirect stderr to stdout.
                           --output-tty Treat output as TTY regardless of terminal information. This will enable things like ANSI cursor, progress
                                        bars etc.
                              --profile Collect and write profile to disk. Includes profiles for all processes.
                  --profile-path <path> Path where to write profile. When omitted defaults to Profile-TIMESTAMP.json
          --profile-sampling <microsec> Profiler sampling interval in microseconds - default 100
           --profile-timeout <millisec> Stop the profile after the milliseconds specified. When omitted the profile is of the whole command
                                 --rage Create a rage tarball of debug information
                     --rage-path <path> Path where to write rage tarball. When omitted defaults to Rage-TIMESTAMP.tgz
                       --resolver-mocks Enable mocks for module resolution
         --resolver-platform <platform> Specify the platform for module resolution - values "ios" "android" "mobile" "electron" "web" "node")
                 --resolver-scale <num> Specify the image scale for module resolution
                               --review Display and perform actions on diagnostics. Only some commands support this.
                 --show-all-diagnostics Display all diagnostics ignoring caps
                               --silent Don't write anything to the console
                     --temporary-daemon Start a daemon, if one isn't already running, for the lifetime of this command
                               --timing Dump timing information after running the command
                        --unsafe-writes When writing files, don't verify mtime or existence. Potentially dangerous and could lead to unintended
                                        data loss
                  --verbose-diagnostics Display additional hidden diagnostic information
                              --version Show the version
                                --watch Keep running command and update on file changes. Only some commands support this.
      --write-shell-completions <shell> Write shell completion commands - values "fish" "bash" "zsh")

Commands

• rome format (we already have this one)
• rome lint, only run the linter
• rome check, apply format/lint/etc. (etc. has more stuff like e.g. dependency check, license check, etc.)
• rome config, various operations on the configuration (e.g. rome config enable formatter, rome config set formatter.line_width "120")
• rome init, starts a new project, requires having support of the configuration file
• rome auto-config It scans the project and provides possible fixes to apply to Rome configuration
• rome daemon, various operations around the daemon of rome (e.g. rome daemon start, rome daemon stop)
• rome lsp, connets to an LSP
• rome ci, various operations (lint, format, etc.) in check mode, to use only in CI environments
• rome test, runs the test suite

[leops]

Displaying progress bars is something I have in my "feature backlog" for rome_console, but I never got to implementing it at the moment because all our current commands are really fast, so it would only be displayed for less than a second anyway

[ematipico]

Yeah this is something I thought about it. At the moment we are so fast that it doesn't make much sense (for now), to actually having a progress bar. With these timings, it might feel more like a flick rather than a real progress bar 😆

[MichaReiser]

It's also a common problem that painting the progress bar slows down the overall process. For example, our coverage tests run faster if you remove the progress bar...

[leops]

What exactly is the difference between the rome check and rome ci commands ? Both sound very similar as "command that runs a number of different checks"

[ematipico]

At the moment, rome ci and rome check are the same, but in the future rome ci will do much more, like:

• running tests by freezing the snapshots;
• compile the documentation (when rome will be able to generate documentation) and make sure it's not outdated;

We might have other things that we want to run in the CI but for now that's all I have. Currently rome classic runs formatter, linter and tests. (internally, the test command is not available as standalone command)