implab/gradle-common Commit - r44:ae7ec3f08ac3

more documentation

cin -

r44:ae7ec3f08ac3 default

parent child

Context file:

r44:ae7ec3f08ac3

Collapse all files

variant_sources_precedence.md +68 0

             # `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
+            - the enforcement point is the first selector registration itself; finalization
+              of `variants` alone does not freeze this policy
             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
             ---
+            ## Compile-Unit Naming Policy
+            `variantSources` also exposes a policy for projecting compile units to symbolic
+            source-set names:
+            ```groovy
+            variantSources {
+                namingPolicy {
+                    failOnNameCollision()
+                }
+            }
+            ```
+            Base projected name:
+            - `sourceSetName = variantName + capitalize(layerName)`
+            Example:
+            - `(browser, main)` -> `browserMain`
+            - `(browser, rjs)` -> `browserRjs`
+            Available modes:
+            - `failOnNameCollision()` rejects finalized compile-unit models that project the
+              same base name for different compile units
+            - `resolveNameCollision()` resolves such collisions deterministically
+            ### `resolveNameCollision()` semantics
+            Conflicting compile units are ordered canonically by:
+            ```text
+            (variant.name, layer.name)
+            ```
+            Name assignment in a conflicting group is:
+            - the first compile unit keeps the base name
+            - the second gets suffix `2`
+            - the third gets suffix `3`
+            - and so on
+            Example:
+            - `(foo, variantBar)` and `(fooVariant, bar)` both project to `fooVariantBar`
+            - after canonical ordering:
+              - `(foo, variantBar)` -> `fooVariantBar`
+              - `(fooVariant, bar)` -> `fooVariantBar2`
+            ### Fixation Point
+            Naming policy is fixed when the finalized `VariantSourcesContext` is created.
+            Operationally this means:
+            - policy selection must happen before `variantSources.whenFinalized(...)`
+              becomes observable
+            - compile-unit names are projected and validated before queued
+              `whenFinalized(...)` callbacks are replayed
+            - changing naming policy from inside a `whenFinalized(...)` callback is too late
+            ---
             ## 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.
             This guarantees that:
             - selector precedence is stable before materialization
             - registration order is preserved
             - 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
+            - compile-unit naming is governed by `namingPolicy(...)`
+            - by default, name collisions fail fast during finalized context creation
             - `variants` defines what exists
             - `variantSources` defines how those compile units are materialized as source sets

variants/src/main/java/org/implab/gradle/variants/sources/SourceSetMaterializer.java +7 -3

             package org.implab.gradle.variants.sources;
             import org.gradle.api.NamedDomainObjectProvider;
             import org.implab.gradle.common.sources.GenericSourceSet;
             /**
-             * Materializes symbolic source set names into actual GenericSourceSet
+             * Materializes symbolic source set names into actual {@link GenericSourceSet}
              * instances.
+             *
+             * <p>Symbolic names are assigned from the finalized compile-unit model using
+             * the selected
+             * {@link VariantSourcesExtension#namingPolicy(org.gradle.api.Action)}.
              */
             public interface SourceSetMaterializer {
                 /**
                  * Returns a lazy provider for the source set corresponding to the compile unit.
                  *
-                 * The provider is stable and cached per compile unit.
+                 * <p>The provider is stable and cached per compile unit.
                  */
                 NamedDomainObjectProvider<GenericSourceSet> getSourceSet(CompileUnit unit);
-            }
  No newline at end of file

variants/src/main/java/org/implab/gradle/variants/sources/VariantSourcesContext.java +3 -1

             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.
+             * <p>Identity in this registry is the {@link GenericSourceSet} name assigned
+             * by the finalized
+             * {@link VariantSourcesExtension#namingPolicy(org.gradle.api.Action)}.
              */
             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
                  *
                  * <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);
             }

variants/src/main/java/org/implab/gradle/variants/sources/VariantSourcesExtension.java +59 0

             package org.implab.gradle.variants.sources;
             import org.eclipse.jdt.annotation.NonNullByDefault;
             import org.gradle.api.Action;
             import org.implab.gradle.common.core.lang.Closures;
             import org.implab.gradle.common.sources.GenericSourceSet;
             import groovy.lang.Closure;
             @NonNullByDefault
             public interface VariantSourcesExtension {
                 /**
                  * Selects how selector rules behave when they target an already materialized
                  * {@link GenericSourceSet}.
                  *
                  * <p>This policy is single-valued:
                  * <ul>
                  * <li>it must be selected before the first selector rule is registered via
                  * {@link #variant(String, Action)}, {@link #layer(String, Action)} or
                  * {@link #unit(String, String, Action)};</li>
                  * <li>once selected, it cannot be changed later;</li>
                  * <li>the policy controls both diagnostics and late-application semantics.</li>
                  * </ul>
+                 *
+                 * <p>If not selected explicitly, the default is
+                 * {@link LateConfigurationPolicySpec#failOnLateConfiguration()}.
                  */
                 void lateConfigurationPolicy(Action<? super LateConfigurationPolicySpec> action);
                 default void lateConfigurationPolicy(Closure<?> closure) {
                     lateConfigurationPolicy(Closures.action(closure));
                 }
+                /**
+                 * Selects how compile-unit name collisions are handled when the finalized
+                 * source context is created.
+                 *
+                 * <p>This policy is single-valued:
+                 * <ul>
+                 * <li>it must be selected before the finalized
+                 * {@link VariantSourcesContext} becomes observable through
+                 * {@link #whenFinalized(Action)};</li>
+                 * <li>once the context is being created, the policy is fixed and cannot be
+                 * changed later;</li>
+                 * <li>the policy governs validation of compile-unit names produced by the
+                 * source-set materializer.</li>
+                 * </ul>
+                 *
+                 * <p>If not selected explicitly, the default is
+                 * {@link NamingPolicySpec#failOnNameCollision()}.
+                 */
                 void namingPolicy(Action<? super NamingPolicySpec> action);
                 default void namingPolicy(Closure<?> closure) {
                     namingPolicy(Closures.action(closure));
                 }
+                /**
+                 * Registers a selector rule for all compile units of the given layer.
+                 *
+                 * <p>Registering the first selector rule fixes the selected
+                 * {@link #lateConfigurationPolicy(Action)} for the remaining extension
+                 * lifecycle.
+                 */
                 void layer(String layerName, Action<? super GenericSourceSet> action);
                 default void layer(String layerName, Closure<?> closure) {
                     layer(layerName, Closures.action(closure));
                 }
+                /**
+                 * Registers a selector rule for all compile units of the given variant.
+                 *
+                 * <p>Registering the first selector rule fixes the selected
+                 * {@link #lateConfigurationPolicy(Action)} for the remaining extension
+                 * lifecycle.
+                 */
                 void variant(String variantName, Action<? super GenericSourceSet> action);
                 default void variant(String variantName, Closure<?> closure) {
                     variant(variantName, Closures.action(closure));
                 }
+                /**
+                 * Registers a selector rule for one exact compile unit.
+                 *
+                 * <p>Registering the first selector rule fixes the selected
+                 * {@link #lateConfigurationPolicy(Action)} for the remaining extension
+                 * lifecycle.
+                 */
                 void unit(String variantName, String layerName, Action<? super GenericSourceSet> action);
                 /**
                  * Invoked when finalized variants-derived source context becomes available.
                  *
                  * Replayable:
                  * <ul>
                  * <li>if called before variants finalization, action is queued
                  * <li>if called after variants finalization, action is invoked immediately
                  * </ul>
+                 *
+                 * <p>By the time this callback becomes observable, compile-unit naming
+                 * policy has already been fixed and symbolic source-set names for finalized
+                 * compile units are determined.
                  */
                 void whenFinalized(Action<? super VariantSourcesContext> action);
                 default void whenFinalized(Closure<?> closure) {
                     whenFinalized(Closures.action(closure));
                 }
                 /**
                  * Imperative selector for the late-configuration mode.
                  *
                  * <p>Exactly one mode is expected to be chosen for the extension lifecycle.
                  */
                 interface LateConfigurationPolicySpec {
                     /**
                      * Rejects selector registration if it targets any already materialized
                      * source set.
                      */
                     void failOnLateConfiguration();
                     /**
                      * Allows late selector registration, but emits a warning when it targets an
                      * already materialized source set.
                      *
                      * <p>For such targets, selector precedence is not re-established
                      * retroactively. The action is applied as a late imperative step, after the
                      * state already produced at the materialization moment.
                      */
                     void warnOnLateConfiguration();
                     /**
                      * Allows late selector registration without a warning when it targets an
                      * already materialized source set.
                      *
                      * <p>For such targets, selector precedence is not re-established
                      * retroactively. The action is applied as a late imperative step, after the
                      * state already produced at the materialization moment.
                      */
                     void allowLateConfiguration();
                 }
                 interface NamingPolicySpec {
+                    /**
+                     * Rejects finalized compile-unit models that project the same source-set
+                     * name for different compile units.
+                     */
                     void failOnNameCollision();
+                    /**
+                     * Resolves name collisions deterministically for the finalized
+                     * compile-unit model.
+                     *
+                     * <p>Conflicting compile units are ordered canonically by
+                     * {@code (variant.name, layer.name)}. The first unit keeps the base
+                     * projected name, and each next unit receives a numeric suffix
+                     * ({@code 2}, {@code 3}, ...).
+                     */
                     void resolveNameCollision();
                 }
             }

variants_variant_sources.md +104 -8

             # 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>`
+            * `SourceSetMaterializer` returns `NamedDomainObjectProvider<GenericSourceSet>`
             * 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
+            This openness is still constrained by explicit policy fixation points:
+            * late-configuration policy is fixed when the first selector rule is registered
+            * naming policy is fixed when the finalized `VariantSourcesContext` is created
             ---
             ## 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
+            * the enforcement point is the first selector registration itself, not variants
+              finalization in isolation
             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
             ---
+            ## Compile-unit naming policy
+            Source-set naming is treated as a separate policy concern from selector
+            registration.
+            Conceptually, `variantSources` exposes:
+            ```groovy
+            variantSources {
+                namingPolicy {
+                    failOnNameCollision()
+                }
+            }
+            ```
+            The base projected name of a compile unit is:
+            ```text
+            variantName + capitalize(layerName)
+            ```
+            Examples:
+            * `(browser, main)` -> `browserMain`
+            * `(browser, rjs)` -> `browserRjs`
+            Available modes are:
+            * `failOnNameCollision()` - reject finalized compile-unit models that project
+              the same source-set name for different compile units
+            * `resolveNameCollision()` - resolve such conflicts deterministically
+            ### `resolveNameCollision()` semantics
+            Conflicting compile units are ordered canonically by:
+            ```text
+            (variant.name, layer.name)
+            ```
+            Within one conflicting group:
+            * the first compile unit keeps the base name
+            * the second gets suffix `2`
+            * the third gets suffix `3`
+            * and so on
+            For example, if:
+            * `(foo, variantBar)` projects to `fooVariantBar`
+            * `(fooVariant, bar)` also projects to `fooVariantBar`
+            then canonical ordering yields:
+            * `(foo, variantBar)` -> `fooVariantBar`
+            * `(fooVariant, bar)` -> `fooVariantBar2`
+            ### Fixation point
+            Naming policy is fixed when the finalized `VariantSourcesContext` is created.
+            Operationally this means:
+            * naming policy must be selected before `variantSources.whenFinalized(...)`
+              becomes observable
+            * compile-unit names are projected and validated before queued
+              `whenFinalized(...)` callbacks are replayed
+            * changing naming policy from inside a `whenFinalized(...)` callback is too late
+            This differs intentionally from late-configuration policy:
+            * late-configuration policy is fixed by the first selector rule
+            * naming policy is fixed by finalized-context creation
+            ---
             ## `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`
+            * `SourceSetMaterializer`
+            By the time the context becomes observable:
+            * compile-unit naming policy is already fixed
+            * symbolic source-set names for finalized compile units are already determined
             Conceptually:
             ```java
             interface VariantSourcesContext {
                 CompileUnitsView getCompileUnits();
                 RoleProjectionsView getRoleProjections();
-                GenericSourceSetMaterializer getSourceSets();
+                SourceSetMaterializer getSourceSets();
             }
             ```
             This callback is also replayable.
             Example:
             ```java
             variantSources.whenFinalized(ctx -> {
                 var units = ctx.getCompileUnits();
                 var roles = ctx.getRoleProjections();
                 var sourceSets = ctx.getSourceSets();
             });
             ```
             ---
-            ## `GenericSourceSetMaterializer`
+            ## `SourceSetMaterializer`
             ### Purpose
-            `GenericSourceSetMaterializer` is the official source of truth for materialized source sets.
+            `SourceSetMaterializer` is the official source of truth for materialized source sets.
             It is responsible for:
             * lazy creation of `GenericSourceSet`
+            * projecting finalized compile units to symbolic source-set names
+            * validating or resolving name collisions according to naming policy
             * 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 {
+            interface SourceSetMaterializer {
                 NamedDomainObjectProvider<GenericSourceSet> getSourceSet(CompileUnit unit);
             }
             ```
             ---
-            ## Why `GenericSourceSetMaterializer` should own `layerRule` application
+            ## Why `SourceSetMaterializer` 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
+            * `SourceSetMaterializer` 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. 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.
+            ### 7. Make name-collision behavior explicit
+            Compile-unit naming must be governed by an explicit policy, not by incidental
+            materialization order.
             ---
             ## 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
+            * compile-unit naming policy
             * 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.

General Comments 0

Write
Preview

You need to be logged in to leave comments. Login now

No TODOs yet

	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