[checks] Collapse nested subjects in condition descriptions - #2784

Revisions updated by `dart tools/rev_sdk_deps.dart`.

dartdoc (https://github.com/dart-lang/dartdoc/compare/5eb0f2c..e1859cf):
  e1859cfc  Fri Oct 9 14:53:01 2026 +0200  Sarah Zakarias  Link a bare prefix only when it maps to exactly one library (dart-lang/dartdoc#4295)
  c48f6fb9  Fri Oct 9 14:25:42 2026 +0200  Sarah Zakarias  Resolve prefixes through the analyzer's PrefixElement.scopeLibraries (dart-lang/dartdoc#4294)
  3a6297e2  Wed Oct 7 12:56:14 2026 +0200  Sarah Zakarias  Require analyzer 14.5.0 and bump to 9.0.10 (dart-lang/dartdoc#4292)

ecosystem (https://github.com/dart-lang/ecosystem/compare/16dca7a..622ef61):
  622ef61  Mon Oct 12 00:23:27 2026 -0700  Kevin Moore  fix(firehose): enforce -wip on published versions and tighten changelog checks (dart-lang/ecosystem#467)
  5576a85  Wed Oct 7 09:29:44 2026 +0200  Moritz  Support use-flutter option in groundskeeper workflow (dart-lang/ecosystem#444)

http (https://github.com/dart-lang/http/compare/585d433..23f8574):
  23f8574  Thu Oct 8 23:27:25 2026 +0700  Cong Bang  feat(http2): configurable receive windows and frame size (dart-lang/http#1999)
  18051a6  Thu Oct 8 10:39:38 2026 +0200  Moritz  Enable Flutter in Groundskeeper workflow for Flutter packages (dart-lang/http#2004)

native (https://github.com/dart-lang/native/compare/a2a6179..10515af):
  10515afca  Mon Oct 12 12:21:52 2026 +0200  Daco Harkes  [native_toolchain_c] Do not pass linker flags when compiling static libraries (dart-lang/native#3731)

native is held back at 10515af, before dart-lang/native#3728, because it
breaks the dartdev `dart install` native assets tests. See
dart-lang/native#3743.

test (https://github.com/dart-lang/test/compare/d749b10..30acb69):
  30acb69e  Mon Oct 12 12:42:54 2026 -0700  Nate Bosch  Time out browser loads just before the suite load timeout (dart-lang/test#2786)
  597a0326  Mon Oct 12 12:22:53 2026 -0700  Kevin Moore  Fix misplaced changelog entries and remove no-op health check (dart-lang/test#2789)
  0b6efee8  Mon Oct 12 12:16:29 2026 -0700  Nate Bosch  [checks] Collapse nested subjects in condition descriptions (dart-lang/test#2784)
  17c98493  Mon Oct 12 12:08:23 2026 -0700  Nate Bosch  Follow symlinks in precompiled browser test directories (dart-lang/test#2787)
  1cc813ec  Fri Oct 9 11:59:56 2026 -0700  Nate Bosch  [checks] Join nested collapsed subjects with "that" (dart-lang/test#2783)
  ada7b950  Thu Oct 8 12:03:42 2026 -0700  Nate Bosch  Prepare to publish (dart-lang/test#2780)
  c4b165b3  Wed Oct 7 11:29:08 2026 -0700  Kevin Moore  [checks] Require package:meta ^1.17.0 (dart-lang/test#2779)
  4a363d70  Tue Oct 6 10:46:31 2026 -0700  Nate Bosch  Let Chrome choose its remote debugging port (dart-lang/test#2778)
  465d66ab  Tue Oct 6 09:35:22 2026 -0700  Nate Bosch  Keep Chrome stderr in the browser output when debugging (dart-lang/test#2777)

tools (https://github.com/dart-lang/tools/compare/a66d517..2b54c71):
  2b54c71af  Mon Oct 12 10:16:45 2026 +0200  dart-ecosystem-bot[bot]  [boring] Update BoringSSL to 3fed4f20 (dart-lang/tools#2655)
  2337f995a  Sat Oct 10 03:11:40 2026 +0300  Hasan Armoush  [json_rpc_2] Add strictProtocolChecks parameter to Client (dart-lang/tools#2555)
  c65c69ed1  Fri Oct 9 08:54:25 2026 +0200  Moritz  [boring] Move package:boring to dart-lang/tools (2/4): FFI helpers from package:webcrypto (dart-lang/tools#2615)
  a04e45491  Thu Oct 8 21:07:18 2026 -0700  Kevin Moore  chore: wire package:api_summary and package:string_scanner PR auto-labeler (dart-lang/tools#2652)
  8bdd4b92c  Thu Oct 8 09:20:48 2026 +0200  Morgan :)  [code_builder] Allow built_collection 6.x. (dart-lang/tools#2645)
  c16040d35  Wed Oct 7 17:30:08 2026 -0700  Kevin Moore  [api_summary] Sort primary barrel first and experimental entry points last (v1.2.0) (dart-lang/tools#2619)
  b2d0780db  Wed Oct 7 11:27:16 2026 -0700  Kevin Moore  [stream_channel] Require package:async ^2.6.0 (dart-lang/tools#2644)
  3ab7bf9d0  Wed Oct 7 11:35:27 2026 +0200  Moritz  [boring] Move package:boring to dart-lang/tools (1/4): vendored BoringSSL, bindings and source build (dart-lang/tools#2614)
  29df6348b  Tue Oct 6 15:21:44 2026 -0700  Kevin Moore  feat(coverage): support web coverage reports in test_with_coverage (dart-lang/tools#2448)

Regenerate pkg/{analyzer,analyzer_plugin,analyzer_testing}/api.txt. The
rolled package:api_summary v1.2.0 (dart-lang/tools#2619) sorts the primary
barrel first and other entry points after it, so entries in these files
are reordered. The APIs themselves are unchanged.

Change-Id: Ie8ff19c5a981ea8ecee8939c75457986a947e0a7
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/563220
Reviewed-by: Samuel Rawlins <[email protected]>
Auto-Submit: Nate Bosch <[email protected]>
Reviewed-by: Paul Berry <[email protected]>
Commit-Queue: Paul Berry <[email protected]>

`IterableChecks.any`, `IterableChecks.every`,
`MapChecks.containsKeyThat`, and `MapChecks.containsValueThat` embed the
description of a condition. They collapse to a single line at the root,
through a predicate noun such as `an iterable containing a value that is
greater than <7>`, but their clause always used the multi-line form of a
label followed by the indented description. Where the clause itself is
shown, such as when one of these expectations is nested inside the
condition of another, the description never collapsed, while the same
check reached through `has` did. Reported in
#2784 (comment):

    check([[1]]).any(.it()..any(.it()..isGreaterThan(1)));

    Expected: a List<List<int>> that:
      contains a value that:
        contains a value that:
          is greater than <1>

Add an internal `describedClause` helper next to
`describedPredicateNoun`. It joins the label to the description of the
condition on a single line when the condition describes in a single line
and the result fits within 80 columns, and otherwise keeps the label
followed by the indented description. Both helpers share the logic for
joining and the length limit. Use it for the clauses of all four
expectations. The inner `any` above now describes itself as a single
line, so the outer `any` collapses to a single `Expected:` line at the
root:

    an iterable containing a value that contains a value that is
    greater than <1>

Joining the label of `every`, `only has values that`, to a description
such as `is less than <10>` reads as `only has values that is less than
<10>`. Describe the condition as `only has elements where each` instead,
which reads as `only has elements where each is less than <10>` on one
line, and `only has elements where each:` followed by the description
otherwise. The label is a predicate over the iterable ending with a
singular noun, so it also reads as a sentence when `every` is nested in
another condition, such as `an iterable where every element only has
elements where each is less than <10>`. Change the predicate noun to
match the wording: `an iterable where every element is less than <10>`.

Expectations which soft check a condition against part of their value,
such as `IterableChecks.every`, describe the failure within the `which` of
their own rejection. Each of `every`, `IterableChecks.deepEquals`,
`StreamChecks.inOrder`, `StreamChecks.anyOf`, and
`IterableChecks.pairwiseMatches` formatted the nested failure by hand, each
slightly differently, and each dropped detail in some cases. Two bugs in
`every` were reported in
#2784 (review).

Add `CheckFailure.describeNested`, which describes a failure in the same
format as a failure message from `check`. A soft checked condition has no
label for its root subject, so the caller provides its own line describing
the value, such as `has an element at index 0 that:`. When the actual does
not collapse to a single line, a line with only `Actual:` takes the place
of the `Actual: <label> that:` line from `check`. `check` and
`describeNested` share a private method which produces the "Actual:" and
"Which:" lines, so the two formats agree by construction. `CheckFailure` is
exported only from `package:checks/context.dart`, so the method is
available to authors of expectations without being part of the API for
writing checks.

Use `describeNested` from `every`, `deepEquals`, `inOrder`, `anyOf`, and
`pairwiseMatches`.

- `every` and `deepEquals` lost the property name when the nested failure
  collapsed:

      Which: has an element at index 0 that:
        Actual: 'foo'

  It now reads `Actual: has field: 'foo'`. `deepEquals` also uses `Which:`
  in place of `which`.
- `inOrder` and `anyOf` dropped the actual description entirely when a
  condition failed without collapsing, including when the actual collapsed
  to the root. They now always include an `Actual:` line, and no longer
  repeat an `Expected:` line for a collapsed failure since the outer
  description already lists each condition.
- `pairwiseMatches` keeps the description of the condition for the element,
  followed by `Actual:` in place of `Actual element at index N:`, so the
  expected and actual descriptions are separated:

      does not have an element at index 0 that:
        has field: 'foo'
        has field that has length: <4>
        Actual:
          has field: 'foo'
          has field that has length: <3>
          Which: is not equal

Fix the failure details when a soft check rejects a precondition such as
`isA<T>()` and further expectations follow it, which also affected `every`:

    check([Wrapper(123)])
        .every(.it()..value.isA<Foo>().field.equals('bar'));

    Failed assertion: 'foundDepth == -1': is not true.

`_fullDetails` assumed that when a subject itself failed, the failing clause
was the last one added to it. That holds for `check`, where a failure
throws before anything else is added, but not for a soft check, where the
following nested clauses are still added, nor for an unawaited expectation,
which can fail after later clauses are added. Pass the rejected clause from
each failure through to `_fullDetails` instead of relying on
`_clauses.last`. A rejected guard is also no longer added a second time as
a `_GuardClause`, since the failing expectation clause already describes
it, so the precondition appears once in the description.

Omit the clauses after the failing one from the failure details. They were
described under `Actual:` as if the value satisfied them, and when the
failing clause came first the actual collapsed onto the root line with the
later clauses printed as its children.

Keep asynchronous expectations in the order they were made, and leave out
any which have not finished when another expectation fails. Nested
asynchronous expectations such as `completes` and `emits` added their clause
only once the value arrived, so an expectation made after them was described
before them. An expectation from
`Context.expectAsync` added its clause before its predicate finished, so it
was described as satisfied if a later expectation failed first. Both now
add a placeholder which keeps their place and is not described until they
finish. Expectations from `Context.expectUnawaited`, such as
`doesNotComplete`, are never awaited by the check and are still described
as satisfied until they fail.

Make the `CheckFailure` and `FailureDetail` constructors private. Failures
only come from soft checking a `Condition`, since `Condition` and `Context`
are `abstract final`, and no API accepts a failure constructed outside the
package. The public `FailureDetail` constructor also recorded that any
custom `actual` started with the root label line, so `describeNested`
dropped its first line.