[flang] Improve syntax error messages by fixing withMessage() parser combinator

The parser combinator withMessage("error message"_err_en_US, PARSER) is meant
to run the parser PARSER and, if it fails, override its error messages if
it failed silently or it was unable to recognize any tokens at all.  This
gives the parser a way to avoid emitting some confusing or missing error
messages.  Unfortunately, the implementation could sometimes lose track of
whether any tokens had been recognized, leading to problems with outer usage
of withMessage() and also -- more seriously -- with ParseState::CombineFailedParses().
That's a utility that determines which error messages to retain when two
or more parsers have been attempted at the same starting point and none
of them succceed.  Its policy is to retain the state from the parser that
consumed the most input text before failing, so long as it had recognized at
least one token.

So anyway, fix up withMessage(), adjust the tests, and add a test of the
original motivating confusing error situation, in which a syntax error in
a COMMON statement was being diagnosed as a problem with a statement function
definition because withMessage() had lost the fact that the parse of the
COMMON statement had recognized some tokens, and the last attempted parse
later was a failed attempt to parse a statement function.

Differential Revision: https://reviews.llvm.org/D135216