Cleanup: Flatten directory structure, update to new versions

This sample project had multiple subfolders, for Android Studio 2,
Android Studio 3, and Android Studio 4. Most of this was obsolete.  This
is now flattened into just one sample, which shows how to write a lint
check for a recent version of Studio/AGP.

It also updates the lint checks in various ways: using JUnit4 for the
unit test instead of JUnit3, providing a Vendor registration for the
issue registry, updating various versions of plugins and libraries to
the latest versions, etc etc.

Author: tnorbye

Diff for: .gitignore

@@ -32,3 +32,5 @@ Thumbs.db
 #.idea/workspace.xml - remove # and delete .idea if it better suit your needs.
 .gradle
 build/
+
+lint-results.sarif

Diff for: README.md

@@ -2,25 +2,82 @@ Custom Lint Rules
 =================
 
 The [Android `lint` tool](http://developer.android.com/tools/help/lint.html) is a static code
- analysis tool that checks your Android project source files for potential bugs and optimization
- improvements for correctness, security, performance, usability, accessibility, and
- internationalization. Lint comes with over 200 checks, however it can be extended with additional
- custom rules.
+analysis tool that checks your project source files for potential bugs and optimization
+improvements for correctness, security, performance, usability, accessibility, and
+internationalization. Lint comes with around 400 built-in checks, but it can be extended with 
+additional custom checks. This sample project shows how those sample checks can be built
+and packaged.
+
+Note that while Android Lint has the name "Android" in it, it is no longer an Android-specific
+static analysis tool; it's a general static analysis tool, and inside Google for example it is
+run to analyze server-side Java and Kotlin code.
 
 **NOTE: The lint API is not a final API; if you rely on this be prepared
  to adjust your code for the next tools release.**
 
 Introduction
 ------------
 
-The Android Lint API allows users to create custom lint rules. For example, if you are the author of
- a library project, and your library project has certain usage requirements, you can write
- additional lint rules to check that your library is used correctly, and then you can distribute
- those extra lint rules for users of the library. Similarly, you may have company-local rules you'd
- like to enforce.
+The Android Lint API allows users to create custom lint checks. For example, if you are the author of
+an Android library project, and your library project has certain usage requirements, you can write
+additional lint rules to check that your library is used correctly, and then you can distribute
+those extra lint rules for users of the library. Similarly, you may have company-local rules you'd
+like to enforce.
 
 This sample demonstrates how to create a custom lint checks and corresponding tests for those rules.
 
+
+# Sample Lint Checks
+
+This project shows how Android Studio as well as the Android Gradle plugin handles packaging of lint
+rules.
+
+## Lint Check Jar Library
+
+First, there's the lint check implementation itself. That's done in the
+"checks" project, which just applies the Gradle "java" or "kotlin" plugins, and
+that project produces a jar. Note that the dependencies for the lint
+check project (other than its testing dependencies) must all be "compileOnly":
+
+    dependencies {
+        compileOnly "com.android.tools.lint:lint-api:$lintVersion"
+        compileOnly "com.android.tools.lint:lint-checks:$lintVersion"
+		...
+
+## Lint Check AAR Library
+
+Next, there's a separate Android library project, called "library". This
+library doesn't have any code on its own (though it could). However,
+in its build.gradle, it specifies this:
+
+    dependencies {
+        lintPublish project(':checks')
+    }
+
+This tells the Gradle plugin to take the output from the "checks" project
+and package that as a "lint.jar" payload inside this library's AAR file.
+When that's done, any other projects that depends on this library will
+automatically be using the lint checks.
+
+## App Modules
+
+Note that you don't have to go through the extra "library indirection"
+if you have a lint check that you only want to apply to one or more
+app modules. You can simply include the `lintChecks` dependency as shown
+above there as well, and then lint will include these rules when analyzing
+the project.
+
+## Lint Version
+
+The lint version of the libraries (specified in this project as the
+`lintVersion` variable in build.gradle) should be the same version
+that is used by the Gradle plugin.
+
+If the Gradle plugin version is *X*.*Y*.*Z*, then the Lint library
+version is *X+23*.*Y*.*Z*.
+
+For example, for AGP 7.0.0-alpha08, the lint API versions are 30.0.0-alpha08.
+
 Getting Started
 ---------------
 
@@ -31,36 +88,68 @@ git clone https://github.com/googlesamples/android-custom-lint-rules.git
 cd android-custom-lint-rules
 ```
 
-##### Build the code
+##### Run The Sample
+
+Run the :app:lint target to have first the custom lint checks in checks/
+compiled, then wrapped into the library, and finally run lint on a
+sample app module which has violations of the check enforced by sample
+check in this project:
+```
+$ ./gradlew :app:lint
+
+> Task :app:lintDebug
+
+Scanning app: ...
+Wrote HTML report to file:///demo/android-custom-lint-rules/app/build/reports/lint-results-debug.html
+Wrote SARIF report to file:///demo/android-custom-lint-rules/app/build/reports/lint-results-debug.sarif
 
-For Android Studio 3.x and above, use the sample in `android-studio-3`.
-If you are targeting Android Studio 2.x and older, use the sample in `android-studio-2`.
+/demo/android-custom-lint-rules/app/src/main/java/com/android/example/Test.kt:8: Warning: This code mentions lint: Congratulations [ShortUniqueId]
+    val s = "lint"
+             ~~~~
+
+   Explanation for issues of type "ShortUniqueId":
+   This check highlights string literals in code which mentions the word lint.
+   Blah blah blah.
+
+   Another paragraph here.
+
+   Vendor: Android Open Source Project
+   Contact: https://github.com/googlesamples/android-custom-lint-rules
+   Feedback: https://github.com/googlesamples/android-custom-lint-rules/issues
+
+0 errors, 1 warnings
+
+BUILD SUCCESSFUL in 1s
+```
 
 ##### Lint Dependencies
 
-When building your own rules, you will likely want to know which dependencies you should bring into your own project. 
-The below descriptions of the dependencies included within this project serve to help you make that decision:
+When building your own rules, you will likely want to know which dependencies you should 
+bring into your own project. The below descriptions of the dependencies included within
+this project serve to help you make that decision:
 
 Source Dependencies
 
-- **com.android.tools.lint:lint-api**: The most important one; it contains things like `LintClient`, the `Detector` 
-base class, the `Issue` class, and everything else that Lint checks rely on in the Lint framework.
-- **com.android.tools.lint:lint-checks**: Contains the built-in checks that are developed internally. Also contains 
-utilities that are sometimes useful for other lint checks, such as the `VersionChecks` class (which figures out whether 
-a given UAST element is known to only be called at a given API level, either by surrounding `if >= SDK-version` checks or 
-`if < SDK-version` early returns in the method).
+- **com.android.tools.lint:lint-api**: The most important one; it contains things 
+  like `LintClient`, the `Detector` base class, the `Issue` class, and everything else 
+  that Lint checks rely on in the Lint framework.
+- **com.android.tools.lint:lint-checks**: Contains the built-in checks that are developed 
+  internally. Also contains utilities that are sometimes useful for other lint checks, 
+  such as the `VersionChecks` class (which figures out whether a given UAST element is 
+  known to only be called at a given API level, either by surrounding `if >= SDK-version`
+  checks or `if < SDK-version` early returns in the method).
 
 Test Dependencies
 
-- **com.android.tools.lint:lint-tests**: Contains useful utilities for writing unit tests for Lint checks, 
-including the `LintDetectorTest` base class.
-- **com.android.tools:testutils**: It's unlikely that you need to depend on this directly. The test infrastructure 
-depends on it indirectly though (the methods we use there were mostly for the older lint test infrastructure, 
-not the newer one).  
-- **com.android.tools.lint:lint**: Lint checks don't need to depend on this. It's a separate artifact used by tools 
-that want to integrate lint with the command line, such as the Gradle integration of lint. This is where things like 
-terminal output, HTML reporting, command line parsing etc is handled.
+- **com.android.tools.lint:lint-tests**: Contains useful utilities for writing unit tests 
+  for Lint checks, including the `LintDetectorTest` base class.
+- **com.android.tools.lint:lint**: Lint checks don't need to depend on this. It's a 
+  separate artifact used by tools that want to integrate lint with the command line, 
+  such as the Gradle integration of lint. This is where things like terminal output, HTML 
+  reporting, command line parsing etc is handled.
 
+The APIs in all but the lint-api artifact are more likely to change incompatibly than
+the lint-api artifact.
 
 Support
 -------