Fix conflation of Builder#name methods

* Builder#name() - the *environment type* the builder produces.
* Builder#name(String) - the *desired environment name* to build.

These are two different ideas. To reduce confusion and avoid name
clashes (especially in appose-python), this commit renames the
Builder#name() method to Builder#envType(). The Builder#name(String)
method is left as is (instead of renaming to Builder#envName(String)),
with the rationale that we want fluid builder syntax to be as succinct
as possible, and it can be assumed that the thing we are naming is the
environment to be built.

Author: ctrueden

src/main/java/org/apposed/appose/BuildException.java

@@ -78,7 +78,7 @@ public BuildException(
 	}
 
 	private static String makeMessage(Builder<?> builder, Throwable cause) {
-		String noun = builder == null ? "build" : builder.name() + " build";
+		String noun = builder == null ? "build" : builder.envType() + " build";
 		String verb = cause instanceof InterruptedException ? "interrupted" : "failed";
 		return noun + " " + verb;
 	}

src/main/java/org/apposed/appose/Builder.java

@@ -64,11 +64,11 @@
 public interface Builder<T extends Builder<T>> {
 
 	/**
-	 * Returns the name of this builder (e.g., "pixi", "mamba", "uv", "system").
+	 * Gets the environment type constructed by this builder (e.g., "pixi", "mamba", "uv").
 	 *
-	 * @return The builder name.
+	 * @return The builder's associated environment type.
 	 */
-	String name();
+	String envType();
 
 	/**
 	 * Builds the environment. This is the terminator method for any fluid building chain.

src/main/java/org/apposed/appose/BuilderFactory.java

@@ -49,16 +49,16 @@ public interface BuilderFactory {
 	 * Configuration should be provided via the fluent API
 	 * (e.g., {@link Builder#content}, {@link Builder#scheme}).
 	 *
-	 * @return A new builder instance
+	 * @return A new builder instance.
 	 */
 	Builder<?> createBuilder();
 
 	/**
-	 * Returns the name of this builder (e.g., "pixi", "mamba", "uv", "system").
+	 * Gets the environment type handled by this builder (e.g., "pixi", "mamba", "uv").
 	 *
-	 * @return The builder name
+	 * @return The builder's associated environment type.
 	 */
-	String name();
+	String envType();
 
 	/**
 	 * Checks if this builder supports the given scheme.

src/main/java/org/apposed/appose/Environment.java

@@ -58,21 +58,20 @@ default Map<String, String> envVars() {
 	}
 
 	/**
-	 * Returns the builder that created this environment.
+	 * Gets the builder that created this environment.
 	 * This enables re-configuration and rebuilding of the environment.
 	 *
 	 * @return The builder instance.
 	 */
 	Builder<?> builder();
 
 	/**
-	 * Returns the type of this environment (e.g., "pixi", "mamba", "uv", "system").
-	 * By default, delegates to the builder's name.
+	 * Gets the type of this environment (e.g., "pixi", "mamba", "uv").
 	 *
-	 * @return The environment type name.
+	 * @return The environment type.
 	 */
 	default String type() {
-		return builder().name();
+		return builder().envType();
 	}
 
 	/**

src/main/java/org/apposed/appose/builder/BaseBuilder.java

@@ -68,13 +68,13 @@ public abstract class BaseBuilder<T extends BaseBuilder<T>> implements Builder<T
 	protected String content;
 
 	/** Explicit scheme (e.g., "pixi.toml", "environment.yml"). */
-	protected String scheme;
+	protected Scheme scheme;
 
 	// -- Builder methods --
 
 	@Override
 	public void delete() throws IOException {
-		File dir = envDir();
+		File dir = resolveEnvDir();
 		if (dir.exists()) FilePaths.deleteRecursively(dir);
 	}
 
@@ -135,7 +135,7 @@ public T content(String content) {
 
 	@Override
 	public T scheme(String scheme) {
-		this.scheme = scheme;
+		this.scheme = Schemes.fromName(scheme);
 		return typedThis();
 	}
 
@@ -164,22 +164,22 @@ private T typedThis() {
 		return (T) this;
 	}
 
-	protected String envName() {
-		return envName != null ? envName :
-			// No explicit environment name set;
-			// extract name from the source content.
-			scheme().envName(content);
-	}
-
-	protected File envDir() {
+	/** Determines the environment directory path. */
+	protected File resolveEnvDir() {
 		if (envDir != null) return envDir;
+
 		// No explicit environment directory set; fall back to
 		// a subfolder of the Appose-managed environments directory.
-		return Paths.get(Environments.apposeEnvsDir(), envName()).toFile();
+		String dirName = envName != null ? envName :
+			// No explicit environment name set; extract name from the source content.
+			resolveScheme().envName(content);
+		return dirName == null ? null :
+			Paths.get(Environments.apposeEnvsDir(), dirName).toFile();
 	}
 
-	protected Scheme scheme() {
-		if (scheme != null) return Schemes.fromName(scheme);
+	/** Determines the scheme, detecting from content if needed. */
+	protected Scheme resolveScheme() {
+		if (scheme != null) return scheme;
 		if (content != null) return Schemes.fromContent(content);
 		throw new IllegalStateException("Cannot determine scheme: neither scheme nor content is set");
 	}

src/main/java/org/apposed/appose/builder/Builders.java

@@ -52,13 +52,14 @@ private Builders() {
 		(a, b) -> Double.compare(b.priority(), a.priority()));
 
 	/**
-	 * Finds a factory by name.
+	 * Finds the first factory capable of building a particular type of environment.
+	 * Factories are checked in priority order.
 	 *
-	 * @param name The builder name to search for.
-	 * @return The factory with matching name, or null if not found.
+	 * @param envType The environment type to target.
+	 * @return A factory supporting that environment type, or null if not found.
 	 */
-	public static @Nullable BuilderFactory findFactoryByName(String name) {
-		return Plugins.find(BUILDERS, factory -> factory.name().equalsIgnoreCase(name));
+	public static @Nullable BuilderFactory findFactoryByEnvType(String envType) {
+		return Plugins.find(BUILDERS, factory -> factory.envType().equalsIgnoreCase(envType));
 	}
 
 	/**
@@ -74,7 +75,7 @@ private Builders() {
 
 	/**
 	 * Finds the first factory that can wrap the given environment directory.
-	 * Factories are checked in priority order (highest priority first).
+	 * Factories are checked in priority order.
 	 *
 	 * @param envDir The directory to find a factory for.
 	 * @return The first factory that can wrap the directory, or null if none found.
@@ -117,14 +118,25 @@ public static boolean canWrap(File envDir) {
 	}
 
 	/**
-	 * Returns the environment type name for the given directory.
-	 * This is a convenience method equivalent to {@code findFactoryForWrapping(envDir).name()}.
+	 * Returns the given directory's environment type.
+	 * This is a convenience method equivalent to {@code findFactoryForWrapping(envDir).type()}.
+	 *
+	 * @param envDir The directory to check.
+	 * @return The environment type (e.g., "pixi", "mamba", "uv"), or null if not a known environment.
+	 */
+	public static @Nullable String envType(String envDir) {
+		return envType(new File(envDir));
+	}
+
+	/**
+	 * Returns the given directory's environment type.
+	 * This is a convenience method equivalent to {@code findFactoryForWrapping(envDir).type()}.
 	 *
 	 * @param envDir The directory to check.
-	 * @return The environment type name (e.g., "pixi", "mamba", "uv"), or null if not a known environment.
+	 * @return The environment type (e.g., "pixi", "mamba", "uv"), or null if not a known environment.
 	 */
 	public static @Nullable String envType(File envDir) {
 		BuilderFactory factory = findFactoryForWrapping(envDir);
-		return factory == null ? null : factory.name();
+		return factory == null ? null : factory.envType();
 	}
 }

src/main/java/org/apposed/appose/builder/DynamicBuilder.java

@@ -33,6 +33,7 @@
 import org.apposed.appose.Builder;
 import org.apposed.appose.BuilderFactory;
 import org.apposed.appose.Environment;
+import org.apposed.appose.Scheme;
 
 /**
  * Dynamic builder that auto-detects the appropriate specific builder
@@ -42,38 +43,38 @@
  */
 public final class DynamicBuilder extends BaseBuilder<DynamicBuilder> {
 
-	private String builderName;
+	private String envType;
 
 	// -- DynamicBuilder methods --
 
 	/**
 	 * Specifies the preferred builder to use.
 	 *
-	 * @param builderName The builder name (e.g., "pixi", "mamba", "uv")
+	 * @param envType The builder's environment type (e.g., "pixi", "mamba", "uv")
 	 * @return This builder instance, for fluent-style programming.
 	 */
-	public DynamicBuilder builder(String builderName) {
-		this.builderName = builderName;
+	public DynamicBuilder builder(String envType) {
+		this.envType = envType;
 		return this;
 	}
 
 	// -- Builder methods --
 
 	@Override
-	public String name() {
-		return "dynamic";
+	public String envType() {
+		return envType != null ? envType : "dynamic";
 	}
 
 	@Override
 	public Environment build() throws BuildException {
-		Builder<?> delegate = createBuilder(builderName, scheme);
+		Builder<?> delegate = createBuilder();
 		copyConfigToDelegate(delegate);
 		return delegate.build();
 	}
 
 	@Override
 	public Environment rebuild() throws BuildException {
-		Builder<?> delegate = createBuilder(builderName, scheme);
+		Builder<?> delegate = createBuilder();
 		copyConfigToDelegate(delegate);
 		return delegate.rebuild();
 	}
@@ -86,31 +87,31 @@ private void copyConfigToDelegate(Builder<?> delegate) {
 		if (envName != null) delegate.name(envName);
 		if (envDir != null) delegate.base(envDir);
 		if (content != null) delegate.content(content);
-		if (scheme != null) delegate.scheme(scheme);
+		if (scheme != null) delegate.scheme(scheme.name());
 		delegate.channels(channels);
 		progressSubscribers.forEach(delegate::subscribeProgress);
 		outputSubscribers.forEach(delegate::subscribeOutput);
 		errorSubscribers.forEach(delegate::subscribeError);
 	}
 
-	private Builder<?> createBuilder(String name, String scheme) {
+	private Builder<?> createBuilder() {
 		// Find the builder matching the specified name, if any.
-		if (name != null) {
-			BuilderFactory factory = Builders.findFactoryByName(name);
-			if (factory == null) throw new IllegalArgumentException("Unknown builder: " + name);
+		if (envType != null) {
+			BuilderFactory factory = Builders.findFactoryByEnvType(envType);
+			if (factory == null) throw new IllegalArgumentException("Unknown builder: " + envType);
 			return factory.createBuilder();
 		}
 
 		// Detect scheme from content if content is provided but scheme is not.
-		String effectiveScheme = scheme;
-		if (effectiveScheme == null && content != null) {
-			effectiveScheme = scheme().name();
+		Scheme actualScheme = scheme;
+		if (actualScheme == null && content != null) {
+			actualScheme = resolveScheme();
 		}
 
 		// Find the highest-priority builder that supports this scheme.
-		if (effectiveScheme != null) {
-			BuilderFactory factory = Builders.findFactoryByScheme(effectiveScheme);
-			if (factory == null) throw new IllegalArgumentException("No builder supports scheme: " + effectiveScheme);
+		if (actualScheme != null) {
+			BuilderFactory factory = Builders.findFactoryByScheme(actualScheme.name());
+			if (factory == null) throw new IllegalArgumentException("No builder supports scheme: " + actualScheme.name());
 			return factory.createBuilder();
 		}
 

src/main/java/org/apposed/appose/builder/MambaBuilder.java

@@ -53,7 +53,7 @@ public final class MambaBuilder extends BaseBuilder<MambaBuilder> {
 	// -- Builder methods --
 
 	@Override
-	public String name() {
+	public String envType() {
 		return "mamba";
 	}
 
@@ -70,7 +70,7 @@ public MambaBuilder channels(String... channels) {
 
 	@Override
 	public Environment build() throws BuildException {
-		File envDir = envDir();
+		File envDir = resolveEnvDir();
 
 		// Check for incompatible existing environments.
 		if (new File(envDir, ".pixi").isDirectory()) {
@@ -93,9 +93,9 @@ public Environment build() throws BuildException {
 		}
 
 		// Infer scheme if not explicitly set.
-		if (scheme == null) scheme = Schemes.fromContent(content).name();
+		if (scheme == null) scheme = Schemes.fromContent(content);
 
-		if (!"environment.yml".equals(scheme)) {
+		if (!"environment.yml".equals(scheme.name())) {
 			throw new IllegalArgumentException("MambaBuilder only supports environment.yml scheme, got: " + scheme);
 		}
 

src/main/java/org/apposed/appose/builder/MambaBuilderFactory.java

@@ -45,7 +45,7 @@ public Builder<?> createBuilder() {
 	}
 
 	@Override
-	public String name() {
+	public String envType() {
 		return "mamba";
 	}
 

src/main/java/org/apposed/appose/builder/PixiBuilder.java

@@ -81,13 +81,13 @@ public PixiBuilder pypi(String... packages) {
 	// -- Builder methods --
 
 	@Override
-	public String name() {
+	public String envType() {
 		return "pixi";
 	}
 
 	@Override
 	public Environment build() throws BuildException {
-		File envDir = envDir();
+		File envDir = resolveEnvDir();
 
 		// Check for incompatible existing environments.
 		if (new File(envDir, "conda-meta").exists() && !new File(envDir, ".pixi").exists()) {
@@ -131,21 +131,23 @@ public Environment build() throws BuildException {
 				}
 
 				// Infer scheme if not explicitly set.
-				if (scheme == null) scheme = Schemes.fromContent(content).name();
+				if (scheme == null) scheme = Schemes.fromContent(content);
 
 				if (!envDir.exists() && !envDir.mkdirs()) {
 					throw new BuildException(this, "Failed to create environment directory: " + envDir);
 				}
 
-				if ("pixi.toml".equals(scheme)) {
+				if ("pixi.toml".equals(scheme.name())) {
 					// Write pixi.toml to envDir.
 					File pixiTomlFile = new File(envDir, "pixi.toml");
 					Files.write(pixiTomlFile.toPath(), content.getBytes(StandardCharsets.UTF_8));
-				} else if ("pyproject.toml".equals(scheme)) {
+				}
+				else if ("pyproject.toml".equals(scheme.name())) {
 					// Write pyproject.toml to envDir (Pixi natively supports it).
 					File pyprojectTomlFile = new File(envDir, "pyproject.toml");
 					Files.write(pyprojectTomlFile.toPath(), content.getBytes(StandardCharsets.UTF_8));
-				} else if ("environment.yml".equals(scheme)) {
+				}
+				else if ("environment.yml".equals(scheme.name())) {
 					// Write environment.yml and import.
 					File environmentYamlFile = new File(envDir, "environment.yml");
 					Files.write(environmentYamlFile.toPath(), content.getBytes(StandardCharsets.UTF_8));
@@ -224,14 +226,14 @@ public Environment wrap(File envDir) throws BuildException {
 			if (pixiToml.exists() && pixiToml.isFile()) {
 				// Read the content so rebuild() will work even after directory is deleted.
 				content = new String(Files.readAllBytes(pixiToml.toPath()), StandardCharsets.UTF_8);
-				scheme = "pixi.toml";
+				scheme = Schemes.fromName("pixi.toml");
 			} else {
 				// Check for pyproject.toml.
 				File pyprojectToml = new File(envDir, "pyproject.toml");
 				if (pyprojectToml.exists() && pyprojectToml.isFile()) {
 					// Read the content so rebuild() will work even after directory is deleted.
 					content = new String(Files.readAllBytes(pyprojectToml.toPath()), StandardCharsets.UTF_8);
-					scheme = "pyproject.toml";
+					scheme = Schemes.fromName("pyproject.toml");
 				}
 			}
 		}