Document the Sass migrator (sass#372)

Closes sass#358

Rakefile

@@ -67,6 +67,28 @@ namespace :sass do
     end
   end
 
+  namespace :migrator do
+    # Check out the latest commit of the Sass migrator into the .sass-migrator directory.
+    task :checkout do
+      unless Dir.exists?(".sass-migrator")
+        sh %{git clone git://github.com/sass/migrator .sass-migrator}
+      end
+
+      Dir.chdir(".sass-migrator") do
+        sh %{git fetch}
+        if ENV["SASS_MIGRATOR_REVISION"]
+          sh %{git checkout #{ENV["SASS_MIGRATOR_REVISION"]}}
+        else
+          sh %{git checkout origin/master}
+        end
+      end
+    end
+
+    task :version => :checkout do
+      add_version 'migrator', Dir.chdir(".sass-migrator") {latest_stable_tag}
+    end
+  end
+
   namespace :libsass do
     # Check out the latest commit of Dart Sass into the .libsass directory.
     task :checkout do

helpers/sass_helpers.rb

@@ -322,6 +322,7 @@ def release_url(impl)
     repo =
       case impl
       when :dart; "dart-sass"
+      when :migrator; "migrator"
       when :libsass; "libsass"
       end
 

source/code-snippets/_example-module-migrator.html.md.erb

@@ -0,0 +1,25 @@
+```shellsession
+$ cat style.scss
+$body-bg: #000;
+$body-color: #111;
+
+@import "bootstrap";
+
+@include media-breakpoint-up(sm) {
+  .navbar {
+    display: block;
+  }
+}
+$ sass-migrator --migrate-deps module style.scss
+$ cat style.scss
+@use "bootstrap" with (
+  $body-bg: #000,
+  $body-color: #111
+);
+
+@include bootstrap.media-breakpoint-up(sm) {
+  .navbar {
+    display: block;
+  }
+}
+```

source/documentation/cli/migrator.html.md.erb

@@ -1,5 +1,299 @@
 ---
 title: "Migrator"
+table_of_contents: true
 introduction: >
-  TODO(nweiz): Write this
+  The Sass migrator automatically updates your Sass files to help you move on to
+  the latest and greatest version of the language. Each of its commands migrates
+  a single feature, to give you as much control as possible over what you update
+  and when.
 ---
+
+## Usage
+
+To use the Sass migrator, tell it [which migration][] you want to run and what
+Sass files you want to migrate:
+
+[which migration]: #migrations
+
+```
+sass-migrator <migration> <entrypoint.scss...>
+```
+
+By default, the migrator will only change files that you explicitly pass on the
+command line. Passing the [`--migrate-deps` option][] tells the migrator to also
+change all the stylesheets that are loaded using the [`@use` rule][],
+[`@forward` rule][], or [`@import` rule][]. And if you want to do a test run to
+see what changes will be made without actually saving them, you can pass
+<code>[--dry-run][] [--verbose][]</code> (or `-nv` for short).
+
+[`--migrate-deps` option]: #migrate-deps
+[`@use` rule]: ../at-rules/use
+[`@forward` rule]: ../at-rules/forward
+[`@import` rule]: ../at-rules/import
+[--dry-run]: #dry-run
+[--verbose]: #verbose
+
+<%= partial 'code-snippets/example-module-migrator' %>
+
+## Installation
+
+You can install the Sass migrator from most of the same places that you can
+install [Dart Sass](/dart-sass):
+
+### Standalone
+
+You can install the Sass migrator on Windows, Mac, or Linux by downloading the
+package for your operating system [from GitHub][] and [adding it to your
+`PATH`][].
+
+[from GitHub]: <%= release_url(:migrator) %>
+[adding it to your `PATH`]: https://katiek2.github.io/path-doc/
+
+### npm
+
+If you use Node.js, you can also install the Sass migrator using [npm][] by
+running
+
+[npm]: https://www.npmjs.com
+
+```
+npm install -g sass-migrator
+```
+
+### Chocolatey
+
+If you use [the Chocolatey package manager][] for Windows, you can install the
+Sass migrator by running
+
+[the Chocolatey package manager]: https://chocolatey.org
+
+```
+choco install sass-migrator
+```
+
+### Homebrew
+
+If you use [the Homebrew package manager][] for Mac OS X, you can install Dart
+Sass by running
+
+[the Homebrew package manager]: https://brew.sh
+
+```
+brew install sass/sass/migrator
+```
+
+## Global Options
+
+These options are available for all migrators.
+
+### `--migrate-deps`
+
+This option (abbreviated `-d`) tells the migrator to change not just the
+stylesheets that are explicitly passed on the command line, but also any
+stylesheets that they depend on using the [`@use` rule][], [`@forward` rule][],
+or [`@import` rule][].
+
+```shellsession
+$ sass-migrator module --verbose style.scss
+Migrating style.scss
+$ sass-migrator module --verbose --migrate-deps style.scss
+Migrating style.scss
+Migrating _theme.scss
+Migrating _fonts.scss
+Migrating _grid.scss
+```
+
+### `--dry-run`
+
+This flag (abbreviated `-n`) tells the migrator not to save any changes to
+disk. It instead prints the list of files that it would have changed. This is
+commonly paired with the [`--verbose` option][] to print the contents of the
+changes that would have been made as well.
+
+[`--verbose` option]: #verbose
+
+```shellsession
+$ sass-migrator module --dry-run --migrate-deps style.scss
+Dry run. Logging migrated files instead of overwriting...
+
+style.scss
+_theme.scss
+_fonts.scss
+_grid.scss
+```
+
+#### `--no-unicode`
+
+This flag tells the Sass migrator only to emit ASCII characters to the terminal
+as part of error messages. By default, or if `--unicode` is passed, the migrator
+will emit non-ASCII characters for these messages. This flag does not affect the
+CSS output.
+
+```shellsession
+$ sass-migrator --no-unicode module style.scss
+line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'.
+  ,
+1 | @import "typography";
+  |         ^^^^^^^^^^^^
+  '
+Migration failed!
+$ sass-migrator --unicode module style.scss
+line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'.
+  ╷
+1 │ @import "typography";
+  │         ^^^^^^^^^^^^
+  ╵
+Migration failed!
+```
+
+### `--verbose`
+
+This flag (abbreviated `-v`) tells the migrator to print extra information to
+the console. By default, it just prints the name of files that are changed, but
+when combined with the [`--dry-run` option][] it also prints those files' new
+contents.
+
+[`--dry-run` option]: #dry-run
+
+<%# Indent this because otherwise the table-of-contents generator interprets
+the `===` as a heading. %>
+
+    $ sass-migrator module --verbose --dry-run style.scss
+    Dry run. Logging migrated files instead of overwriting...
+
+    style.scss
+    ================================================================================
+    @use "bootstrap" with (
+      $body-bg: #000,
+      $body-color: #111
+    );
+
+    @include bootstrap.media-breakpoint-up(sm) {
+      .navbar {
+        display: block;
+      }
+    }
+
+    --------------------------------------------------------------------------------
+    $ sass-migrator module --verbose style.scss
+    Migrating style.scss
+
+## Migrations
+
+The migrator currently supports only one migration, but expect more to come as
+the Sass language continues to evolve!
+
+### Module
+
+This migration converts stylesheets that use the old [`@import` rule][] to load
+dependencies so that they use the Sass module system via the [`@use` rule][]
+instead. It doesn't just naïvely change `@import`s to `@use`s—it updates
+stylesheets intelligently so that they keep working the same way they did
+before, including:
+
+* Adding namespaces to uses of members (variables, mixins, and functions) from
+  other modules.
+
+* Adding new `@use` rules to stylesheets that were using members without
+  importing them.
+
+* Converting overridden default variables to [`with` clauses][].
+
+  [`with` clauses]: ../at-rules/use#configuring-modules
+
+* Automatically removing `-` and `_` prefixes from members that are used from
+  other files (because otherwise they'd be considered [private][] and could only
+  be used in the module they're declared).
+
+  [private]: ../at-rules/use#private-members
+
+* Converting [nested imports][] to use the [`meta.load-css()` mixin][] instead.
+
+  [nested imports]: ../at-rules/import#nesting
+  [`meta.load-css()` mixin]: ../modules/meta#load-css
+
+<% heads_up do %>
+  Because the module migrator may need to modify both member definitions *and*
+  member names, it's important to either run it with the [`--migrate-deps`
+  option][] or ensure that you pass it all the stylesheets in your package or
+  application.
+
+  [`--migrate-deps` option]: #migrate-deps
+<% end %>
+
+<%= partial 'code-snippets/example-module-migrator' %>
+
+#### `--remove-prefix`
+
+This option (abbreviated `-p`) takes an identifier prefix to remove from the
+beginning of all variable, mixin, and function names when they're migrated.
+Members that don't start with this prefix will remain unchanged.
+
+The [`@import` rule][] put all top-level members in one global scope, so when it
+was the standard way of loading stylesheets, everyone was incentivized to add
+prefixes to all their member names to avoid accidentally redefining some other
+stylesheet's. The module system solves this problem, so it's useful to
+automatically strip those old prefixes now that they're unnecessary.
+
+```shellsession
+$ cat style.scss
+@import "theme";
+
+@mixin app-inverted {
+  color: $app-bg-color;
+  background-color: $app-color;
+}
+$ sass-migrator --migrate-deps module --remove-prefix=app- style.scss
+$ cat style.scss
+@import "theme";
+
+@mixin inverted {
+  color: theme.$bg-color;
+  background-color: theme.$color;
+}
+```
+
+When you pass this option, the migrator will also generate an [import-only
+stylesheet][] that [forwards][] all the members with the prefix added back, to
+preserve backwards-compatibility for users who were importing the library.
+
+[import-only stylesheet]: ../at-rules/import#import-only-files
+[forwards]: ../at-rules/forward
+
+#### `--forward`
+
+This option tells the migrator which members to forward using the [`@forward`
+rule][]. It supports the following settings:
+
+* `none` (the default) doesn't forward any members.
+
+* `all` forwards all members except those that started with `-` or `_` in the
+  original stylesheet, since that was commonly used to mark a package-private
+  member before the module system was introduced.
+
+* `prefixed` forwards only members that begin with the prefix passed to the
+  [`--remove-prefix` option][]. This option may only be used in conjunction with
+  the `--remove-prefix` option.
+
+  [`--remove-prefix` option]: #remove-prefix
+
+All files that are passed explicitly on the command line will forward members
+that are transitively loaded by those files using the `@import` rule. Files
+loaded using the [`--migrate-deps` option][] will not forward any new members.
+This option is particularly useful when migrating a Sass library, because it
+ensures that users of that library will still be able to access all the members
+it defines.
+
+```shellsession
+$ cat _index.scss
+@import "theme";
+@import "typography";
+@import "components";
+$ sass-migrator --migrate-deps module --forward=all style.scss
+$ cat _index.scss
+@forward "theme";
+@forward "typography";
+@forward "components/button";
+@forward "components/nav";
+@forward "components/drawer";
+```