Add better explanation for cache status

- Clarify default settings for cache-read-only
- Explain why cache was disabled or read-only
- Provide links to documentation in Job Summary

Fixes #255

sources/src/caching/cache-reporting.ts

@@ -1,5 +1,21 @@
 import * as cache from '@actions/cache'
 
+export const DEFAULT_READONLY_REASON = `Cache was read-only: by default the action will only write to the cache for Jobs running on the default ('main'/'master') branch. 
+    See [the docs](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#using-the-cache-read-only) for more details.
+`
+
+export const DEFAULT_DISABLED_REASON = `Cache was set to disabled via action confiugration. Gradle User Home was not restored from or saved to the cache.
+    See [the docs](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#disabling-caching) for more details.
+`
+
+export const DEFAULT_WRITEONLY_REASON = `Cache was set to write-only via action configuration. Gradle User Home was not restored from cache.
+    See [the docs](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#using-the-cache-write-only) for more details.
+`
+
+export const EXISTING_GRADLE_HOME = `Cache was disabled to avoid overwriting a pre-existing Gradle User Home. Gradle User Home was not restored from or saved to the cache.
+    See [the docs](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#overwriting-an-existing-gradle-user-home) for a more details.
+`
+
 /**
  * Collects information on what entries were saved and restored during the action.
  * This information is used to generate a summary of the cache usage.
@@ -9,7 +25,7 @@ export class CacheListener {
     cacheReadOnly = false
     cacheWriteOnly = false
     cacheDisabled = false
-    cacheDisabledReason = 'disabled'
+    cacheStatusReason: string | undefined
 
     get fullyRestored(): boolean {
         return this.cacheEntries.every(x => !x.wasRequestedButNotRestored())
@@ -17,12 +33,27 @@ export class CacheListener {
 
     get cacheStatus(): string {
         if (!cache.isFeatureAvailable()) return 'not available'
-        if (this.cacheDisabled) return this.cacheDisabledReason
+        if (this.cacheDisabled) return 'disabled'
         if (this.cacheWriteOnly) return 'write-only'
         if (this.cacheReadOnly) return 'read-only'
         return 'enabled'
     }
 
+    setReadOnly(reason: string = DEFAULT_READONLY_REASON): void {
+        this.cacheReadOnly = true
+        this.cacheStatusReason = reason
+    }
+
+    setDisabled(reason: string = DEFAULT_DISABLED_REASON): void {
+        this.cacheDisabled = true
+        this.cacheStatusReason = reason
+    }
+
+    setWriteOnly(reason: string = DEFAULT_WRITEONLY_REASON): void {
+        this.cacheWriteOnly = true
+        this.cacheStatusReason = reason
+    }
+
     entry(name: string): CacheEntryListener {
         for (const entry of this.cacheEntries) {
             if (entry.entryName === name) {
@@ -117,6 +148,9 @@ export function generateCachingReport(listener: CacheListener): string {
     return `
 <details>
 <summary><h4>Caching for Gradle actions was ${listener.cacheStatus} - expand for details</h4></summary>
+
+${listener.cacheStatusReason}
+
 ${renderEntryTable(entries)}
 
 <h5>Cache Entry Details</h5>

sources/src/caching/caches.ts

@@ -1,5 +1,5 @@
 import * as core from '@actions/core'
-import {CacheListener} from './cache-reporting'
+import {CacheListener, EXISTING_GRADLE_HOME} from './cache-reporting'
 import {GradleUserHomeCache} from './gradle-user-home-cache'
 import {CacheCleaner} from './cache-cleaner'
 import {DaemonController} from '../daemon-controller'
@@ -26,7 +26,7 @@ export async function restore(
         core.info('Cache is disabled: will not restore state from previous builds.')
         // Initialize the Gradle User Home even when caching is disabled.
         gradleStateCache.init()
-        cacheListener.cacheDisabled = true
+        cacheListener.setDisabled()
         return
     }
 
@@ -35,8 +35,7 @@ export async function restore(
             core.info('Gradle User Home already exists: will not restore from cache.')
             // Initialize pre-existing Gradle User Home.
             gradleStateCache.init()
-            cacheListener.cacheDisabled = true
-            cacheListener.cacheDisabledReason = 'disabled due to pre-existing Gradle User Home'
+            cacheListener.setDisabled(EXISTING_GRADLE_HOME)
             return
         }
         core.info('Gradle User Home already exists: will overwrite with cached contents.')
@@ -48,7 +47,7 @@ export async function restore(
 
     if (cacheConfig.isCacheWriteOnly()) {
         core.info('Cache is write-only: will not restore from cache.')
-        cacheListener.cacheWriteOnly = true
+        cacheListener.setWriteOnly()
         return
     }
 
@@ -82,7 +81,7 @@ export async function save(
 
     if (cacheConfig.isCacheReadOnly()) {
         core.info('Cache is read-only: will not save state for use in subsequent builds.')
-        cacheListener.cacheReadOnly = true
+        cacheListener.setReadOnly()
         return
     }