Improve detection error message with better user experience (#168)

Author: Malax

CHANGELOG.md

@@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - Framework detection now uses Gradle dependency resolution instead of build file parsing for more reliable detection across all DSL syntax, version catalogs, and dependency sources. ([#165](https://github.com/heroku/heroku-buildpack-gradle/pull/165))
 - Improved error messages with detailed troubleshooting steps, documentation links, and local reproduction guidance. ([#165](https://github.com/heroku/heroku-buildpack-gradle/pull/165))
+- Improve detection error message with better user experience and guidance for other build tools. ([#168](https://github.com/heroku/heroku-buildpack-gradle/pull/168))
 
 ### Removed
 

bin/detect

@@ -4,6 +4,10 @@ set -euo pipefail
 
 BUILD_DIR="${1}"
 
+BUILDPACK_DIR=$(cd "$(dirname "$(dirname "${BASH_SOURCE[0]}")")" && pwd)
+
+source "${BUILDPACK_DIR}/lib/output.sh"
+
 gradle_files=(
 	"gradlew"
 	"build.gradle"
@@ -23,5 +27,33 @@ for gradle_file in "${gradle_files[@]}"; do
 	fi
 done
 
-(>&2 echo "Could not find a gradlew file or other supported Gradle files!")
+output::error <<-EOF
+	Error: Your app is configured to use the Gradle buildpack,
+	but we couldn't find any supported Gradle project files.
+
+	The Gradle buildpack requires at least one of the following files
+	in the root directory of your source code:
+
+	Supported Gradle files: $(printf "%s, " "${gradle_files[@]}" | sed 's/, $//')
+
+	IMPORTANT: If your project uses a different build tool:
+	- For Maven projects, use the heroku/java buildpack instead
+	- For sbt projects, use the heroku/scala buildpack instead
+
+	Currently the root directory of your app contains:
+
+	$(ls -1A --indicator-style=slash "${BUILD_DIR}" 2>/dev/null || echo "Unable to list directory contents")
+
+	If your app already has Gradle files, check that they:
+
+	1. Are in the top level directory (not a subdirectory).
+	2. Have the correct spelling (the filenames are case-sensitive).
+	3. Aren't listed in '.gitignore' or '.slugignore'.
+	4. Have been added to the Git repository using 'git add --all'
+	   and then committed using 'git commit'.
+
+	For help with using Gradle on Heroku, see:
+	https://devcenter.heroku.com/articles/deploying-gradle-apps-on-heroku
+EOF
+
 exit 1

test/spec/detection_spec.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'spec_helper'
+
+RSpec.describe 'Gradle buildpack detection' do
+  it 'shows helpful error message when no Gradle project files are found' do
+    app = Hatchet::Runner.new('non-gradle-app', allow_failure: true)
+    app.deploy do
+      expect(clean_output(app.output)).to include(<<~OUTPUT)
+        remote:  !     Error: Your app is configured to use the Gradle buildpack,
+        remote:  !     but we couldn't find any supported Gradle project files.
+        remote:  !     
+        remote:  !     The Gradle buildpack requires at least one of the following files
+        remote:  !     in the root directory of your source code:
+        remote:  !     
+        remote:  !     Supported Gradle files: gradlew, build.gradle, build.gradle.kts, settings.gradle, settings.gradle.kts
+        remote:  !     
+        remote:  !     IMPORTANT: If your project uses a different build tool:
+        remote:  !     - For Maven projects, use the heroku/java buildpack instead
+        remote:  !     - For sbt projects, use the heroku/scala buildpack instead
+        remote:  !     
+        remote:  !     Currently the root directory of your app contains:
+        remote:  !     
+        remote:  !     README.md
+        remote:  !     
+        remote:  !     If your app already has Gradle files, check that they:
+        remote:  !     
+        remote:  !     1. Are in the top level directory (not a subdirectory).
+        remote:  !     2. Have the correct spelling (the filenames are case-sensitive).
+        remote:  !     3. Aren't listed in '.gitignore' or '.slugignore'.
+        remote:  !     4. Have been added to the Git repository using 'git add --all'
+        remote:  !        and then committed using 'git commit'.
+        remote:  !     
+        remote:  !     For help with using Gradle on Heroku, see:
+        remote:  !     https://devcenter.heroku.com/articles/deploying-gradle-apps-on-heroku
+      OUTPUT
+    end
+  end
+end

test/spec/fixtures/repos/non-gradle-app/README.md

@@ -0,0 +1,3 @@
+# Not a Gradle App
+
+This directory contains no Gradle project files to test detection failure.