implab/gradle-common Commit - r43:3285592a0ee9

Add compile-unit naming policy and late-configuration enforcement to VariantSourcesPlugin

cin -

r43:3285592a0ee9 default

parent child

Context file:

r43:3285592a0ee9

Collapse all files

variants/src/main/java/org/implab/gradle/variants/sources/internal/CompileUnitNamer.java created 644 +91 0

@@ -0,0 +1,91
	1	package org.implab.gradle.variants.sources.internal;
	2
	3	import java.text.MessageFormat;
	4	import java.util.Collection;
	5	import java.util.Comparator;
	6	import java.util.HashMap;
	7	import java.util.HashSet;
	8	import java.util.Map;
	9	import java.util.Optional;
	10	import java.util.Set;
	11	import java.util.function.Function;
	12	import java.util.stream.Collectors;
	13
	14	import org.gradle.api.InvalidUserDataException;
	15	import org.implab.gradle.common.core.lang.Strings;
	16	import org.implab.gradle.variants.sources.CompileUnit;
	17
	18	public interface CompileUnitNamer {
	19
	20	String resolveName(CompileUnit unit);
	21
	22	public static Builder builder() {
	23	return new Builder();
	24	}
	25
	26	static class Builder {
	27	private final Set<CompileUnit> units = new HashSet<>();
	28	private NameCollisionPolicy nameCollisionPolicy = NameCollisionPolicy.FAIL;
	29
	30	private Builder() {
	31	}
	32
	33	public Builder addUnits(Collection<CompileUnit> other) {
	34	units.addAll(other);
	35	return this;
	36	}
	37
	38	public Builder nameCollisionPolicy(NameCollisionPolicy policy) {
	39	nameCollisionPolicy = policy;
	40	return this;
	41	}
	42
	43	public CompileUnitNamer build() {
	44	Map<String, Integer> seen = new HashMap<>();
	45
	46	if (nameCollisionPolicy == NameCollisionPolicy.FAIL) {
	47	var collisions = units.stream()
	48	.collect(Collectors.groupingBy(this::projectName))
	49	.entrySet().stream()
	50	.filter(pair -> pair.getValue().size() > 1)
	51	.map(pair -> MessageFormat.format(
	52	"({0}: {1})",
	53	pair.getKey(),
	54	pair.getValue().stream()
	55	.map(Object::toString)
	56	.collect(Collectors.joining(","))))
	57	.collect(Collectors.joining(","));
	58	if (!collisions.isEmpty())
	59	throw new InvalidUserDataException(
	60	"The same source set names are produced by different compile units: " + collisions);
	61	}
	62
	63	var unitNames = units.stream()
	64	.sorted(Comparator
	65	.comparing((CompileUnit unit) -> unit.variant().getName())
	66	.thenComparing(unit -> unit.layer().getName()))
	67	.collect(Collectors.toUnmodifiableMap(Function.identity(), unit -> {
	68	var baseName = projectName(unit);
	69
	70	var c = seen.compute(baseName, (key, count) -> count == null ? 1 : count + 1);
	71	return c == 1 ? baseName : baseName + String.valueOf(c);
	72	}));
	73
	74	return new CompileUnitNamer() {
	75
	76	@Override
	77	public String resolveName(CompileUnit unit) {
	78	return Optional.ofNullable(unitNames.get(unit)).orElseThrow(
	79	() -> new IllegalArgumentException(MessageFormat.format(
	80	"Compile unit {0} doesn't have an associated name",
	81	unit)));
	82	}
	83
	84	};
	85	}
	86
	87	private String projectName(CompileUnit unit) {
	88	return unit.variant().getName() + Strings.capitalize(unit.layer().getName());
	89	}
	90	}
	91	}

variants/src/main/java/org/implab/gradle/variants/sources/internal/DefaultCompileUnitNamingPolicy.java created 644 +36 0

@@ -0,0 +1,36
	1	package org.implab.gradle.variants.sources.internal;
	2
	3	import org.implab.gradle.variants.sources.VariantSourcesExtension.NamingPolicySpec;
	4
	5	public class DefaultCompileUnitNamingPolicy implements NamingPolicySpec {
	6	private NameCollisionPolicy policy = NameCollisionPolicy.FAIL;
	7	private boolean policyApplied = false;
	8
	9	public NameCollisionPolicy policy() {
	10	finalizePolicy();
	11	return policy;
	12	}
	13
	14	public void finalizePolicy() {
	15	policyApplied = true;
	16	}
	17
	18	@Override
	19	public void failOnNameCollision() {
	20	assertApplyOnce();
	21	policy = NameCollisionPolicy.FAIL;
	22	}
	23
	24	@Override
	25	public void resolveNameCollision() {
	26	assertApplyOnce();
	27	policy = NameCollisionPolicy.RESOLVE;
	28	}
	29
	30	private void assertApplyOnce() {
	31	if (policyApplied)
	32	throw new IllegalStateException("Naming policy already applied");
	33	policyApplied = true;
	34
	35	}
	36	}

variants/src/main/java/org/implab/gradle/variants/sources/internal/DefaultLateConfigurationPolicySpec.java created 644 +42 0

@@ -0,0 +1,42
	1	package org.implab.gradle.variants.sources.internal;
	2
	3	import org.implab.gradle.variants.sources.VariantSourcesExtension.LateConfigurationPolicySpec;
	4
	5	public class DefaultLateConfigurationPolicySpec implements LateConfigurationPolicySpec {
	6
	7	private LateConfigurationMode policyMode = LateConfigurationMode.FAIL;
	8	private boolean policyApplied = false;
	9
	10	public LateConfigurationMode mode() {
	11	return policyMode;
	12	}
	13
	14	public void finalizePolicy() {
	15	policyApplied = true;
	16	}
	17
	18	@Override
	19	public void failOnLateConfiguration() {
	20	assertApplyOnce();
	21	policyMode = LateConfigurationMode.FAIL;
	22	}
	23
	24	@Override
	25	public void warnOnLateConfiguration() {
	26	assertApplyOnce();
	27	policyMode = LateConfigurationMode.WARN;
	28	}
	29
	30	@Override
	31	public void allowLateConfiguration() {
	32	assertApplyOnce();
	33	policyMode = LateConfigurationMode.APPLY;
	34	}
	35
	36	private void assertApplyOnce() {
	37	if (policyApplied)
	38	throw new IllegalStateException("Lazy configuration policy already applied");
	39	policyApplied = true;
	40	}
	41
	42	}

variants/src/main/java/org/implab/gradle/variants/sources/internal/DefaultVariantSourcesContext.java created 644 +92 0

@@ -0,0 +1,92
	1	package org.implab.gradle.variants.sources.internal;
	2
	3	import java.util.HashMap;
	4	import java.util.Map;
	5	import org.gradle.api.Action;
	6	import org.gradle.api.NamedDomainObjectProvider;
	7	import org.implab.gradle.common.sources.GenericSourceSet;
	8	import org.implab.gradle.variants.core.Layer;
	9	import org.implab.gradle.variants.core.Variant;
	10	import org.implab.gradle.variants.core.VariantsView;
	11	import org.implab.gradle.variants.sources.CompileUnit;
	12	import org.implab.gradle.variants.sources.CompileUnitsView;
	13	import org.implab.gradle.variants.sources.RoleProjectionsView;
	14	import org.implab.gradle.variants.sources.SourceSetMaterializer;
	15	import org.implab.gradle.variants.sources.VariantSourcesContext;
	16
	17	public class DefaultVariantSourcesContext implements VariantSourcesContext {
	18	private final VariantsView variantsView;
	19	private final CompileUnitsView compileUnitsView;
	20	private final RoleProjectionsView roleProjectionsView;
	21	private final SourceSetMaterializer sourceSetMaterializer;
	22	private final SourceSetRegistry sourceSetRegistry;
	23	private final CompileUnitNamer compileUnitNamer;
	24	private final SourceSetConfigurationRegistry sourceSetConfigurationRegistry;
	25
	26	public DefaultVariantSourcesContext(
	27	VariantsView variantsView,
	28	CompileUnitsView compileUnitsView,
	29	RoleProjectionsView roleProjectionsView,
	30	CompileUnitNamer compileUnitNamer,
	31	SourceSetRegistry sourceSetRegistry,
	32	SourceSetConfigurationRegistry sourceSetConfigurationRegistry) {
	33	this.variantsView = variantsView;
	34	this.compileUnitNamer = compileUnitNamer;
	35	this.compileUnitsView = compileUnitsView;
	36	this.roleProjectionsView = roleProjectionsView;
	37	this.sourceSetRegistry = sourceSetRegistry;
	38	this.sourceSetConfigurationRegistry = sourceSetConfigurationRegistry;
	39
	40	sourceSetMaterializer = new LocalSourceSetMaterializer();
	41	}
	42
	43	@Override
	44	public VariantsView getVariants() {
	45	return variantsView;
	46	}
	47
	48	@Override
	49	public CompileUnitsView getCompileUnits() {
	50	return compileUnitsView;
	51	}
	52
	53	@Override
	54	public RoleProjectionsView getRoleProjections() {
	55	return roleProjectionsView;
	56	}
	57
	58	@Override
	59	public SourceSetMaterializer getSourceSets() {
	60	return sourceSetMaterializer;
	61	}
	62
	63	@Override
	64	public void configureLayer(Layer layer, Action<? super GenericSourceSet> action) {
	65	sourceSetConfigurationRegistry.addLayerAction(layer, action);
	66	}
	67
	68	@Override
	69	public void configureVariant(Variant variant, Action<? super GenericSourceSet> action) {
	70	sourceSetConfigurationRegistry.addVariantAction(variant, action);
	71	}
	72
	73	@Override
	74	public void configureUnit(CompileUnit unit, Action<? super GenericSourceSet> action) {
	75	sourceSetConfigurationRegistry.addCompileUnitAction(unit, action);
	76	}
	77
	78	class LocalSourceSetMaterializer implements SourceSetMaterializer {
	79	private final Map<CompileUnit, NamedDomainObjectProvider<GenericSourceSet>> registeredSources = new HashMap<>();
	80
	81	@Override
	82	public NamedDomainObjectProvider<GenericSourceSet> getSourceSet(CompileUnit unit) {
	83	return registeredSources.computeIfAbsent(unit, k -> {
	84	var sourcesName = compileUnitNamer.resolveName(unit);
	85	sourceSetRegistry.whenMaterialized(sourcesName,
	86	sourceSet -> sourceSetConfigurationRegistry.applyConfiguration(unit, sourceSet));
	87	return sourceSetRegistry.sourceSets().register(sourcesName);
	88	});
	89	}
	90
	91	}
	92	}

variants/src/main/java/org/implab/gradle/variants/sources/internal/LateConfigurationMode.java created 644 +7 0

@@ -0,0 +1,7
	1	package org.implab.gradle.variants.sources.internal;
	2
	3	public enum LateConfigurationMode {
	4	FAIL,
	5	WARN,
	6	APPLY
	7	}

variants/src/main/java/org/implab/gradle/variants/sources/internal/NameCollisionPolicy.java created 644 +6 0

@@ -0,0 +1,6
	1	package org.implab.gradle.variants.sources.internal;
	2
	3	public enum NameCollisionPolicy {
	4	FAIL,
	5	RESOLVE
	6	}

variants/src/main/java/org/implab/gradle/variants/sources/internal/SourceSetRegistry.java created 644 +46 0

@@ -0,0 +1,46
	1	package org.implab.gradle.variants.sources.internal;
	2
	3	import java.util.HashMap;
	4	import java.util.Map;
	5	import java.util.function.Consumer;
	6
	7	import org.gradle.api.NamedDomainObjectContainer;
	8	import org.gradle.api.model.ObjectFactory;
	9	import org.implab.gradle.common.core.lang.Deferred;
	10	import org.implab.gradle.common.sources.GenericSourceSet;
	11
	12	public class SourceSetRegistry {
	13	private final Map<String, Deferred<GenericSourceSet>> materialized = new HashMap<>();
	14	private final NamedDomainObjectContainer<GenericSourceSet> sourceSets;
	15	private final ObjectFactory objectFactory;
	16
	17	public SourceSetRegistry(ObjectFactory objectFactory) {
	18	this.objectFactory = objectFactory;
	19	this.sourceSets = objectFactory.domainObjectContainer(GenericSourceSet.class, this::createSourceSet);
	20	}
	21
	22	void forEachMaterialized(Consumer<? super GenericSourceSet> consumer) {
	23	materialized.values().stream()
	24	.filter(Deferred::resolved)
	25	.map(Deferred::value)
	26	.forEach(consumer);
	27	}
	28
	29	public NamedDomainObjectContainer<GenericSourceSet> sourceSets() {
	30	return sourceSets;
	31	}
	32
	33	public void whenMaterialized(String name, Consumer<? super GenericSourceSet> consumer) {
	34	materialized(name).whenResolved(consumer);
	35	}
	36
	37	private GenericSourceSet createSourceSet(String name) {
	38	var sourceSet = objectFactory.newInstance(GenericSourceSet.class, name);
	39	materialized(name).resolve(sourceSet);
	40	return sourceSet;
	41	}
	42
	43	private Deferred<GenericSourceSet> materialized(String name) {
	44	return materialized.computeIfAbsent(name, k -> new Deferred<>());
	45	}
	46	}

.hgignore +3 0

             syntax: glob
             .gradle/
+            .codex/
             common/build/
             common/bin/
+            variants/build/
+            variants/bin/

AGENTS.md +10 0

             # AGENTS.md
             ## Проектные договоренности
             ### Публичное API библиотек
             - Предпочтителен `non-null` подход.
             - Там, где значение живет в Gradle Provider API, возвращается `Provider<T>` (не `null`).
             - Там, где lookup синхронный, возвращается `Optional<T>` (не `null`).
             - `find*` рассматривается как синоним legacy `get*` (поиск без `fail-fast`).
             - `require*` это `find*` + `fail-fast` с понятной ошибкой в месте вызова.
             - Для нового API предпочтительны формы `find/require`; новые `get*` по возможности не добавлять.
+            ### Документация
+            - документирование кода должно быть на английском языке
+            - к публичному API
+              - описание должно отражать назначение, где используется и какое влияние оказывает на остальные части программы
+              - давать небольшое описание концепции, а также краткие примеры
+            - к приватному API достаточно давать краткую справку о назначении и использовании
+            - реализацию алгоритмов в коде сопровождать комментариями с пояснениями, тривиальные операции пояснять не требуется.
+            - документация должна формироваться согласно требованиям по форматированию типа javadoc, jsdoc и т.п., в зависимости от используемых в проекте языках и инструментах.
             ## Identity-first modeling
             Prefer an **identity-first** split between:
             - **identity objects** used for discovery and selection
             - **stateful/materialized objects** obtained through separate API calls
             ### Rules
             - Objects intended for replayable observation (`all(...)`, similar collection APIs) should be **identity objects**.
             - Identity objects must be:
               - cheap to create
               - effectively immutable
               - limited to identity and cheap selection metadata
             - Heavy, computed, provider-based, or runtime-bound state must be resolved separately.
             - Aggregate content should be accessed through dedicated lookup/materialization APIs.
             - Eager observation of identity is acceptable.
             - Eager observation of computed state is not.
             ### Do not
             - Do not store heavy computed state inside identity objects.
             - Do not store runtime references to foreign domains inside identity objects.
             - Do not use custom events when replayable identity registries plus on-demand lookup are sufficient.
             ### Rule of thumb
             **Identity objects contain selection metadata.
             Aggregate content is obtained separately, on demand.**

common/src/main/java/org/implab/gradle/common/core/lang/Deferred.java +12 -2

             package org.implab.gradle.common.core.lang;
             import java.util.LinkedList;
             import java.util.List;
             import java.util.function.Consumer;
             public final class Deferred<T> {
-                private final List<Consumer<T>> listeners = new LinkedList<>();
+                private final List<Consumer<? super T>> listeners = new LinkedList<>();
                 private T value;
                 private boolean resolved = false;
+                public boolean resolved() {
+                    return resolved;
+                }
+                public T value() {
+                    if (!resolved)
+                        throw new IllegalStateException();
+                    return value;
+                }
                 public void resolve(T value) {
                     if (resolved) {
                         throw new IllegalStateException("Already resolved");
                     }
                     this.value = value;
                     this.resolved = true;
                     listeners.forEach(listener -> listener.accept(value));
                     listeners.clear();
                 }
-                public void whenResolved(Consumer<T> listener) {
+                public void whenResolved(Consumer<? super T> listener) {
                     if (resolved) {
                         listener.accept(value);
                     } else {
                         listeners.add(listener);
                     }
                 }
             }

variant_sources_precedence.md +62 -3

             # `variantSources`: selectors and precedence
             `variantSources` configures source-set materialization over the compile-unit space.
             A compile unit is defined as:
             - `(variant, layer)`
             This means:
             - `variant` defines compilation semantics
             - `layer` defines compilation partitioning
             The `variantSources` DSL does not introduce a separate source model.
             Instead, it provides configuration selectors over the existing compile-unit space.
             ## Selectors
             Three selectors are available:
             - `variant(...)`
             - `layer(...)`
             - `unit(...)`
             They all target the same set of compile units, but at different levels of specificity.
             ### `variant(...)`
             `variant(...)` applies configuration to all compile units that belong to the given variant.
             Example:
             ```groovy
             variantSources {
                 variant("browser") {
                     declareOutputs("js", "dts")
                 }
             }
             ```
             This affects all compile units of `browser`, for example:
             - `(browser, main)`
             - `(browser, rjs)`
             - `(browser, test)`
             Use this selector for variant-wide conventions.
             ---
             ### `layer(...)`
             `layer(...)` applies configuration to all compile units that use the given layer.
             Example:
             ```groovy
             variantSources {
                 layer("main") {
                     set("ts") {
                         srcDir("src/main/ts")
                     }
                 }
             }
             ```
             This affects all compile units with layer `main`, for example:
             - `(browser, main)`
             - `(nodejs, main)`
             - `(electron, main)`
             Use this selector for cross-variant layer conventions.
             ---
             ### `unit(...)`
             `unit(...)` applies configuration to one exact compile unit.
             Example:
             ```groovy
             variantSources {
                 unit("browser", "main") {
                     set("resources") {
                         srcDir("src/browserMain/resources")
                     }
                 }
             }
             ```
             This affects only:
             - `(browser, main)`
             Use this selector for the most specific adjustments.
             ---
             ## Precedence
             For each compile unit, source-set configuration is applied in the following order:
             ```text
             variant < layer < unit
             ```
             This means:
 . `variant(...)` actions are applied first
 . `layer(...)` actions are applied next
 . `unit(...)` actions are applied last
             Each next level is allowed to refine or override the previous one.
             ### Within the same level
             Within the same selector level, actions are applied in registration order.
             For example, if two plugins both configure `layer("main")`, their actions are applied in the same order in which they were registered.
+            ### Scope of this guarantee
+            This precedence describes the normal materialization order used by the source-set
+            materializer.
+            It is stable for source sets that are configured before they are materialized.
+            If a selector rule is added after a target source set has already been
+            materialized, the behavior depends on the selected late-configuration policy.
+            - in `fail` mode, such late configuration is rejected
+            - in `warn` and `allow` modes, the late action is applied as an imperative
+              follow-up step
+            - in `warn` and `allow` modes, selector precedence is not reconstructed
+              retroactively for already materialized targets
+            ---
+            ## Late Configuration Policy
+            `variantSources` exposes a policy switch for selector rules that target already
+            materialized source sets:
+            ```groovy
+            variantSources {
+                lateConfigurationPolicy {
+                    failOnLateConfiguration()
+                }
+            }
+            ```
+            Available modes:
+            - `failOnLateConfiguration()` rejects such rules
+            - `warnOnLateConfiguration()` allows them and emits a warning
+            - `allowLateConfiguration()` allows them silently
+            Policy rules:
+            - the policy must be chosen before the first selector rule is added
+            - selector rules here mean `variant(...)`, `layer(...)`, and `unit(...)`
+            - once chosen, the policy cannot be changed later
+            - the policy is single-valued; it is not intended to be switched during further
+              configuration
+            Operationally:
+            - `fail` preserves the strict precedence contract by rejecting late mutation of
+              already materialized targets
+            - `warn` and `allow` keep compatibility with imperative late mutation
+            - in `warn` and `allow`, already materialized targets observe the late action in
+              actual registration order, not in reconstructed `variant < layer < unit`
+              order
             ---
             ## Example
             ```groovy
             variantSources {
                 variant("browser") {
                     declareOutputs("js", "dts")
                 }
                 layer("main") {
                     set("ts") {
                         srcDir("src/main/ts")
                     }
                 }
                 unit("browser", "main") {
                     set("resources") {
                         srcDir("src/browserMain/resources")
                     }
                 }
             }
             ```
             For compile unit `(browser, main)` the effective configuration is built in this order:
 . `variant("browser")`
 . `layer("main")`
 . `unit("browser", "main")`
             For compile unit `(browser, rjs)` the effective configuration is built in this order:
 . `variant("browser")`
 . `layer("rjs")` if present
 . `unit("browser", "rjs")` if present
             For compile unit `(nodejs, main)` the effective configuration is built in this order:
 . `variant("nodejs")` if present
 . `layer("main")`
 . `unit("nodejs", "main")` if present
             ---
             ## Model boundary
             These selectors do not define compile units.
             Compile units are derived from finalized `variants`.
             `variantSources` only configures how source sets are materialized for those units.
             This means:
             - `variants` is the source of truth for compile-unit existence
             - `variantSources` is the source of truth for compile-unit source-set configuration
             ---
             ## Operational semantics
             The `variantSources` API is exposed through a finalized context.
             Conceptually, configuration is registered against finalized model objects, while DSL sugar may still use names for convenience.
-            Internally, selector-based configuration is accumulated and later applied by the source-set materializer when a `GenericSourceSet` is created for a compile unit.
+            Internally, selector-based configuration is accumulated and later applied by the
+            source-set materializer when a `GenericSourceSet` is created for a compile unit.
             This guarantees that:
-            - selector precedence is stable
+            - selector precedence is stable before materialization
             - registration order is preserved
-            - configuration does not depend on the materialization moment
+            - configuration of already materialized targets is governed by the selected
+              late-configuration policy
             - adapters do not need to depend on raw Gradle lifecycle timing
             ---
             ## Summary
             - compile unit space is `(variant, layer)`
             - `variant(...)`, `layer(...)`, and `unit(...)` are selectors over that space
             - precedence is:
             ```text
             variant < layer < unit
             ```
             - registration order is preserved within the same selector level
+            - already materialized targets are handled by `lateConfigurationPolicy(...)`
+            - the late-configuration policy must be selected before the first selector rule
+              and cannot be changed later
             - `variants` defines what exists
             - `variantSources` defines how those compile units are materialized as source sets

variants/src/main/java/org/implab/gradle/variants/VariantSourcesPlugin.java +112 -58

@@ -1,102 +1,156
1	package org.implab.gradle.variants;	1	package org.implab.gradle.variants;
2		2
		3	import java.util.Objects;
		4	import java.util.function.Predicate;
		5
3	import org.eclipse.jdt.annotation.NonNullByDefault;	6	import org.eclipse.jdt.annotation.NonNullByDefault;
4	import org.gradle.api.Action;	7	import org.gradle.api.Action;
		8	import org.gradle.api.InvalidUserDataException;
		9	import org.gradle.api.Named;
5	import org.gradle.api.Plugin;	10	import org.gradle.api.Plugin;
6	import org.gradle.api.Project;	11	import org.gradle.api.Project;
7	import org.implab.gradle.common.core.lang.Deferred;	12	import org.implab.gradle.common.core.lang.Deferred;
		13	import org.implab.gradle.common.core.lang.Strings;
8	import org.implab.gradle.common.sources.GenericSourceSet;	14	import org.implab.gradle.common.sources.GenericSourceSet;
9	import org.implab.gradle.common.sources.SourcesPlugin;
10	import org.implab.gradle.variants.core.Layer;	15	import org.implab.gradle.variants.core.Layer;
11	import org.implab.gradle.variants.core.Variant;	16	import org.implab.gradle.variants.core.Variant;
12	import org.implab.gradle.variants.core.VariantsExtension;	17	import org.implab.gradle.variants.core.VariantsExtension;
13	import org.implab.gradle.variants.core.VariantsView;	18	import org.implab.gradle.variants.core.VariantsView;
14	import org.implab.gradle.variants.sources.CompileUnit;	19	import org.implab.gradle.variants.sources.CompileUnit;
15	import org.implab.gradle.variants.sources.CompileUnitsView;	20	import org.implab.gradle.variants.sources.CompileUnitsView;
16	import org.implab.gradle.variants.sources.RoleProjectionsView;	21	import org.implab.gradle.variants.sources.RoleProjectionsView;
17	import org.implab.gradle.variants.sources.SourceSetMaterializer;
18	import org.implab.gradle.variants.sources.VariantSourcesContext;	22	import org.implab.gradle.variants.sources.VariantSourcesContext;
		23	import org.implab.gradle.variants.sources.VariantSourcesExtension;
		24	import org.implab.gradle.variants.sources.internal.CompileUnitNamer;
		25	import org.implab.gradle.variants.sources.internal.DefaultCompileUnitNamingPolicy;
		26	import org.implab.gradle.variants.sources.internal.DefaultLateConfigurationPolicySpec;
		27	import org.implab.gradle.variants.sources.internal.DefaultVariantSourcesContext;
		28	import org.implab.gradle.variants.sources.internal.SourceSetConfigurationRegistry;
		29	import org.implab.gradle.variants.sources.internal.SourceSetRegistry;
19		30
20	@NonNullByDefault	31	@NonNullByDefault
21	public abstract class VariantSourcesPlugin implements Plugin<Project> {	32	public abstract class VariantSourcesPlugin implements Plugin<Project> {
		33	public static final String VARIANT_SOURCES_EXTENSION = "variantSources";
		34
22	@Override	35	@Override
23	public void apply(Project target) {	36	public void apply(Project target) {
		37	var extensions = target.getExtensions();
		38
24	// Apply the main VariantsPlugin to ensure the core variant model is available.	39	// Apply the main VariantsPlugin to ensure the core variant model is available.
25	target.getPlugins().apply(VariantsPlugin.class);	40	target.getPlugins().apply(VariantsPlugin.class);
26	target.getPlugins().apply(SourcesPlugin.class);
27	// Access the VariantsExtension to configure variant sources.	41	// Access the VariantsExtension to configure variant sources.
28	var variantsExtension = ~~targ~~et.~~getE~~xtensions().getByType(VariantsExtension.class);	42	var variantsExtension = extensions.getByType(VariantsExtension.class);
29	var objectFactory = target.getObjects();	43	var objectFactory = target.getObjects();
30		44
31	var sources = SourcesPlugin.getSourcesExtension(target);
32
33	var deferred = new Deferred<VariantSourcesContext>();	45	var deferred = new Deferred<VariantSourcesContext>();
34		46
		47	var lateConfigurationPolicy = new DefaultLateConfigurationPolicySpec();
		48	var namingPolicy = new DefaultCompileUnitNamingPolicy();
		49
35	variantsExtension.whenFinalized(variants -> {	50	variantsExtension.whenFinalized(variants -> {
		51	// create variant views
36	var compileUnits = CompileUnitsView.of(variants);	52	var compileUnits = CompileUnitsView.of(variants);
37	var roleProjections = RoleProjectionsView.of(variants);	53	var roleProjections = RoleProjectionsView.of(variants);
38		54
39	var context = new Context(variants, compileUnits, roleProjections);	55	// create registries
		56	var sourceSetRegistry = new SourceSetRegistry(objectFactory);
		57	var sourceSetConfiguration = new SourceSetConfigurationRegistry(lateConfigurationPolicy::mode);
		58
		59	// build compile unit namer
		60	var compileUnitNamer = CompileUnitNamer.builder()
		61	.addUnits(compileUnits.getUnits())
		62	.nameCollisionPolicy(namingPolicy.policy())
		63	.build();
40		64
		65	// create the context
		66	var context = new DefaultVariantSourcesContext(
		67	variants,
		68	compileUnits,
		69	roleProjections,
		70	compileUnitNamer,
		71	sourceSetRegistry,
		72	sourceSetConfiguration
		73	);
41	deferred.resolve(context);	74	deferred.resolve(context);
42	});	75	});
43		76
44	// var	77	var variantSourcesExtension = new VariantSourcesExtension() {
		78	@Override
		79	public void whenFinalized(Action<? super VariantSourcesContext> action) {
		80	deferred.whenResolved(action::execute);
		81	}
		82
		83	@Override
		84	public void lateConfigurationPolicy(Action<? super LateConfigurationPolicySpec> action) {
		85	action.execute(lateConfigurationPolicy);
		86	}
		87
		88	@Override
		89	public void namingPolicy(Action<? super NamingPolicySpec> action) {
		90	action.execute(namingPolicy);
		91	}
		92
		93	@Override
		94	public void variant(String variantName, Action<? super GenericSourceSet> action) {
		95	Strings.argumentNotNullOrBlank(variantName, "variantName");
		96	Objects.requireNonNull(action, "action can't be null");
		97
		98	lateConfigurationPolicy.finalizePolicy();
		99
		100	whenFinalized(ctx -> ctx.configureVariant(resolveVariant(ctx.getVariants(), variantName), action));
		101	}
		102
		103	@Override
		104	public void layer(String layerName, Action<? super GenericSourceSet> action) {
		105	// protect external DSL
		106	Strings.argumentNotNullOrBlank(layerName, "layerName");
		107	Objects.requireNonNull(action, "action can't be null");
		108
		109	lateConfigurationPolicy.finalizePolicy();
		110
		111	whenFinalized(ctx -> ctx.configureLayer(resolveLayer(ctx.getVariants(), layerName), action));
		112	}
		113
		114	@Override
		115	public void unit(String variantName, String layerName, Action<? super GenericSourceSet> action) {
		116	Strings.argumentNotNullOrBlank(layerName, "layerName");
		117	Strings.argumentNotNullOrBlank(variantName, "variantName");
		118	Objects.requireNonNull(action, "action can't be null");
		119
		120	lateConfigurationPolicy.finalizePolicy();
		121
		122	whenFinalized(ctx -> ctx.configureUnit(resolveCompileUnit(ctx, variantName, layerName), action));
		123	}
		124	};
		125
		126	extensions.add(VariantSourcesExtension.class, VARIANT_SOURCES_EXTENSION, variantSourcesExtension);
45		127
46	}	128	}
47		129
48	private static class Context implements VariantSourcesContext {	130	private static Layer resolveLayer(VariantsView variants, String name) {
49		131	return variants.getLayers().stream()
50	private final VariantsView variantsView;	132	.filter(named(name))
51	private final CompileUnitsView compileUnitsView;	133	.findAny()
52	private final RoleProjectionsView roleProjectionsView;	134	.orElseThrow(() -> new IllegalArgumentException("Layer '" + name + "' isn't declared"));
53		135	}
54	Context(VariantsView variantsView, CompileUnitsView compileUnitsView, RoleProjectionsView roleProjectionsView) {
55	this.variantsView = variantsView;
56	this.compileUnitsView = compileUnitsView;
57	this.roleProjectionsView = roleProjectionsView;
58	}
59
60	@Override
61	public VariantsView getVariants() {
62	return variantsView;
63	}
64
65	@Override
66	public CompileUnitsView getCompileUnits() {
67	return compileUnitsView;
68	}
69		136
70	@Override	137	private static Variant resolveVariant(VariantsView variants, String name) {
71	public RoleProjectionsView getRoleProjections() {	138	return variants.getVariants().stream()
72	return roleProjectionsView;	139	.filter(named(name))
73	}	140	.findAny()
74		141	.orElseThrow(() -> new IllegalArgumentException("Variant '" + name + "' is't declared"));
75	@Override
76	public SourceSetMaterializer getSourceSets() {
77	// TODO Auto-generated method stub
78	throw new UnsupportedOperationException("Unimplemented method 'getSourceSets'");
79	}
80
81	@Override
82	public void configureLayer(Layer layer, Action<? super GenericSourceSet> action) {
83	// TODO Auto-generated method stub
84	throw new UnsupportedOperationException("Unimplemented method 'configureLayer'");
85	}
86
87	@Override
88	public void configureVariant(Variant variant, Action<? super GenericSourceSet> action) {
89	// TODO Auto-generated method stub
90	throw new UnsupportedOperationException("Unimplemented method 'configureVariant'");
91	}
92
93	@Override
94	public void configureUnit(CompileUnit unit, Action<? super GenericSourceSet> action) {
95	// TODO Auto-generated method stub
96	throw new UnsupportedOperationException("Unimplemented method 'configureUnit'");
97	}
98
99	}	142	}
100		143
		144	private static CompileUnit resolveCompileUnit(VariantSourcesContext ctx, String variantName, String layerName) {
		145	return ctx.getCompileUnits().findUnit(
		146	resolveVariant(ctx.getVariants(), variantName),
		147	resolveLayer(ctx.getVariants(), layerName))
		148	.orElseThrow(() -> new InvalidUserDataException(
		149	"The CompileUnit isn't declared for variant '" + variantName + "', layer '" + layerName + "'"));
		150	}
		151
		152	private static Predicate<Named> named(String name) {
		153	return named -> named.getName().equals(name);
		154	}
101		155
102	}	156	}

variants/src/main/java/org/implab/gradle/variants/core/VariantsView.java +69 0

             package org.implab.gradle.variants.core;
             import java.util.ArrayList;
             import java.util.LinkedHashMap;
             import java.util.List;
             import java.util.Map;
             import java.util.Objects;
             import java.util.Optional;
             import java.util.Set;
             import java.util.stream.Collectors;
             import org.eclipse.jdt.annotation.NonNullByDefault;
             import org.gradle.api.InvalidUserDataException;
+            /**
+             * A resolved view of declared variants, roles, layers, and their bindings.
+             *
+             * Built from {@link VariantDefinition} instances, this class materializes validated
+             * {@link VariantRoleLayer} entries and provides lookup APIs grouped by variant,
+             * role, or layer.
+             *
+             * Typical usage is to collect identities and variant definitions through
+             * {@link Builder}, then use the resulting view to traverse resolved bindings.
+             */
             @NonNullByDefault
             public class VariantsView {
                 private final Set<Layer> layers;
                 private final Set<Role> roles;
                 private final Set<Variant> variants;
                 private final Set<VariantRoleLayer> entries;
                 private final Map<Variant, Set<VariantRoleLayer>> entriesByVariant;
                 private final Map<Role, Set<VariantRoleLayer>> entriesByRole;
                 private final Map<Layer, Set<VariantRoleLayer>> entriesByLayer;
                 private VariantsView(Set<Layer> layers, Set<Role> roles, Set<Variant> variants, Set<VariantRoleLayer> entries) {
                     this.layers = layers;
                     this.roles = roles;
                     this.variants = variants;
                     this.entries = entries;
                     this.entriesByVariant = entries.stream()
                             .collect(Collectors.groupingBy(VariantRoleLayer::variant, Collectors.toSet()));
                     this.entriesByRole = entries.stream()
                             .collect(Collectors.groupingBy(VariantRoleLayer::role, Collectors.toSet()));
                     this.entriesByLayer = entries.stream()
                             .collect(Collectors.groupingBy(VariantRoleLayer::layer, Collectors.toSet()));
                 }
+                /**
+                 * Returns all declared layers included in this view.
+                 */
                 public Set<Layer> getLayers() {
                     return layers;
                 }
+                /**
+                 * Returns all declared roles included in this view.
+                 */
                 public Set<Role> getRoles() {
                     return roles;
                 }
+                /**
+                 * Returns all declared variants included in this view.
+                 */
                 public Set<Variant> getVariants() {
                     return variants;
                 }
+                /**
+                 * Returns all resolved variant-role-layer bindings.
+                 */
                 public Set<VariantRoleLayer> getEntries() {
                     return entries;
                 }
+                /**
+                 * Returns all bindings associated with the specified variant.
+                 *
+                 * An empty set is returned when the variant has no bindings in this view.
+                 */
                 public Set<VariantRoleLayer> getEntriesForVariant(Variant variant) {
                     return entriesByVariant.getOrDefault(variant, Set.of());
                 }
+                /**
+                 * Returns all bindings associated with the specified layer.
+                 *
+                 * An empty set is returned when the layer has no bindings in this view.
+                 */
                 public Set<VariantRoleLayer> getEntriesForLayer(Layer layer) {
                     return entriesByLayer.getOrDefault(layer, Set.of());
                 }
+                /**
+                 * Returns all bindings associated with the specified role.
+                 *
+                 * An empty set is returned when the role has no bindings in this view.
+                 */
                 public Set<VariantRoleLayer> getEntriesForRole(Role role) {
                     return entriesByRole.getOrDefault(role, Set.of());
                 }
+                /**
+                 * A resolved binding between a variant, a role, and a layer.
+                 *
+                 * @param variant the resolved variant
+                 * @param role the resolved role
+                 * @param layer the resolved layer
+                 */
                 public record VariantRoleLayer(Variant variant, Role role, Layer layer) {
                 }
+                /**
+                 * Creates a builder for assembling a {@link VariantsView}.
+                 */
                 public static Builder builder() {
                     return new Builder();
                 }
+                /**
+                 * Collects declared identities and variant definitions, then resolves them
+                 * into a {@link VariantsView}.
+                 */
                 public static class Builder {
                     private final Map<String, Layer> layers = new LinkedHashMap<>();
                     private final Map<String, Role> roles = new LinkedHashMap<>();
                     private final Map<String, Variant> variants = new LinkedHashMap<>();
                     private final List<VariantDefinition> definitions = new ArrayList<>();
                     private Builder() {
                     }
+                    /**
+                     * Adds or replaces a role by its name.
+                     */
                     public Builder addRole(Role role) {
                         Objects.requireNonNull(role, "role can't be null");
                         roles.put(role.getName(), role);
                         return this;
                     }
+                    /**
+                     * Adds or replaces a layer by its name.
+                     */
                     public Builder addLayer(Layer layer) {
                         Objects.requireNonNull(layer, "layer can't be null");
                         layers.put(layer.getName(), layer);
                         return this;
                     }
+                    /**
+                     * Adds or replaces a variant by its name.
+                     */
                     public Builder addVariant(Variant variant) {
                         Objects.requireNonNull(variant, "variant can't be null");
                         variants.put(variant.getName(), variant);
                         return this;
                     }
+                    /**
+                     * Adds a variant definition to be resolved during {@link #build()}.
+                     */
                     public Builder addDefinition(VariantDefinition definition) {
                         Objects.requireNonNull(definition, "definition can't be null");
                         definitions.add(definition);
                         return this;
                     }
+                    /**
+                     * Resolves collected identities and definitions into an immutable view.
+                     *
+                     * Missing variant, role, or layer declarations referenced by definitions
+                     * cause {@link InvalidUserDataException}.
+                     */
                     public VariantsView build() {
                         var entries = definitions.stream()
                                 .flatMap(def -> def.getRoleBindings().get().stream()
                                         .map(layerRole -> createVariantRoleLayer(
                                                 def.getName(), // variantName
                                                 layerRole.roleName(),
                                                 layerRole.layerName())))
                                 .collect(Collectors.toSet());
                         return new VariantsView(
                                 Set.copyOf(layers.values()),
                                 Set.copyOf(roles.values()),
                                 Set.copyOf(variants.values()),
                                 entries);
                     }
                     private VariantRoleLayer createVariantRoleLayer(String variantName, String roleName, String layerName) {
                         return new VariantRoleLayer(
                                 resolveVariant(variantName,
                                         "Variant '" + variantName + "' isn't declared"),
                                 resolveRole(roleName,
                                         "Role '" + roleName + "' isn't declared, referenced in '" + variantName + "' variant"),
                                 resolveLayer(layerName,
                                         "Layer '" + layerName + "' isn't declared, referenced in '" + variantName
                                                 + "' variant with '" + roleName + "' role"));
                     }
                     private Layer resolveLayer(String layerName, String errorMessage) {
                         return Optional.ofNullable(layers.get(layerName))
                                 .orElseThrow(() -> new InvalidUserDataException(errorMessage));
                     }
                     private Variant resolveVariant(String variantName, String errorMessage) {
                         return Optional.ofNullable(variants.get(variantName))
                                 .orElseThrow(() -> new InvalidUserDataException(errorMessage));
                     }
                     private Role resolveRole(String roleName, String errorMessage) {
                         return Optional.ofNullable(roles.get(roleName))
                                 .orElseThrow(() -> new InvalidUserDataException(errorMessage));
                     }
                 }
             }

variants/src/main/java/org/implab/gradle/variants/sources/VariantSourcesContext.java +22 -2

             package org.implab.gradle.variants.sources;
             import org.gradle.api.Action;
             import org.implab.gradle.common.sources.GenericSourceSet;
             import org.implab.gradle.variants.core.Layer;
             import org.implab.gradle.variants.core.Variant;
             import org.implab.gradle.variants.core.VariantsView;
             /**
              * Registry of symbolic source set names produced by sources projection.
              *
              * Identity in this registry is the GenericSourceSet name.
              */
             public interface VariantSourcesContext {
                /**
                  * Finalized core model.
                  */
                 VariantsView getVariants();
                 /**
                  * Derived compile-side view.
                  */
                 CompileUnitsView getCompileUnits();
                 /**
                  * Derived role-side view.
                  */
                 RoleProjectionsView getRoleProjections();
                 /**
                  * Lazy source set provider service.
                  */
                 SourceSetMaterializer getSourceSets();
                 /**
                  * Configures all GenericSourceSets produced from the given layer.
                  *
                  * The action is applied:
                  * - to already materialized source sets of this layer
                  * - to all future source sets of this layer
                  *
-                 * Actions are applied in registration order.
+                 * <p>For future source sets, selector precedence and registration order are
+                 * preserved by the materializer.
+                 *
+                 * <p>For already materialized source sets, behavior is governed by
+                 * {@link VariantSourcesExtension#lateConfigurationPolicy(org.gradle.api.Action)}.
+                 * In warn/allow modes the action is applied as a late imperative step and does
+                 * not retroactively restore selector precedence.
                  */
                 void configureLayer(Layer layer, Action<? super GenericSourceSet> action);
+                /**
+                 * Configures all GenericSourceSets produced from the given variant.
+                 *
+                 * <p>Late application semantics for already materialized source sets are
+                 * governed by
+                 * {@link VariantSourcesExtension#lateConfigurationPolicy(org.gradle.api.Action)}.
+                 */
                 void configureVariant(Variant variant, Action<? super GenericSourceSet> action);
+                /**
+                 * Configures the GenericSourceSet produced from the given compile unit.
+                 *
+                 * <p>Late application semantics for already materialized source sets are
+                 * governed by
+                 * {@link VariantSourcesExtension#lateConfigurationPolicy(org.gradle.api.Action)}.
+                 */
                 void configureUnit(CompileUnit unit, Action<? super GenericSourceSet> action);
-            }
  No newline at end of file

variants/src/main/java/org/implab/gradle/variants/sources/VariantSourcesExtension.java +62 -50

@@ -1,93 +1,105
1	package org.implab.gradle.variants.sources;	1	package org.implab.gradle.variants.sources;
2		2
3	import java.util.Objects;
4	import java.util.function.Predicate;
5
6	import org.eclipse.jdt.annotation.NonNullByDefault;	3	import org.eclipse.jdt.annotation.NonNullByDefault;
7	import org.gradle.api.Action;	4	import org.gradle.api.Action;
8	import org.gradle.api.InvalidUserDataException;
9	import org.gradle.api.Named;
10	import org.implab.gradle.common.core.lang.Closures;	5	import org.implab.gradle.common.core.lang.Closures;
11	import org.implab.gradle.common.core.lang.Strings;
12	import org.implab.gradle.common.sources.GenericSourceSet;	6	import org.implab.gradle.common.sources.GenericSourceSet;
13	import org.implab.gradle.variants.core.Layer;
14	import org.implab.gradle.variants.core.Variant;
15	import org.implab.gradle.variants.core.VariantsView;
16
17	import groovy.lang.Closure;	7	import groovy.lang.Closure;
18		8
19	@NonNullByDefault	9	@NonNullByDefault
20	public interface VariantSourcesExtension {	10	public interface VariantSourcesExtension {
21		11
22	default void layer(String layerName, Action<? super GenericSourceSet> action) {	12	/**
23	// protect external DSL	13	* Selects how selector rules behave when they target an already materialized
24	Strings.argumentNotNullOrBlank(layerName, "layerName");	14	* {@link GenericSourceSet}.
25	Objects.requireNonNull(action, "action can't be null");	15	*
		16	* <p>This policy is single-valued:
		17	* <ul>
		18	* <li>it must be selected before the first selector rule is registered via
		19	* {@link #variant(String, Action)}, {@link #layer(String, Action)} or
		20	* {@link #unit(String, String, Action)};</li>
		21	* <li>once selected, it cannot be changed later;</li>
		22	* <li>the policy controls both diagnostics and late-application semantics.</li>
		23	* </ul>
		24	*/
		25	void lateConfigurationPolicy(Action<? super LateConfigurationPolicySpec> action);
26		26
27	whenFinalized(ctx -> ctx.configureLayer(resolveLayer(ctx.getVariants(), layerName), action));	27	default void lateConfigurationPolicy(Closure<?> closure) {
		28	lateConfigurationPolicy(Closures.action(closure));
28	}	29	}
29		30
		31	void namingPolicy(Action<? super NamingPolicySpec> action);
		32
		33	default void namingPolicy(Closure<?> closure) {
		34	namingPolicy(Closures.action(closure));
		35	}
		36
		37	void layer(String layerName, Action<? super GenericSourceSet> action);
		38
30	default void layer(String layerName, Closure<?> closure) {	39	default void layer(String layerName, Closure<?> closure) {
31	layer(layerName, Closures.action(closure));	40	layer(layerName, Closures.action(closure));
32	}	41	}
33		42
34	~~default~~ void variant(String variantName, Action<? super GenericSourceSet> action) {	43	void variant(String variantName, Action<? super GenericSourceSet> action);
35	Strings.argumentNotNullOrBlank(variantName, "variantName");
36	Objects.requireNonNull(action, "action can't be null");
37
38	whenFinalized(ctx -> ctx.configureVariant(resolveVariant(ctx.getVariants(), variantName), action));
39	}
40		44
41	default void variant(String variantName, Closure<?> closure) {	45	default void variant(String variantName, Closure<?> closure) {
42	variant(variantName, Closures.action(closure));	46	variant(variantName, Closures.action(closure));
43	}	47	}
44		48
45	~~default~~ void unit(String variantName, String layerName, Action<? super GenericSourceSet> action) {	49	void unit(String variantName, String layerName, Action<? super GenericSourceSet> action);
46	Strings.argumentNotNullOrBlank(layerName, "layerName");
47	Strings.argumentNotNullOrBlank(variantName, "variantName");
48	Objects.requireNonNull(action, "action can't be null");
49
50	whenFinalized(ctx -> ctx.configureUnit(resolveCompileUnit(ctx, variantName, layerName), action));
51	}
52		50
53	/**	51	/**
54	* Invoked when finalized variants-derived source context becomes available.	52	* Invoked when finalized variants-derived source context becomes available.
55	*	53	*
56	* Replayable:	54	* Replayable:
57	* <ul>	55	* <ul>
58	* <li>if called before variants finalization, action is queued	56	* <li>if called before variants finalization, action is queued
59	* <li>if called after variants finalization, action is invoked immediately	57	* <li>if called after variants finalization, action is invoked immediately
60	* </ul>	58	* </ul>
61	*/	59	*/
62	void whenFinalized(Action<? super VariantSourcesContext> action);	60	void whenFinalized(Action<? super VariantSourcesContext> action);
63		61
64	default void whenFinalized(Closure<?> closure) {	62	default void whenFinalized(Closure<?> closure) {
65	whenFinalized(Closures.action(closure));	63	whenFinalized(Closures.action(closure));
66	}	64	}
67		65
68	private static Layer resolveLayer(VariantsView variants, String name) {	66
69	return variants.getLayers().stream()	67	/**
70	.filter(named(name))	68	* Imperative selector for the late-configuration mode.
71	.findAny()	69	*
72	.orElseThrow(() -> new IllegalArgumentException("Layer '" + name + "' isn't declared"));	70	* <p>Exactly one mode is expected to be chosen for the extension lifecycle.
		71	*/
		72	interface LateConfigurationPolicySpec {
		73	/**
		74	* Rejects selector registration if it targets any already materialized
		75	* source set.
		76	*/
		77	void failOnLateConfiguration();
		78
		79	/**
		80	* Allows late selector registration, but emits a warning when it targets an
		81	* already materialized source set.
		82	*
		83	* <p>For such targets, selector precedence is not re-established
		84	* retroactively. The action is applied as a late imperative step, after the
		85	* state already produced at the materialization moment.
		86	*/
		87	void warnOnLateConfiguration();
		88
		89	/**
		90	* Allows late selector registration without a warning when it targets an
		91	* already materialized source set.
		92	*
		93	* <p>For such targets, selector precedence is not re-established
		94	* retroactively. The action is applied as a late imperative step, after the
		95	* state already produced at the materialization moment.
		96	*/
		97	void allowLateConfiguration();
73	}	98	}
74		99
75	private static Variant resolveVariant(VariantsView variants, String name) {	100	interface NamingPolicySpec {
76	return variants.getVariants().stream()	101	void failOnNameCollision();
77	.filter(named(name))
78	.findAny()
79	.orElseThrow(() -> new IllegalArgumentException("Variant '" + name + "' is't declared"));
80	}
81		102
82	private static CompileUnit resolveCompileUnit(VariantSourcesContext ctx, String variantName, String layerName) {	103	void resolveNameCollision();
83	return ctx.getCompileUnits().findUnit(
84	resolveVariant(ctx.getVariants(), variantName),
85	resolveLayer(ctx.getVariants(), layerName))
86	.orElseThrow(() -> new InvalidUserDataException(
87	"The CompileUnit isn't declared for variant '" + variantName + "', layer '" + layerName + "'"));
88	}	104	}
89		105	}
90	private static Predicate<Named> named(String name) {
91	return named -> named.getName().equals(name);
92	}
93	} No newline at end of file

variants/src/main/java/org/implab/gradle/variants/sources/internal/SourceSetConfigurationRegistry.java ~~variants/src/main/java/org/implab/gradle/variants/sources/internal/LayerConfigurationRegistry.java~~ renamed +103 -4

@@ -1,15 +1,114
1	package org.implab.gradle.variants.sources.internal;	1	package org.implab.gradle.variants.sources.internal;
2		2
		3	import java.text.MessageFormat;
		4	import java.util.LinkedHashMap;
		5	import java.util.LinkedList;
		6	import java.util.List;
		7	import java.util.Map;
		8	import java.util.function.Consumer;
		9	import java.util.function.Supplier;
		10	import java.util.stream.Collectors;
		11
		12	import org.eclipse.jdt.annotation.NonNullByDefault;
3	import org.gradle.api.Action;	13	import org.gradle.api.Action;
		14	import org.gradle.api.Named;
		15	import org.gradle.api.logging.Logger;
		16	import org.gradle.api.logging.Logging;
4	import org.implab.gradle.common.sources.GenericSourceSet;	17	import org.implab.gradle.common.sources.GenericSourceSet;
5	import org.implab.gradle.variants.core.Layer;	18	import org.implab.gradle.variants.core.Layer;
		19	import org.implab.gradle.variants.core.Variant;
6	import org.implab.gradle.variants.sources.CompileUnit;	20	import org.implab.gradle.variants.sources.CompileUnit;
7		21
8	public interface LayerConfigurationRegistry {	22	@NonNullByDefault
		23	public class SourceSetConfigurationRegistry {
		24	private static final Logger logger = Logging.getLogger(SourceSetConfigurationRegistry.class);
		25
		26	private final Map<Layer, ReplayableQueue<GenericSourceSet>> sourcesByLayer = new LinkedHashMap<>();
		27	private final Map<Variant, ReplayableQueue<GenericSourceSet>> sourcesByVariant = new LinkedHashMap<>();
		28	private final Map<CompileUnit, ReplayableQueue<GenericSourceSet>> sourcesByUnit = new LinkedHashMap<>();
		29
		30	private final Supplier<LateConfigurationMode> lateConfigurationMode;
		31
		32	public SourceSetConfigurationRegistry(Supplier<LateConfigurationMode> lateConfigurationMode) {
		33	this.lateConfigurationMode = lateConfigurationMode;
		34	}
9		35
10	void addLayerAction(Layer layer, Action<? super GenericSourceSet> action);	36	public void addLayerAction(Layer layer, Action<? super GenericSourceSet> action) {
		37	addToActions(
		38	sourcesByLayer.computeIfAbsent(layer, key -> new ReplayableQueue<>()),
		39	action,
		40	MessageFormat.format(
		41	"Source sets for [layer={0}] layer already materialized",
		42	layer.getName()));
		43	}
		44
		45	public void addVariantAction(Variant variant, Action<? super GenericSourceSet> action) {
		46	addToActions(
		47	sourcesByVariant.computeIfAbsent(variant, key -> new ReplayableQueue<>()),
		48	action,
		49	MessageFormat.format(
		50	"Source sets for [variant={0}] variant already materialized",
		51	variant.getName()));
		52
		53	}
		54
		55	public void addCompileUnitAction(CompileUnit unit, Action<? super GenericSourceSet> action) {
		56	addToActions(
		57	sourcesByUnit.computeIfAbsent(unit, key -> new ReplayableQueue<>()),
		58	action,
		59	MessageFormat.format(
		60	"Source set for [variant={0}, layer={1}] already materialed",
		61	unit.variant().getName(),
		62	unit.layer().getName()));
		63	}
11		64
12	void applyLayer(Layer layer, GenericSourceSet sourceSet);	65	private void addToActions(
		66	ReplayableQueue<GenericSourceSet> actions,
		67	Action<? super GenericSourceSet> action,
		68	String assertMessage) {
		69	assertLazyConfiguration(actions.values(), assertMessage);
		70	actions.forEach(action::execute);
		71	}
		72
		73	void assertLazyConfiguration(List<GenericSourceSet> sets, String message) {
		74	if (sets.size() == 0)
		75	return;
		76
		77	var names = sets.stream().map(Named::getName).collect(Collectors.joining(", "));
		78
		79	switch (lateConfigurationMode.get()) {
		80	case FAIL:
		81	throw new IllegalStateException(message + " [" + names + "]");
		82	case WARN:
		83	logger.warn(message + "\n\t" + names);
		84	break;
		85	default:
		86	break;
		87	}
		88	}
13		89
14	void apply~~Unit~~(CompileUnit unit, GenericSourceSet sourceSet);	90	public void applyConfiguration(CompileUnit unit, GenericSourceSet sourceSet) {
		91	sourcesByVariant.computeIfAbsent(unit.variant(), key -> new ReplayableQueue<>()).add(sourceSet);
		92	sourcesByLayer.computeIfAbsent(unit.layer(), key -> new ReplayableQueue<>()).add(sourceSet);
		93	sourcesByUnit.computeIfAbsent(unit, key -> new ReplayableQueue<>()).add(sourceSet);
		94	}
		95
		96	class ReplayableQueue<T> {
		97	private final List<Consumer<? super T>> consumers = new LinkedList<>();
		98	private final List<T> values = new LinkedList<>();
		99
		100	public void add(T value) {
		101	consumers.forEach(consumer -> consumer.accept(value));
		102	values.add(value);
		103	}
		104
		105	List<T> values() {
		106	return List.copyOf(values);
		107	}
		108
		109	public void forEach(Consumer<? super T> consumer) {
		110	values.forEach(consumer);
		111	consumers.add(consumer);
		112	}
		113	}
15	}	114	}

variants_variant_sources.md +59 -2

             # Variants and Variant Sources
             ## Overview
             This document describes a two-layer model for build variants:
             - `variants` defines the **core domain model**
             - `variantSources` defines **source materialization semantics** for that model
             The main goal is to keep the core model small, explicit, and stable, while allowing source-related behavior to remain flexible and adapter-friendly.
             The model is intentionally split into:
 . a **closed, finalized domain model**
 . an **open, runtime-oriented source materialization model**
             This separation is important because compilation, source aggregation, publication, and adapter-specific behavior do not belong to the same abstraction layer.
             ---
             ## Core idea
             The `variants` model is based on three independent domains:
             - `Layer`
             - `Role`
             - `Variant`
             A finalized `VariantsView` contains the normalized relation:
             - `(variant, role, layer)`
             This relation is the source of truth.
             Everything else is derived from it.
             ---
             ## `variants`: the core domain model
             ### Purpose
             `variants` describes:
             - what layers exist
             - what roles exist
             - what variants exist
             - which `(variant, role, layer)` combinations are valid
             It does **not** describe:
             - source directories
             - source roots
             - source set materialization
             - compilation tasks
             - publication mechanics
             - source set inheritance
             - layer merge behavior for a concrete toolchain
             Those concerns are intentionally outside the core model.
             ---
             ## Core DSL example
             ```groovy
             variants {
                 layers {
                     main()
                     test()
                     generated()
                     rjs()
                     cjs()
                 }
                 roles {
                     production()
                     test()
                     tool()
                 }
                 variant("browser") {
                     role("production") {
                         layers("main", "generated", "rjs")
                     }
                     role("test") {
                         layers("main", "test", "generated", "rjs")
                     }
                 }
                 variant("nodejs") {
                     role("production") {
                         layers("main", "generated", "cjs")
                     }
                     role("test") {
                         layers("main", "test", "generated", "cjs")
                     }
                     role("tool") {
                         layers("main", "generated", "cjs")
                     }
                 }
             }
             ```
             ### Interpretation
             This example means:
             * `browser` production uses `main`, `generated`, `rjs`
             * `browser` test uses `main`, `test`, `generated`, `rjs`
             * `nodejs` production uses `main`, `generated`, `cjs`
             * `nodejs` test uses `main`, `test`, `generated`, `cjs`
             * `nodejs` tool uses `main`, `generated`, `cjs`
             The model is purely declarative.
             ---
             ## Identity and references
             `Layer`, `Role`, and `Variant` are identity objects.
             They exist as declared domain values.
             References between model elements are symbolic:
             * layers are referenced by layer name
             * roles are referenced by role name
             * variants are referenced by variant name
             This is intentional.
             The core model is declarative, not navigation-oriented.
             It is acceptable for aggregates to hold symbolic references to foreign domain values, as long as identity is clearly defined and validated later.
             ---
             ## Finalization
             The `variants` model is finalized once.
             Finalization is an internal lifecycle transition. It is typically triggered privately, for example from `afterEvaluate`, but that mechanism is not part of the public API contract.
             The public contract is:
             * `variants.whenFinalized(...)`
             This callback is **replayable**:
             * if called before finalization, the action is queued
             * if called after finalization, the action is invoked immediately
             The callback receives a finalized, read-only view of the model.
             Example:
             ```java
             variants.whenFinalized(view -> {
                 // use finalized VariantsView here
             });
             ```
             ---
             ## `VariantsView`
             `VariantsView` is the finalized representation of the core model.
             It contains:
             * all declared `Layer`
             * all declared `Role`
             * all declared `Variant`
             * all normalized entries `(variant, role, layer)`
             Conceptually:
             ```java
             interface VariantsView {
                 Set<Layer> getLayers();
                 Set<Role> getRoles();
                 Set<Variant> getVariants();
                 Set<VariantRoleLayer> getEntries();
             }
             ```
             Where:
             ```java
             record VariantRoleLayer(Variant variant, Role role, Layer layer) {}
             ```
             This view is:
             * immutable
             * normalized
             * validated
             * independent from DSL internals
             ---
             ## Derived views
             Two important views can be derived from `VariantsView`:
             * `CompileUnitsView`
             * `RoleProjectionsView`
             These views are not part of the raw core model itself, but they are naturally derived from it.
             ---
             ## `CompileUnitsView`
             ### Purpose
             A compile unit is defined as:
             * `(variant, layer)`
             This is based on the following rationale:
             * `variant` defines compilation semantics
             * `layer` partitions a variant into separate compilation units
             * `role` is not a compilation boundary
             This is especially useful for toolchains such as TypeScript, where compilation is often more practical or more correct per layer than for the whole variant at once.
             ### Example
             From:
             * `(browser, production, main)`
             * `(browser, production, rjs)`
             * `(browser, test, main)`
             * `(browser, test, test)`
             * `(browser, test, rjs)`
             we derive compile units:
             * `(browser, main)`
             * `(browser, rjs)`
             * `(browser, test)`
             ### Conceptual API
             ```java
             interface CompileUnitsView {
                 Set<CompileUnit> getUnits();
                 Set<CompileUnit> getUnitsForVariant(Variant variant);
                 boolean contains(Variant variant, Layer layer);
                 Set<Role> getRoles(CompileUnit unit);
             }
             record CompileUnit(Variant variant, Layer layer) {}
             ```
             ### Meaning
             `CompileUnitsView` answers:
             * what can be compiled
             * how a variant is partitioned into compile units
             * which logical roles include a given compile unit
             ---
             ## `RoleProjectionsView`
             ### Purpose
             A role projection is defined as:
             * `(variant, role)`
             This is based on the following rationale:
             * `role` is not about compilation
             * `role` groups compile units by purpose
             * roles are more closely related to publication, aggregation, assembly, or result grouping
             ### Example
             For `browser`:
             * `production` includes compile units:
               * `(browser, main)`
               * `(browser, rjs)`
             * `test` includes compile units:
               * `(browser, main)`
               * `(browser, test)`
               * `(browser, rjs)`
             ### Conceptual API
             ```java
             interface RoleProjectionsView {
                 Set<RoleProjection> getProjections();
                 Set<RoleProjection> getProjectionsForVariant(Variant variant);
                 Set<RoleProjection> getProjectionsForRole(Role role);
                 Set<CompileUnit> getUnits(RoleProjection projection);
             }
             record RoleProjection(Variant variant, Role role) {}
             ```
             ### Meaning
             `RoleProjectionsView` answers:
             * how compile units are grouped by purpose
             * what belongs to `production`, `test`, `tool`, etc.
             * what should be aggregated or published together
             ---
             ## Why `CompileUnitsView` and `RoleProjectionsView` are not part of `VariantsView`
             `VariantsView` is intentionally minimal.
             It expresses the domain relation:
             * `(variant, role, layer)`
             `CompileUnitsView` and `RoleProjectionsView` are **derived interpretations** of that relation.
             They are natural and useful, but they are still interpretations:
             * `CompileUnit = (variant, layer)`
             * `RoleProjection = (variant, role)`
             This is why they are better treated as derived views rather than direct core model primitives.
             ---
             ## `variantSources`: source semantics for layers
             ### Purpose
             `variantSources` does **not** define variants.
             It defines how a declared `Layer` contributes sources.
             In other words:
             * `variants` defines **what exists**
             * `variantSources` defines **how layers become source inputs**
             This distinction is important.
             `variantSources` does not own the variant model. It interprets it.
             ---
             ## Main idea
             A layer source rule describes the source contribution of a layer.
             This is independent of any concrete variant or role.
             Conceptually:
             * `Layer -> source contribution rule`
             Examples of source contribution semantics:
             * base directory
             * source directories
             * logical source kinds (`ts`, `js`, `resources`)
             * declared outputs (`js`, `dts`, `resources`)
             ---
             ## `variantSources` DSL example
             ```groovy
             variantSources {
                 layerRule("main") {
                     from("src/main")
                     set("ts") {
                         srcDir("ts")
                     }
                     set("js") {
                         srcDir("js")
                     }
                     set("resources") {
                         srcDir("resources")
                     }
                     outputs("js", "dts", "resources")
                 }
                 layerRule("test") {
                     from("src/test")
                     set("ts") {
                         srcDir("ts")
                     }
                     set("resources") {
                         srcDir("resources")
                     }
                     outputs("js", "dts", "resources")
                 }
                 layerRule("rjs") {
                     from("src/rjs")
                     set("ts") {
                         srcDir("ts")
                     }
                     outputs("js", "dts")
                 }
                 layerRule("cjs") {
                     from("src/cjs")
                     set("ts") {
                         srcDir("ts")
                     }
                     outputs("js", "dts")
                 }
             }
             ```
             ### Interpretation
             This means:
             * `main` contributes `ts`, `js`, and `resources`
             * `test` contributes `ts` and `resources`
             * `rjs` contributes `ts`
             * `cjs` contributes `ts`
             These are layer rules only.
             They do not yet say which variant consumes them.
             ---
             ## Why `variantSources` remains open
             Unlike `variants`, `variantSources` does not need to be closed in the same way.
             Reasons:
             * the DSL is internal to source materialization
             * the source of truth for unit existence is already finalized in `VariantsView`
             * `GenericSourceSetMaterializer` returns `NamedDomainObjectProvider<GenericSourceSet>`
-            * late configuration of providers is expected and acceptable
             * adapters may need to refine source-related behavior after `variants` is finalized
             Therefore:
             * `variants` is finalized
             * `variantSources` may remain open
             This is not a contradiction.
             It reflects the difference between:
             * a closed domain model
             * an open infrastructure/materialization model
             ---
+            ## Late configuration policy
+            Openness of `variantSources` does not mean that late configuration is
+            semantically neutral.
+            Selector rules may be added after the finalized context becomes available, but
+            their behavior against already materialized `GenericSourceSet` objects must be
+            controlled explicitly.
+            Conceptually, `variantSources` exposes a policy choice such as:
+            ```groovy
+            variantSources {
+                lateConfigurationPolicy {
+                    failOnLateConfiguration()
+                }
+            }
+            ```
+            Available modes are:
+            * `failOnLateConfiguration()`
+            * `warnOnLateConfiguration()`
+            * `allowLateConfiguration()`
+            Meaning:
+            * `fail` rejects selector rules that target already materialized source sets
+            * `warn` allows them but emits a warning
+            * `allow` allows them silently
+            This policy is intentionally modeled as an imperative choice, not as a mutable
+            property:
+            * it must be chosen before the first selector rule is added
+            * selector rules here mean `variant(...)`, `layer(...)`, and `unit(...)`
+            * once chosen, it cannot be changed later
+            * it controls runtime behavior, not just a stored value
+            For source sets configured before materialization, selector precedence remains:
+            ```text
+            variant < layer < unit
+            ```
+            For already materialized source sets in `warn` and `allow` modes:
+            * the late action is applied as an imperative follow-up step
+            * selector precedence is not reconstructed retroactively
+            * actual observation order is the order in which late actions are registered
+            ---
             ## `VariantSourcesContext`
             `variantSources.whenFinalized(...)` remains useful, but not because `variantSources` itself is frozen.
             Its purpose is to provide access to a finalized context derived from `variants`.
             This context contains:
             * `CompileUnitsView`
             * `RoleProjectionsView`
             * `GenericSourceSetMaterializer`
             Conceptually:
             ```java
             interface VariantSourcesContext {
                 CompileUnitsView getCompileUnits();
                 RoleProjectionsView getRoleProjections();
                 GenericSourceSetMaterializer getSourceSets();
             }
             ```
             This callback is also replayable.
             Example:
             ```java
             variantSources.whenFinalized(ctx -> {
                 var units = ctx.getCompileUnits();
                 var roles = ctx.getRoleProjections();
                 var sourceSets = ctx.getSourceSets();
             });
             ```
             ---
             ## `GenericSourceSetMaterializer`
             ### Purpose
             `GenericSourceSetMaterializer` is the official source of truth for materialized source sets.
             It is responsible for:
             * lazy creation of `GenericSourceSet`
             * applying `layerRule`
             * connecting a compile unit to a source set provider
             * exposing source sets to adapters
             This is the correct place to apply `layerRule`.
             Adapters should not apply layer rules themselves.
             ### Conceptual API
             ```java
             interface GenericSourceSetMaterializer {
                 NamedDomainObjectProvider<GenericSourceSet> getSourceSet(CompileUnit unit);
             }
             ```
             ---
             ## Why `GenericSourceSetMaterializer` should own `layerRule` application
             If adapters applied `layerRule` directly, responsibility would leak across multiple layers:
             * one component would know compile units
             * another would know source semantics
             * another would know how to configure `GenericSourceSet`
             This would make the model harder to reason about.
             Instead:
             * `layerRule` is DSL/spec-level
             * `GenericSourceSetMaterializer` is execution/materialization-level
             * adapters are consumption-level
             This gives a much cleaner separation.
             ---
             ## `GenericSourceSet` as materialization target
             `GenericSourceSet` is the materialized source aggregation object.
             It is a good fit because it can represent:
             * multiple logical source sets
             * aggregated source directories
             * declared outputs
             * lazy registration through providers
             The materializer is therefore the owner of:
             * creating `GenericSourceSet`
             * populating its source sets
             * declaring outputs
             * returning a provider for later use
             ---
             ## How an adapter should use the model
             Example:
             ```java
             variantSources.whenFinalized(ctx -> {
                 for (CompileUnit unit : ctx.getCompileUnits().getUnits()) {
                     var sourceSetProvider = ctx.getSourceSets().getSourceSet(unit);
                     var variant = unit.variant();
                     var layer = unit.layer();
                     // create compile task for this compile unit
                     // configure compiler options from variant semantics
                     // use sourceSetProvider as task input
                 }
                 for (RoleProjection projection : ctx.getRoleProjections().getProjections()) {
                     var units = ctx.getRoleProjections().getUnits(projection);
                     // aggregate outputs of included compile units
                     // use for publication or assembly
                 }
             });
             ```
             ---
             ## Why compile unit is `(variant, layer)` and not `(variant, role)` or `(variant, role, layer)`
             ### Not `(variant, role)`
             Because role is not a compilation boundary.
             Role is a logical grouping of results.
             ### Not `(variant, role, layer)`
             Because role does not define the compile unit itself.
             A compile unit is a unit of compilation, not a unit of publication grouping.
             ### Correct interpretation
             * `(variant, layer)` = compile unit
             * `(variant, role)` = logical result group
             * `(variant, role, layer)` = membership relation between them
             This is the most coherent separation.
             ---
             ## Model boundaries
             ### What belongs to `variants`
             * declared domains: `Layer`, `Role`, `Variant`
             * normalized relation `(variant, role, layer)`
             * finalization lifecycle
             * finalized `VariantsView`
             ### What belongs to derived views
             * compile units: `(variant, layer)`
             * role projections: `(variant, role)`
             ### What belongs to `variantSources`
             * source semantics of layers
             * source materialization rules
             * lazy `GenericSourceSet` provisioning
             * source adapter integration
             ### What does not belong to `variants`
             * source directories
             * base paths
             * output declarations
             * source set layout
             * task registration
             * compiler-specific assumptions
             ---
             ## Design principles
             ### 1. Keep the core model small
             The core model should only contain domain facts.
             ### 2. Separate domain truth from materialization
             The existence of compile units comes from `VariantsView`, not from source rules.
             ### 3. Treat source materialization as infrastructure
             `variantSources` is an interpretation layer, not the source of truth.
             ### 4. Prefer replayable finalized hooks
             Adapters should not depend on raw Gradle lifecycle callbacks such as `afterEvaluate`.
-            ### 5. Keep heavy runtime objects behind providers
+            ### 5. Make late behavior explicit
+            Late configuration after materialization is a policy decision, not an implicit
+            guarantee.
+            ### 6. Keep heavy runtime objects behind providers
             Materialized `GenericSourceSet` objects should remain behind a lazy API.
             ---
             ## Summary
             The model is intentionally split into two layers.
             ### `variants`
             A closed, finalized domain model:
             * `Layer`
             * `Role`
             * `Variant`
             * `(variant, role, layer)`
             ### `variantSources`
             An open, source-materialization layer:
             * layer source rules
             * compile-unit source set materialization
             * adapter-facing `GenericSourceSet` providers
             ### Derived views
             From the finalized variant model:
             * `CompileUnitsView`: `(variant, layer)`
             * `RoleProjectionsView`: `(variant, role)`
             ### Operational interpretation
             * `variant` defines compilation semantics
             * `layer` partitions compilation
             * `role` groups results by purpose
             This keeps the core model stable and minimal, while allowing source handling and adapter integration to remain flexible.

variants/src/main/java/org/implab/gradle/variants/sources/internal/DefaultLayerConfigurationRegistry.java removed 0 -48

	Site-wide shortcuts
/	Use quick search box
g h	Goto home page
g g	Goto my private gists page
g G	Goto my public gists page
g 0-9	Goto bookmarked items from 0-9
n r	New repository page
n g	New gist page

	Repositories
g s	Goto summary page
g c	Goto changelog page
g f	Goto files page
g F	Goto files page with file search activated
g p	Goto pull requests page
g o	Goto repository settings
g O	Goto repository access permissions settings
t s	Toggle sidebar on some pages