Support ABI exclusions

[ZacSweers]

This is intended to resolve #48 by adding a new API to extensions for abi handling and exclusions configuration.

The API in practice looks like this:

abi {
  exclusions {
    // Convenience helpers
    ignoreSubPackage("internal")
    ignoreInternalPackages()
    ignoreGeneratedCode()

    // Raw, regexp-based APIs
    excludeAnnotations(".*\\.Generated")
    excludeClasses(".*\\.internal\\..*")
  }
}

I've left toe-holds in for directory based parsing (i.e. build/), but that will take more work as the current code looks only at class files and not where they originated from.

No tests yet as I want to put this up for review of the design before moving further.

[autonomousapps]

Thank you for the contribution! I have no fundamental problems with this, although I did leave a few small comments.

The biggest thing this PR needs is a functional test verifying the new behavior. I can provide pointers to get you started more quickly if you want to tackle that.

[autonomousapps]

Do you think we should change the pre-existing maptToSet() function to use a LinkedHashSet instead of adding a new method? Or, why do you prefer a linked hash set specifically here?

[ZacSweers]

I'd be down for that, as that would match kotlin's conventional behavior as well (toSet() guarantees preserved order)

[ZacSweers]

As for why LinkedHashSet - https://publicobject.com/2016/02/08/linkedhashmap-is-always-better-than-hashmap/

[ZacSweers]

a3c0509

[ZacSweers]

Addressed the inline comments, going to work on adding a test(s) now

[ZacSweers]

I wrote a pretty good unit test for the ABI checking. I can still write a functional test, but at this point it would be just to verify gradle plumbing rather than functionally correct exclusion behavior. Can take a crack if you think it's worth it, let me know

[autonomousapps]

very nice! Love that new unit test. TIL. I'll give this a try locally and hopefully we can merge soon.

[autonomousapps]

I want to talk a bit about the impact this has on generated advice.

Without setting any exclusions and running buildHealth on a personal project, I will see this in the abi-dump.txt file:

public abstract interface class com/seattleshelter/core/api/PetsService {
	public abstract fun getCatById (J)Lio/reactivex/Single;
	public abstract fun getCatsList ()Lio/reactivex/Single;
        ...etc...
}

and furthermore, the advice for this project suggests adding RxJava as an api dependency (as we would expect).

If I add the following:

abi {
  exclusions {
    excludeClasses("com\\.seattleshelter\\.core\\.api\\.PetsService")
  }
}

then abi dump does not contain that interface any longer, and the advice no longer suggests adding RxJava2 as an api dependency, since it's no longer part of the published api, as it was only used by the now-excluded class.

Is this what you expected? If not, could you be precise with what your goal is?

One interesting thing about this is that this plugin deals primarily in resolved dependencies. This new DSL operates at a different level (that of classes), which has an indirect impact on the dependency advice.

[ZacSweers]

Right, in this case that's expected. The idea is that you can limit exposed APIs for things that are either optional or public-only-becuse-tey-have-to-be

[autonomousapps]

LGTM. Will merge when CI passes.