Smarter handling of "block" and "headline" formatting.

[munificent]

The formatter has a notion of "block formatting" that comes into play in places like:

// No indentation needed for RHS here:
variable = [
  block,
  formatted,
];

// Indentation needed here:
variable =
    notBlock +
    formatted;

A hard design question in the formatter is whether we can determine if an AST node is "block-formatted" or "block-formattable" eagerly based just on the AST or whether it has to be figured out later during solving.

Eagerly is appealing because we have access to the full AST and know what the actual source code the user wrote is before it gets lowered to a Piece tree that might obscure that. (In other words, there might be two ASTs that we want to format differently that get lowered to Pieces that are hard to distinguish.) It's also generally good for performance to make as many formatting decisions as we can before going into the solver.

But it turns out that there are cases where we really don't know if a AST node will end up block shaped or not. Consider:

variable = (target + expression).method(argument, another);

If we're able to fit the method target on one line and instead split in the argument list, then the RHS of = does end up block-shaped:

variable = (target + expression).method(
  argument,
  another,
);

Nice. But if the target is too long for that to work, then we should not consider the method call block-shaped. We don't want to allow:

variable = (target +
      expression).method(
  argument,
  another,
);

But as you can see, we can't tell that just looking at the AST. It depends on how the formatter formats that target expression.

Alas, I didn't realize this problem early on in the rewrite and by the time it became clear to me, it was too late to start over again. Since then, I've tried several times to refactor towards a model where we can express these shaped-based formatting constraints during solving without (hopefully) completely tanking performance.

This PR is that. I've broken it into a series of commits to try to make it more digestible, but it's still a pretty big change. But it significantly improves the output and I think also builds a foundation to support other more sophisticated style rules we might want.

Here's the basic idea. Much of formatting is about resolving constraints between parent and child nodes. For example, we want to avoid output like:

operand + (anotherOne *
    thingOperand) + fourth;

Here, there is a split in the * expression but it doesn't cause the surrounding + expressions to split. That makes for very hard to read code. The way the formatter handles this is by having constraints where it says "if a newline occurs inside child X, then parent Y can't be in state Z." In the case of InfixPiece, the constraint is simply that a newline in any operand forces the InfixPiece to fully split.

It's a really simple model. Each Piece defines a list of states, and then for each state, it defines which children may contain newlines. That gets you surprisingly far. But it struggles with code like:

variable = (target + expression).method(
  argument,
  another,
);

// Versus:
variable = (target +
    expression).method(argument, another);

Here, there is a newline in the RHS child of the assignment in both cases, but they're different kinds of newlines. We want the first one to be OK and allow the = on the same line as the target, but not the second one.

To support this, we expand the constraint model a bit. Instead of just "newline or not", the presence of newlines in a child piece puts it into one of a few shapes. The shapes are:

// Shape.inline:
all + one + line;

// Shape.block:
[
  delimited,
  andBlockIndented,
]

// Shape.headline:
somethingOnFirstLine
    .moreStuff()
    .afterThat();

// Shape.other:
anything +
    else;

Then we allow pieces to constrain their children not just to disallow newlines but to permit certain shapes and prohibit others. In practice, basically AssignPiece is the only one that really cares about this. But given how prevalent =, :, and => are (which all use AssignPiece), that ends up having a large impact on formatting quality.

In order to get this working, I also had to add some other machinery like a slightly smarter system for handling indentation. And it let me get rid of some of the other ways of modelling constraints (like most uses of the applyConstraints() API).

The main goal is to finally be able to fix #1465 and #1466 in a non-hacky robust way. But I hope this will make it easier to implement other style changes too. By pushing more of the formatting choices into the back end where we know how the child actually formatted, the parent can take that into account.

Aside from fixing those issues, these changes also tweak the output around assignments with complex operands in ways that are hard to describe precisely. Given a piece of code like:

var constructedRequest = new Request()
  ..campaignId = (rollup.campaignId == null ? new Int64(0) : rollup.campaignId);

It could be formatted a variety of ways with no clear best:

var constructedRequest = new Request()
  ..campaignId = (rollup.campaignId == null ? new Int64(0) : rollup.campaignId);

var constructedRequest = new Request()..campaignId =
    (rollup.campaignId == null ? new Int64(0) : rollup.campaignId);

var constructedRequest =
    new Request()
        ..campaignId = (rollup.campaignId == null
            ? new Int64(0)
            : rollup.campaignId);

And with the scale of this refactoring, sometimes the formatter makes different choices. I plan to tweak it a little more going forward (now that it's easier to do so). But, overall, I don't think it makes any of these cases worse, and supporting headline-style formatting makes a lot of code much better.

Unfortunately, this PR regresses performance. Roughly ~20% on the microbenchmarks. As far as I can tell, there are no new pathological performance corners, it's just a little uniformly slow everywhere. I have some ideas on how to claw the performance back but if not, I can live with it. So far, users have complained about the output but not performance.

[kallentu]

I'm happy with the structural changes and the commits were nice to go through. Thanks for working on this, Bob.

[passsy]

Interesting read, thanks for taking the extra time!