fix(maven): clarify requirements.txt vs packages handling and lock file checks

- Clarify behavior between <packages> and requirements.txt dependency modes
- Avoid possible NullPointerExceptions when requirements.txt is not used
- Validate lock file usage when no Python dependencies are configured
- Make dependency mode selection explicit and deterministic

Author: ih0r-d

graalpy-maven-plugin/src/main/java/org/graalvm/python/maven/plugin/InstallPackagesMojo.java

@@ -40,6 +40,7 @@
  */
 package org.graalvm.python.maven.plugin;
 
+import java.nio.file.Files;
 import org.apache.maven.plugin.MojoExecutionException;
 import org.apache.maven.plugins.annotations.LifecyclePhase;
 import org.apache.maven.plugins.annotations.Mojo;
@@ -100,6 +101,18 @@ private void manageVenv() throws MojoExecutionException {
 		MavenDelegateLog log = new MavenDelegateLog(getLog());
 		Path lockFile = getLockFile();
 		Path reqFile = resolveReqFile();
+
+		boolean emptyPackages = packages == null || packages.isEmpty();
+		boolean hasReqFile = reqFile != null && Files.exists(reqFile);
+		boolean hasLockFile = lockFile != null && Files.exists(lockFile);
+
+		if (emptyPackages && !hasReqFile) {
+			if (hasLockFile) {
+				throw new MojoExecutionException(
+						"Lock file is present, but no Python packages or requirements.txt are configured.");
+			}
+			return;
+		}
 		try {
 			VFSUtils.createVenv(venvDirectory, packages, lockFile, MISSING_LOCK_FILE_WARNING, createLauncher(),
 					getGraalPyVersion(project), log, reqFile);

graalpy-maven-plugin/src/main/java/org/graalvm/python/maven/plugin/LockPackagesMojo.java

@@ -65,7 +65,7 @@ public class LockPackagesMojo extends AbstractGraalPyMojo {
 			based on the packages defined in the plugin configuration and their dependencies.
 			""";
 	public static final String MISSING_DEPENDENCY_CONFIGURATION_ERROR = """
-			In order to run the lock-packages goal you must declare Python dependencies in the graalpy-maven-plugin configuration.
+			In order to run the lock-packages goal there have to be python packages declared in the graalpy-maven-plugin configuration.
 
 			You must configure Python dependencies in one of the following ways:
 
@@ -140,12 +140,11 @@ private void checkEmptyPackages() throws MojoExecutionException {
 		boolean requirementsExists = reqFilePath != null;
 		// Disallow lock-packages when no packages OR when requirementsFile is used
 		if (emptyPackages || requirementsExists) {
-			getLog().error("");
-			getLog().error("Missing Python dependency configuration.");
 			getLog().error("");
 			getLog().error(MISSING_DEPENDENCY_CONFIGURATION_ERROR);
 			getLog().error("");
-			throw new MojoExecutionException("Missing Python dependency configuration.");
+			throw new MojoExecutionException("In order to run the lock-packages goal there have to be python packages "
+					+ "declared in the graalpy-maven-plugin configuration");
 		}
 	}
 }

org.graalvm.python.embedding.tools/src/main/java/org/graalvm/python/embedding/tools/vfs/VFSUtils.java

@@ -543,38 +543,43 @@ public static void createVenv(Path venvDirectory, List<String> packages, Path lo
 		Objects.requireNonNull(graalPyVersion);
 		Objects.requireNonNull(log);
 
-		if (installPackagesFromReqFile(venvDirectory, launcher, graalPyVersion, log, reqFile)) {
+		if (installPackagesFromReqFile(venvDirectory, launcher, graalPyVersion, log, lockFilePath, reqFile)) {
 			return;
 		}
 
 		installPackages(venvDirectory, packages, lockFilePath, missingLockFileWarning, launcher, graalPyVersion, log);
 	}
 
 	static boolean installPackagesFromReqFile(Path venvDirectory, Launcher launcher, String graalPyVersion,
-			BuildToolLog log, Path reqFile) throws IOException {
-		if (reqFile != null) {
-			log.info("Using <requirements.txt> dependency mode.");
-			log.info("Installing Python dependencies from: " + reqFile);
+			BuildToolLog log, Path lockFilePath, Path reqFile) throws IOException {
+		if (reqFile == null) {
+			return false;
+		}
+		if (!Files.exists(reqFile)) {
+			return false;
+		}
+		log.info("Using <requirements.txt> dependency mode.");
+		log.info("Installing Python dependencies from: " + reqFile);
 
-			warnIfLockFileExists(venvDirectory, log);
+		warnIfLockFileExists(lockFilePath, log);
 
-			VenvContents vc = ensureVenv(venvDirectory, graalPyVersion, launcher, log);
+		VenvContents vc = ensureVenv(venvDirectory, graalPyVersion, launcher, log);
 
-			runPip(venvDirectory, "install", log, "--compile", "-r", reqFile.toString());
-			List<String> reqPackages = requirementsPackages(reqFile);
-			vc.write(reqPackages);
+		runPip(venvDirectory, "install", log, "--compile", "-r", reqFile.toString());
+		List<String> reqPackages = requirementsPackages(reqFile);
+		vc.write(reqPackages);
 
-			InstalledPackages installed = InstalledPackages.fromVenv(venvDirectory);
-			installed.freeze(log);
+		InstalledPackages installed = InstalledPackages.fromVenv(venvDirectory);
+		installed.freeze(log);
 
-			return true;
-		}
-		return false;
+		return true;
 	}
 
-	private static void warnIfLockFileExists(Path venvDirectory, BuildToolLog log) {
-		Path lockFile = venvDirectory.resolve("graalpy.lock");
-		if (Files.exists(lockFile)) {
+	private static void warnIfLockFileExists(Path lockFilePath, BuildToolLog log) {
+		if (lockFilePath == null) {
+			return;
+		}
+		if (Files.exists(lockFilePath)) {
 			log.warning("Lock file is ignored in <requirements.txt> mode.");
 		}
 	}
@@ -589,7 +594,7 @@ static void installPackages(Path venvDirectory, List<String> packages, Path lock
 
 		List<String> pluginPackages = trim(packages);
 
-		LockFile lockFile = null;
+		VFSUtils.LockFile lockFile = null;
 		if (lockFilePath != null && Files.exists(lockFilePath)) {
 			log.info("Lock-file detected: " + lockFilePath);
 			lockFile = LockFile.fromFile(lockFilePath, log);