Add types and assertions for parts of the Perforce diff logic.

Review Request #12618 — Created Sept. 22, 2022 and submitted — Latest diff uploaded


Perforce has some complex diff logic, and not all of it is instrumented
or even comprehensively documented based on actual usage.

In preparation for work on modernizing the diff building, this change
adds type annotations for all the _extract*() functions used to
calculate add/delete/edit/move information, and updates documentation
accordingly. To keep code readable, these functions now require keyword
arguments, and flags have defaults.

As part of this, mypy and pyright determined there were places where
None values could theoretically be passed in as paths or revisions in
some places. This would have led to broken diffs before, but shouldn't
really happen. We now assert these values as a precaution.

It was also found that revisions are sometimes passed as a string, and
sometimes as an integer. The functions themselves can handle either, but
we now formalize this in the type annotations. We may wish to
standardize it at a later date.

Unit tests pass.