Complete implementation the deprecations API

[jathak]

This implements the full deprecations API for the JS API and the embedded compiler, and also adds silenceDeprecations/--silence-deprecation to the Dart API and CLI to complete those implementations.

See sass/sass#3826
See sass/sass-spec#1967
[skip sass-embedded]

[nex3]

It's a fair bet that most JS API users don't know or follow the Dart API, so it's probably better to frame this as adding three new features to the JS API rather than bringing two from the Dart API and adding one new

[jathak]

Done

[nex3]

Similarly, although to a lesser extent, the CLI users are a somewhat different set than the JS API users. Better to keep the CLI descriptions as self-contained as possible—it's less net effort for us to duplicate some prose than for a bunch of readers to read extra paragraphs.

[jathak]

Done

[nex3]

I'd mark this as **Potentially breaking bug fix:** on the off chance that someone was doing it without realizing that it wasn't failing.

[jathak]

Done

[nex3]

You can use if ... case to avoid this nullability assertion

[jathak]

Done

[nex3]

You could make this block a switch statement.

[jathak]

Done

[nex3]

A benefit of the old pattern of having a separate warnForDeprecation() method is that it's clear from the static types that every deprecation warning has to have a deprecationType attached to it. Unless there's a technical reason to fold that into warn(), I think I'd prefer to keep it the old way. (If they do need to be merged, we should have error handling for what happens if deprecation and deprecationType disagree.)

[jathak]

Now that there are other loggers that need to receive the deprecation type, using the same name for their method as the extension method meant that those other loggers could receive future deprecation warnings that hadn't been explicitly passed through by DeprecationProcessingLogger, so I wanted to separate those names.

I've now updated the method that LoggerWithDeprecationTypes implement to be internalWarn, which omits the boolean parameter and only has the Deprecation? one. In Dart Sass 2.0.0, we can eliminate internalWarn and LoggerWithDeprecationType by just changing Logger.warn's signature.

[nex3]

The distinction between DeprecationLogger and DeprecationHandlingLogger is now pretty confusing, since neither the names nor the documentations clearly say what makes them different from one another.

[jathak]

I've renamed this to DeprecationProcessingLogger and fleshed out the documentation to make it clearer that this one processes deprecation warnings (sometimes ignoring them or treating them as errors) based on the various flags.

The other one is now LoggerWithDeprecationType, which is clunky, but we can eliminate it in Dart Sass 2.0.0, so I'm not too worried about it.

[nex3]

Nit: remove trailing comma for consistency with other arglists.

[jathak]

Done

[nex3]

Consider:

Suggested change

	if (fatalDeprecations != null) {
	request.fatalDeprecation.addAll(fatalDeprecations);
	}
	fatalDeprecations.andThen(request.fatalDeprecation.addAll);

[jathak]

Done

[nex3]

There's a discrepancy with the spec here: the JS version API we've specified only supports <number>.<number>.<number> versions, but Version.parse() supports the full semver range, including build identifiers and prerelease versions. To match the spec, this should probably throw an error if anything beyond numbers are included.

[nex3]

Between this and --fatal-deprecation, nearly half the length of the --help output is taken up by deprecation descriptions. WDYT about just linking to the Sass site's CLI docs instead?

[jathak]

Yeah, I think that makes more sense. Is there a short version of https://sass-lang.com/documentation/cli/dart-sass so we can link to it with #fatal-deprecation, #silence-deprecation and #future-deprecation?