Deprecate "dartfmt" in favor of "dart format"

[munificent]

The Dart SDK now exposes a single dart command line executable with subcommands for all of the main tasks you might like to perform: run code, run tests, etc. To format your code, you can now run dart format. Eventually, we plan to remove the dartfmt executable from the Dart SDK. Two things make this a little more complicated:

New CLI options

The command line options supported by dartfmt are not very usable, and the output is verbose. When we added the new dart format command, I took the opportunity to completely revamp the options. The dart format command does away with the annoying required -w option and the hundreds of "Unchanged..." lines. The new CLI is more usable, flexible, and consistent with other dart commands. It is also incompatible with the old option set.

Package CLI

In addition to running the formatter through the Dart SDK, the dart_style package also exposes a command line executable that can be invoked like:

$ pub run dart_style:format

Or:

$ pub global install dart_style
$ dartfmt

That executable still uses the old options. It would be nice to eventually completely remove the old option code, which means the dart_style:format command should either go away or also move over to the new options.

As far as I can tell, the package executable is not widely used. We could deprecate it and remove it in a future breaking release of dart_style. But I do think exposing an executable is useful because it gives users a way to write scripts that run a specific version of the formatter. This may become important if we want to make larger formatting changes and users want to control when they migrate to them.

To that end, I propose we keep the format executable in dart_style but move it over to the new CLI options in a future breaking release.

Migration plan

• Document differences between the old and new CLIs (https://github.com/dart-lang/dart_style/wiki/CLI-Changes)
• Migrate travis-ci scripts to use dart format (when Dart SDK is >= 2.10.0)
• Migrate VSCode integration to use dart format (when Dart SDK is >= 2.10.0)
• Migrate IntelliJ plug-in to use dart format (when Dart SDK is >= 2.10.0)
• Migrate Dart team tools and scripts that invoke dartfmt
  • pkg/analyzer_utilities/lib/tools.dart (Migrate pkg/analyzer_utilities/lib/tools.dart off dartfmt sdk#46046)
• Make SDK shell scripts print deprecation warning (https://dart-review.googlesource.com/c/sdk/+/202144)

After Dart 2.14 ships:

• Remove dartfmt shell scripts from the SDK.

In a future breaking change release of dart_style:

• Move bin/format.dart to use the new CLI options and remove the old option code.

[munificent]

Timing note: We want dartfmt printing the deprecation notice before 2.14 ships on stable (though we don't plan to remove support in 2.14).

[leafpetersen]

LGTM

[mit-mit]

I'm not entirely convinced that retaining the ability to run the "raw package" as an executable is worth the extra complexity and cot. But if you feel passionately that we should keep it then ok.

[munificent]

I think the cost of exposing an executable in the package is relatively low. And I have some vague anticipation that the new change process for dart format may open the door to larger more interesting formatting changes. If that happens, it will be more useful for users to be able to pin to a specific version of the formatter so they can adopt the change when they want to.

[mit-mit]

I was more worried about all kinds of "interesting" compatibility issues around version combination of the Dart SDK and the formatter. But perhaps this is less of an issue with the formatter, which is less semantic.

[mit-mit]

CR in https://dart-review.googlesource.com/c/sdk/+/202144

[mit-mit]

CR has landed. @munificent can we close this bug?

[munificent]

This is also tracking the deprecation and removal of the old CLI from the dart_style package itself, so I'm going to leave it open until that's complete. If that makes it harder for you, let me know and I can split that work into a separate bug.