Find nearest node when formatting range (#1659)

* Move range extension code into helper functions

* Add findNodeByOffset() helper

This was adapted from https://github.com/prettier/prettier/pull/1637/commits/cbc1929c64db558b4e444500bca3d2ce1d550359

* Test extending formatted range to entire node

* Fix extending formatted range to entire node

* Fix style errors

* Add run_file test function

This makes it possible to use different options on a per-file basis,
which is useful for things like range formatting tests.

* Test extending the format range to nearest parseable node

This means you can select the range of a `catch` clause, attempt to
format it, and have the `try` formatted as well, rather than throwing an
error.

* Fix extending the format range to nearest parseable node

This means you can select the range of a `catch` clause, attempt to
format it, and have the `try` formatted as well, rather than throwing an
error.

* Test that external indentation is left alone when formatting a range

* Preserve external indentation when formatting a range

* Dedupe range formatting traversal callbacks

* Simplify range formatting traversal using ast-types

See https://github.com/prettier/prettier/pull/1659#issuecomment-302974798

* Make range formatting traversal more efficient

There's less unnecessary parsing now.

* Fix style errors

* Add test where range expanding fails

* Fix test where range expanding fails

This makes sure that the range contains the entirety of the nodes
containing each of the range's endpoints.

* Add test for expanding range to beginning of line

* Pass test for expanding range to beginning of line

This makes it so that indentation before the range is added to the
formatted range.

* Don't parse/stringify AST to detect pre-range indentation

See https://github.com/prettier/prettier/pull/1659#discussion_r117790671

* When formatting a range, find closest statement rather than parsing

The `isStatement` implementation came from `docs/prettier.min.js`.

See https://github.com/prettier/prettier/pull/1659#issuecomment-303154770

* Add test for range-formatting a FunctionDeclaration's argument object

* Include FunctionDeclaration when searching for nearest node to range-format

From the spec, a Program is a series of SourceElements, each of which is
either a Statement or a FunctionDeclaration. See
https://www.ecma-international.org/ecma-262/5.1/#sec-A.5

* Remove unnecessary try-catch

See https://github.com/prettier/prettier/pull/1659#discussion_r117810096

* Add tests with multiple statements

See https://github.com/prettier/prettier/pull/1659#discussion_r117810753

* Remove unnecessary arguments from findNodeByOffset()

* Contract format range to ensure it starts/ends on nodes

* Specify test ranges in the fixtures

See https://github.com/prettier/prettier/pull/1659#discussion_r117811186

* Remove unnecessary comments from range fixtures

* Remove run_file test function

It's no longer used. This essentially reverts
8241216e68f2e0da997a4f558b03658d642c89a2

* Update range formatting docs

Clarify that the range expands to the nearest statement, and not to the
end of the line.

* Don't overwrite test options when detecting range

Now that multiple files share the same object again, we shouldn't be
re-assigning to it.

* Reuse already-read fixtures for AST_COMPARE=1 tests

* Remove `run_file` global from test eslintrc

* Undo package.json churn

`yarn` reformatted it before, but the whitespace visually sets off the
comment, so let's put it back how it was before.

See https://github.com/prettier/prettier/pull/1659#discussion_r117864655

* Remove misleading comments from isSourceElement

See https://github.com/prettier/prettier/pull/1659#discussion_r117865196

* Loop backwards through string instead of reversing it

See https://github.com/prettier/prettier/pull/1659#discussion_r117865759

* Don't recompute indent string when formatting range

See https://github.com/prettier/prettier/pull/1659#discussion_r117867268

* Rename findNodeByOffset to findNodeAtOffset

"Find x by y" is the common usage for finding an `x` by a key `y`.
However, since "by" has positional meaning, let's use "at" instead.

See https://github.com/prettier/prettier/pull/1659#discussion_r117865121

* Always trimRight() in formatRange and explain why

See https://github.com/prettier/prettier/pull/1659#discussion_r117864635

* Test formatting a range that crosses AST levels

See https://github.com/prettier/prettier/pull/1659#issuecomment-303243688

* Fix formatting a range that crosses AST levels

See https://github.com/prettier/prettier/pull/1659#issuecomment-303243688

* Remove unnecessary try-catch

See https://github.com/prettier/prettier/pull/1659/files/e52db5e9f9ec4af599f658da03739e206dd4578c#r117878763

* Add test demonstrating range formatting indent detection

* Detect alignment from text on line before range, but don't reformat it

This avoids reformatting non-indentation that happens to precede the
range on the same line, while still correctly indenting the range based
on it.

See https://github.com/prettier/prettier/pull/1659#discussion_r117881430

bin/prettier.js

@@ -232,8 +232,12 @@ if (argv["help"] || (!filepatterns.length && !stdin)) {
       "  --trailing-comma <none|es5|all>\n" +
       "                           Print trailing commas wherever possible. Defaults to none.\n" +
       "  --parser <flow|babylon>  Specify which parse to use. Defaults to babylon.\n" +
-      "  --range-start <int>      Format code starting at a given character offset. The range will extend backwards to the start of the line. Defaults to 0.\n" +
-      "  --range-end <int>        Format code ending at a given character offset (exclusive). The range will extend forwards to the end of the line. Defaults to Infinity.\n" +
+      "  --range-start <int>      Format code starting at a given character offset.\n" +
+      "                           The range will extend backwards to the start of the first line containing the selected statement.\n" +
+      "                           Defaults to 0.\n" +
+      "  --range-end <int>        Format code ending at a given character offset (exclusive).\n" +
+      "                           The range will extend forwards to the end of the selected statement.\n" +
+      "                           Defaults to Infinity.\n" +
       "  --no-color               Do not colorize error messages.\n" +
       "  --version or -v          Print Prettier version.\n" +
       "\n"