implab/gradle-common Commit - r60:e376d0cab00e

Set the project version to 0.1.0, add publication descriptions/license metadata, and keep module-level docs as compatibility pointers to the root documentation.

cin -

r60:e376d0cab00e default

parent child

Context file:

r60:e376d0cab00e

Collapse all files

LICENSE created 644 +24 0

@@ -0,0 +1,24
	1	BSD 2-Clause License
	2
	3	Copyright (c) 2026 gradle-common contributors.
	4
	5	Redistribution and use in source and binary forms, with or without modification,
	6	are permitted provided that the following conditions are met:
	7
	8	1. Redistributions of source code must retain the above copyright notice, this
	9	list of conditions and the following disclaimer.
	10
	11	2. Redistributions in binary form must reproduce the above copyright notice,
	12	this list of conditions and the following disclaimer in the documentation
	13	and/or other materials provided with the distribution.
	14
	15	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
	16	ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
	17	WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	18	DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
	19	ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	20	(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
	21	LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
	22	ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	23	(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
	24	SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

PUBLISHING.md created 644 +99 0

@@ -0,0 +1,99
	1	# Local Ivy Publishing
	2
	3	This project currently publishes only to a local Ivy repository. Maven Central,
	4	signing, and Gradle Plugin Portal publication are intentionally out of scope for
	5	the current preparation step.
	6
	7	Published Ivy descriptors include the BSD-2-Clause license metadata.
	8
	9	## Repository
	10
	11	The configured Ivy repository is:
	12
	13	```text
	14	${user.home}/ivy-repo
	15	```
	16
	17	This is defined in:
	18
	19	- `common/build.gradle`
	20	- `variants/build.gradle`
	21
	22	## Verify Before Publishing
	23
	24	Run a full clean verification:
	25
	26	```bash
	27	./gradlew clean check javadoc jar sourcesJar javadocJar --rerun-tasks
	28	```
	29
	30	Optional configuration-cache smoke check:
	31
	32	```bash
	33	./gradlew check --configuration-cache
	34	```
	35
	36	## Publish
	37
	38	Publish all modules:
	39
	40	```bash
	41	./gradlew publish
	42	```
	43
	44	Publish modules explicitly:
	45
	46	```bash
	47	./gradlew :common:publishIvyPublicationToIvyRepository \
	48	:variants:publishIvyPublicationToIvyRepository
	49	```
	50
	51	Safe smoke publish into a temporary repository:
	52
	53	```bash
	54	./gradlew -Duser.home=/tmp/gradle-common-ivy-smoke \
	55	:common:publishIvyPublicationToIvyRepository \
	56	:variants:publishIvyPublicationToIvyRepository \
	57	--rerun-tasks
	58	```
	59
	60	## Consume Locally
	61
	62	Use `buildscript` classpath for now:
	63
	64	```groovy
	65	buildscript {
	66	repositories {
	67	ivy {
	68	url "${System.properties['user.home']}/ivy-repo"
	69	}
	70	mavenCentral()
	71	}
	72	dependencies {
	73	classpath 'org.implab.gradle:variants:0.1.0'
	74	}
	75	}
	76
	77	apply plugin: 'org.implab.gradle-variants'
	78	apply plugin: 'org.implab.gradle-variants-sources'
	79	```
	80
	81	The `plugins {}` DSL needs generated plugin marker artifacts and is not part of
	82	the current local Ivy contract.
	83
	84	## Published Artifacts
	85
	86	Each module publishes:
	87
	88	- `<module>-<version>.jar`
	89	- `<module>-<version>-sources.jar`
	90	- `<module>-<version>-javadoc.jar`
	91	- `ivy.xml`
	92	- Gradle module metadata
	93
	94	## Current Coordinates
	95
	96	```text
	97	org.implab.gradle:common:0.1.0
	98	org.implab.gradle:variants:0.1.0
	99	```

README.md created 644 +296 0

@@ -0,0 +1,296
	1	# gradle-common
	2
	3	Java 21 multi-project build with shared Gradle utilities and experimental
	4	variant-oriented Gradle plugins.
	5
	6	The repository currently publishes to a local Ivy repository only. Maven Central
	7	and Gradle Plugin Portal publication are intentionally not configured yet.
	8
	9	## Modules
	10
	11	- `common` - shared Gradle utilities, JSON helpers, shell execution helpers, and
	12	small core value/util classes.
	13	- `variants` - Gradle plugins for variant topology, source-set materialization,
	14	and outgoing artifact slots.
	15
	16	## Requirements
	17
	18	- JDK 21.
	19	- Gradle Wrapper from this repository, currently Gradle 8.10.2.
	20
	21	The produced bytecode targets Java 21.
	22
	23	## License
	24
	25	This project is licensed under the BSD 2-Clause "Simplified" License
	26	(`BSD-2-Clause`). See [LICENSE](LICENSE).
	27
	28	## Local Build
	29
	30	```bash
	31	./gradlew clean check javadoc jar sourcesJar javadocJar --rerun-tasks
	32	```
	33
	34	Configuration cache smoke check:
	35
	36	```bash
	37	./gradlew check --configuration-cache
	38	```
	39
	40	## Local Ivy Publication
	41
	42	The current publication target is:
	43
	44	```text
	45	${user.home}/ivy-repo
	46	```
	47
	48	Publish both modules locally:
	49
	50	```bash
	51	./gradlew :common:publishIvyPublicationToIvyRepository \
	52	:variants:publishIvyPublicationToIvyRepository
	53	```
	54
	55	or:
	56
	57	```bash
	58	./gradlew publish
	59	```
	60
	61	The publication includes:
	62
	63	- main jar
	64	- sources jar
	65	- javadoc jar
	66	- Ivy descriptor
	67	- Gradle module metadata
	68
	69	## Local Consumption
	70
	71	Current plugin ids are packaged as classic Gradle plugin marker resources inside
	72	the `variants` jar:
	73
	74	- `org.implab.gradle-variants`
	75	- `org.implab.gradle-sources`
	76	- `org.implab.gradle-variants-sources`
	77	- `org.implab.gradle-variants-artifacts`
	78
	79	Until Gradle Plugin Portal marker artifacts are configured, consume the plugin
	80	through `buildscript` classpath:
	81
	82	```groovy
	83	buildscript {
	84	repositories {
	85	ivy {
	86	url "${System.properties['user.home']}/ivy-repo"
	87	}
	88	mavenCentral()
	89	}
	90	dependencies {
	91	classpath 'org.implab.gradle:variants:0.1.0'
	92	}
	93	}
	94
	95	apply plugin: 'org.implab.gradle-variants'
	96	apply plugin: 'org.implab.gradle-variants-sources'
	97	```
	98
	99	The `plugins { id(...) version(...) }` DSL is not part of the current local Ivy
	100	contract.
	101
	102	## Variants DSL
	103
	104	`variants` defines the finalized build topology. It does not create compile
	105	tasks, source directories, or outgoing publications by itself.
	106
	107	```groovy
	108	apply plugin: 'org.implab.gradle-variants'
	109
	110	variants.layers.create('main')
	111	variants.layers.create('test')
	112	variants.roles.create('main')
	113	variants.roles.create('test')
	114
	115	variants.variant('browser') {
	116	role('main') {
	117	layers('main')
	118	}
	119	role('test') {
	120	layers('main', 'test')
	121	}
	122	}
	123
	124	variants.whenFinalized { view ->
	125	println view.entries.collect {
	126	"${it.variant().name}:${it.role().name}:${it.layer().name}"
	127	}.sort()
	128	}
	129	```
	130
	131	The finalized model exposes cheap identity objects: `Variant`, `Role`, `Layer`,
	132	and the normalized relation `(variant, role, layer)`.
	133
	134	## Sources DSL
	135
	136	`sources` creates standalone `GenericSourceSet` objects. This is useful for
	137	fallback workflows that do not need variant topology.
	138
	139	```groovy
	140	apply plugin: 'org.implab.gradle-sources'
	141
	142	sources.create('main') {
	143	declareOutputs('js')
	144	registerOutput('js', layout.projectDirectory.file('inputs/main.js'))
	145
	146	sets.create('ts') {
	147	srcDir 'src/main/ts'
	148	}
	149	}
	150	```
	151
	152	`SourcesPlugin` applies layout conventions:
	153
	154	- `sourceSetDir = src/<sourceSet>`
	155	- `outputsDir = build/out/<sourceSet>`
	156
	157	The base `GenericSourceSet` model itself is convention-free.
	158
	159	## Variant Sources DSL
	160
	161	`variantSources` derives compile units from finalized `variants`.
	162
	163	A compile unit is:
	164
	165	```text
	166	(variant, layer)
	167	```
	168
	169	Selectors configure materialized compile-unit source sets:
	170
	171	```groovy
	172	apply plugin: 'org.implab.gradle-variants-sources'
	173
	174	variants.layers.create('main')
	175	variants.roles.create('main')
	176	variants.variant('browser') {
	177	role('main') {
	178	layers('main')
	179	}
	180	}
	181
	182	variantSources {
	183	layer('main') {
	184	sourceSet {
	185	declareOutputs('js')
	186	registerOutput('js', layout.projectDirectory.file('inputs/browser.js'))
	187	}
	188	}
	189
	190	configureEach {
	191	println "sourceSet=${sourceSet.name}, variant=${variant.name}, layer=${layer.name}"
	192	}
	193	}
	194	```
	195
	196	Selector order for future materialization is:
	197
	198	```text
	199	configureEach -> variant -> layer -> unit
	200	```
	201
	202	Late selector registration is controlled by:
	203
	204	```groovy
	205	variantSources {
	206	lateConfigurationPolicy {
	207	failOnLateConfiguration()
	208	}
	209	}
	210	```
	211
	212	Compile-unit source set names are generated by default as:
	213
	214	```text
	215	<variant> + capitalize(<layer>)
	216	```
	217
	218	Name collisions fail by default and may be resolved deterministically:
	219
	220	```groovy
	221	variantSources {
	222	namingPolicy {
	223	resolveNameCollision()
	224	}
	225	}
	226	```
	227
	228	## Variant Artifacts DSL
	229
	230	`variantArtifacts` is an experimental outgoing artifact layer over `variants`
	231	and `variantSources`.
	232
	233	The current model maps:
	234
	235	- `Variant` to a variant-level consumable outgoing configuration.
	236	- `Slot` to a Gradle outgoing artifact variant inside that configuration.
	237	- `primarySlot` to the primary artifact set of the outgoing configuration.
	238
	239	```groovy
	240	apply plugin: 'org.implab.gradle-variants-artifacts'
	241
	242	variants.layers.create('main')
	243	variants.roles.create('main')
	244	variants.variant('browser') {
	245	role('main') {
	246	layers('main')
	247	}
	248	}
	249
	250	variantSources.layer('main') {
	251	sourceSet {
	252	declareOutputs('types', 'js')
	253	registerOutput('types', layout.projectDirectory.file('inputs/index.d.ts'))
	254	registerOutput('js', layout.projectDirectory.file('inputs/index.js'))
	255	}
	256	}
	257
	258	variantArtifacts {
	259	variant('browser') {
	260	primarySlot('typesPackage') {
	261	fromVariant {
	262	output('types')
	263	}
	264	}
	265	slot('js') {
	266	fromVariant {
	267	output('js')
	268	}
	269	}
	270	}
	271
	272	whenOutgoingConfiguration { publication ->
	273	publication.configuration {
	274	description = "Outgoing contract for ${publication.variant.name}"
	275	}
	276	}
	277
	278	whenOutgoingSlot { publication ->
	279	println "slot=${publication.artifactSlot.slot.name}, primary=${publication.primary}"
	280	}
	281	}
	282	```
	283
	284	The artifact API is still considered pre-1.0 and may change.
	285
	286	## Publication Status
	287
	288	Current status:
	289
	290	- local Ivy publication only
	291	- no Maven Central publication metadata
	292	- no signing
	293	- no Gradle Plugin Portal marker artifacts
	294	- BSD-2-Clause license committed
	295
	296	Before external publication, see [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md).

RELEASE_CHECKLIST.md created 644 +63 0

@@ -0,0 +1,63
	1	# Release Checklist
	2
	3	This checklist tracks what should be true before publishing outside the local
	4	Ivy repository.
	5
	6	## Current Scope
	7
	8	For now the project is prepared for local Ivy publication only.
	9
	10	## Required Before External Publication
	11
	12	- Add Maven publication (`maven-publish`) if publishing to Maven repositories.
	13	- Add signing for Maven Central or any repository that requires signed
	14	artifacts.
	15	- Add complete POM metadata: project name, description, URL, license,
	16	developers, and SCM coordinates.
	17	- Keep Java 21 as the public baseline and document it for consumers.
	18	- Decide whether `variants` artifact APIs are published as experimental or
	19	split into a later module.
	20	- Add Gradle plugin marker artifact generation if `plugins { id(...) version(...) }`
	21	must work.
	22	- Add a published-consumption smoke test that resolves artifacts from a
	23	temporary local repository.
	24
	25	## Local Ivy Release Steps
	26
	27	1. Ensure the Mercurial working tree is clean.
	28	2. Run:
	29
	30	```bash
	31	./gradlew clean check javadoc jar sourcesJar javadocJar --rerun-tasks
	32	```
	33
	34	3. Optionally run:
	35
	36	```bash
	37	./gradlew check --configuration-cache
	38	```
	39
	40	4. Publish locally:
	41
	42	```bash
	43	./gradlew publish
	44	```
	45
	46	5. Optionally smoke-publish into `/tmp` first:
	47
	48	```bash
	49	./gradlew -Duser.home=/tmp/gradle-common-ivy-smoke \
	50	:common:publishIvyPublicationToIvyRepository \
	51	:variants:publishIvyPublicationToIvyRepository \
	52	--rerun-tasks
	53	```
	54
	55	6. Verify `${user.home}/ivy-repo/org.implab.gradle` contains `common` and
	56	`variants` for the expected version.
	57
	58	## API Status
	59
	60	- `common` is intended to be a shared utility library.
	61	- `variants` core and source APIs are pre-1.0 and should be treated as
	62	evolving.
	63	- `variantArtifacts` is experimental and may change more aggressively.

.hgignore +1 0

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

common/build.gradle +6 0

             plugins {
                 id "java-library"
                 id "ivy-publish"
             }
+            description = "Shared Gradle build utilities used by Implab plugins"
             java {
                 withJavadocJar()
                 withSourcesJar()
                 toolchain {
                     languageVersion = JavaLanguageVersion.of(21)
                 }
             }
             dependencies {
                 compileOnly libs.jdt.annotations
                 api gradleApi(),
                     libs.bundles.jackson
                 testImplementation gradleTestKit()
                 testImplementation "org.junit.jupiter:junit-jupiter-api:5.11.4"
                 testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:5.11.4"
                 testRuntimeOnly "org.junit.platform:junit-platform-launcher:1.11.4"
             }
             task printVersion{
                 doLast {
                     println "project: $project.group:$project.name:$project.version"
                     println "jar: ${->jar.archiveFileName.get()}"
                 }
             }
             test {
                 useJUnitPlatform()
             }
             publishing {
                 repositories {
                     ivy {
                         url "${System.properties["user.home"]}/ivy-repo"
                     }
                 }
                 publications {
                     ivy(IvyPublication) {
                         from components.java
                         descriptor.description {
                             text = providers.provider({ description })
                         }
+                        descriptor.license {
+                            name = "BSD-2-Clause"
+                            url = "https://spdx.org/licenses/BSD-2-Clause.html"
                         }
                     }
                 }
+            }

common/readme.md +12 -128

@@ -1,134 +1,18
1	# Gradle Common ~~Sources Model~~	1	# Gradle Common
2
3	## NAME
4
5	`gradle-common/common` — набор плагинов для моделирования вариантов сборки,
6	регистрации source sets и интеграции этой модели с toolchain-адаптерами.
7
8	## SYNOPSIS
9
10	```groovy
11	plugins {
12	id 'org.implab.gradle-variants-sources'
13	}
14
15	variants {
16	layer('mainBase')
17	layer('mainAmd')
18
19	variant('browser') {
20	role('main') { layers('mainBase', 'mainAmd') }
21	}
22	}
23
24	variantSources {
25	bind('mainBase') {
26	configureSourceSet {
27	declareOutputs('compiled')
28	}
29	}
30
31	bind('mainAmd').sourceSetNamePattern = '{variant}{layerCap}'
32		2
33	whenRegistered { sourceSetName() }	3	`common` is the shared utility module used by the Gradle plugins in this
34		4	repository.
35	whenBound { ctx ->
36	ctx.configureSourceSet {
37	declareOutputs('typings')
38	}
39	}
40	}
41	```
42
43	## DESCRIPTION
44
45	Модуль состоит из трех логических частей:
46		5
47	- `variants` — декларативная доменная модель сборки;	6	It contains:
48	- `sources` — модель физически регистрируемых source sets;
49	- `variantSources` — адаптер, который связывает первые две модели.
50
51	Ниже раскрытие каждой части.
52
53	### variants
54
55	`variants` задает структуру пространства сборки: какие есть слои, какие роли
56	используют эти слои в каждом варианте, какие есть атрибуты и artifact slots.
57	Модель не создает задачи и не привязана к TS/JS.
58
59	Практический смысл:
60
61	- формализовать архитектуру сборки;
62	- дать адаптерам единый источник правды.
63
64	### sources
65		7
66	`sources` описывает независимые source sets (`GenericSourceSet`) с именованными	8	- core Gradle helper utilities
67	outputs. Это уже "физический" уровень, к которому удобно привязывать задачи,	9	- small language/value helpers
68	артефакты и task inputs/outputs.	10	- shell execution helpers
69		11	- JSON DSL and JSON-writing task support
70	Практический смысл:
71
72	- создать единый контракт по входам/выходам;
73	- регистрировать результаты задач как outputs source set;
74	- минимизировать ручные `dependsOn` за счет модели outputs.
75
76	### variantSources
77
78	`variantSources` регистрирует source sets на основе `variants`, применяет
79	конфигурацию layer-bindings и отдает события (`whenRegistered`, `whenBound`) для
80	адаптеров других плагинов.
81
82	Практический смысл:
83
84	- переводить логическую модель `variants` в executable-модель `sources`;
85	- навешивать политики toolchain на зарегистрированные source sets;
86	- синхронизировать плагины через replayable callback-контракт.
87
88	## DOMAIN MODEL
89
90	- `BuildLayer` — canonical identity-model объявленного слоя.
91	- `BuildVariant` — агрегат ролей, атрибутов, артефактных слотов.
92	- `BuildRole` — роль внутри варианта, содержит ссылки на declared layer names.
93	- `GenericSourceSet` — зарегистрированный набор исходников и outputs.
94	- `LayerBindingSpec` — публичный DSL-contract adapter policy/callbacks для слоя.
95	- `SourceSetRegistration` — payload события регистрации source set.
96	- `SourceSetUsageBinding` — payload события usage-binding.
97
98	## EVENT CONTRACT
99		12
100	- `whenRegistered`:	13	It no longer contains the variant/source/artifact plugin model. Those plugins
101	- событие нового уникального source set name;	14	live in the `variants` module.
102	- replayable.
103	- `whenBound`:
104	- событие каждой usage-связки `variant/role/layer`;
105	- replayable.
106
107	Closure callbacks работают в delegate-first режиме (`@DelegatesTo`). Для
108	вложенных closure рекомендуется явный параметр (`ctx -> ...`).
109
110	## KEY CLASSES
111		15
112	- `SourcesPlugin` — регистрирует extension `sources`.	16	See the root [README.md](../README.md) and [PUBLISHING.md](../PUBLISHING.md) for
113	- `GenericSourceSet` — модель источников/outputs для конкретного имени.	17	current build and local Ivy publication instructions.
114	- `VariantsPlugin` — регистрирует extension `variants` и lifecycle finalize.
115	- `BuildVariantsExtension` — корневой API модели вариантов.
116	- `BuildVariant` — API ролей, attributes и artifact slots варианта.
117	- `VariantsSourcesPlugin` — применяет `variants` + `sources` и запускает адаптер.
118	- `VariantSourcesExtension` — API bind/events registration.
119	- `LayerBindingSpec` — слой-конкретный DSL для policy/configuration source set.
120	- `SourceSetRegistration` — payload `whenRegistered(...)`.
121	- `SourceSetUsageBinding` — payload `whenBound(...)`.
122		18
123	## NOTES
124
125	- Marker ids:
126	- `org.implab.gradle-variants`
127	- `org.implab.gradle-variants-sources`
128	- `SourcesPlugin` пока class-only (без marker id).
129
130	## SEE ALSO
131
132	- `sources-plugin.md`
133	- `variants-plugin.md`
134	- `variant-sources-plugin.md`

common/sources-plugin.md +4 -80

@@ -1,83 +1,7
1	# Sources Plugin	1	# Moved: Sources Plugin
2
3	## NAME
4
5	`SourcesPlugin` и extension `sources`.
6
7	## SYNOPSIS
8
9	```groovy
10	// Обычно подключается транзитивно через org.implab.gradle-variants-sources
11
12	sources {
13	register('main') {
14	declareOutputs('compiled', 'typings')
15
16	sets {
17	ts { srcDir 'src/main/ts' }
18	js { srcDir 'src/main/js' }
19	}
20	}
21	}
22	```
23
24	## DESCRIPTION
25
26	`SourcesPlugin` регистрирует extension `sources` типа
27	`NamedDomainObjectContainer<GenericSourceSet>`.
28
29	`GenericSourceSet` — это автономный source bundle с четким контрактом outputs.
30
31	### sourceSetDir
32
33	Базовый каталог набора. Конвенция по умолчанию: `src/<name>`.
34
35	### outputsDir
36
37	Базовый каталог результатов набора. Конвенция по умолчанию: `build/<name>`.
38
39	### sets
40		2
41	Контейнер `SourceDirectorySet` внутри `GenericSourceSet`. Используется для	3	The `SourcesPlugin` implementation is now part of the `variants` module, not
42	логического разделения подпапок (например `ts`, `js`, `typings`).	4	the `common` module.
43
44	### outputs contract
45
46	Outputs именованные и должны быть объявлены заранее:
47
48	- `declareOutputs(...)` — декларация доступных output keys;
49	- `output(name)` — доступ к `ConfigurableFileCollection` для output key;
50	- `registerOutput(...)` — регистрация output из файлов или task provider.
51
52	Такой контракт упрощает wiring задач через inputs/outputs без ручного
53	`dependsOn`.
54
55	## API
56
57	### SourcesPlugin
58
59	- `apply(Project)` — добавляет extension `sources` в проект.
60	- `getSourcesExtension(Project)` — возвращает контейнер `GenericSourceSet`.
61		5
62	### GenericSourceSet	6	Current documentation is maintained in the root [README.md](../README.md).
63		7
64	- `getSourceSetDir()` — root directory источников набора.
65	- `getOutputsDir()` — root directory результатов набора.
66	- `getSets()` — контейнер поднаборов `SourceDirectorySet`.
67	- `declareOutputs(...)` — объявляет разрешенные output names.
68	- `output(name)` — возвращает `FileCollection` для конкретного output.
69	- `registerOutput(name, files...)` — добавляет файлы в output.
70	- `registerOutput(name, task, mapper)` — связывает output с task provider.
71	- `getAllOutputs()` — агрегированный `FileCollection` всех outputs.
72	- `getAllSourceDirectories()` — агрегированный `FileCollection` всех source dirs.
73
74	## KEY CLASSES
75
76	- `SourcesPlugin` — регистрация extension `sources`.
77	- `GenericSourceSet` — модель источников и outputs.
78
79	## NOTES
80
81	- Обращение к `output(name)` без предварительного `declareOutputs(name)`
82	приводит к ошибке валидации.
83	- Плагин `sources` сейчас без marker id.

common/variant-artifacts-plugin.md +5 -351

@@ -1,354 +1,8
1	# Variant Artifacts Plugin	1	# Moved: Variant Artifacts Plugin
2
3	## NAME
4
5	`VariantsArtifactsPlugin` и extension `variantArtifacts`.
6
7	## SYNOPSIS
8
9	```groovy
10	import org.gradle.api.attributes.Attribute
11
12	plugins {
13	id 'org.implab.gradle-variants-artifacts'
14	}
15
16	def variantAttr = Attribute.of('test.variant', String)
17	def slotAttr = Attribute.of('test.slot', String)
18
19	variants {
20	layer('main')
21
22	variant('browser') {
23	role('main') { layers('main') }
24	}
25	}
26
27	variantSources {
28	bind('main') {
29	configureSourceSet {
30	declareOutputs('types', 'js', 'resources')
31	}
32	}
33	}
34
35	variantArtifacts {
36	variant('browser') {
37	primarySlot('typesPackage') {
38	fromVariant {
39	output('types')
40	}
41	}
42
43	slot('js') {
44	fromVariant {
45	output('js')
46	}
47	}
48
49	slot('resources') {
50	fromVariant {
51	output('resources')
52	}
53	}
54	}
55
56	whenOutgoingVariant { publication ->
57	publication.configureConfiguration {
58	attributes.attribute(variantAttr, publication.variantName())
59	}
60
61	publication.primarySlot().configureArtifactAttributes {
62	attribute(slotAttr, publication.primarySlot().slotName())
63	}
64
65	publication.requireSlot('js').configureArtifactAttributes {
66	attribute(slotAttr, 'js')
67	}
68
69	publication.requireSlot('resources').configureArtifactAttributes {
70	attribute(slotAttr, 'resources')
71	}
72	}
73	}
74	```
75
76	## DESCRIPTION
77
78	`VariantsArtifactsPlugin` применяет `VariantsSourcesPlugin`, затем строит
79	outgoing publication model поверх `variantSources`.
80
81	### publication model
82
83	Для каждого `variantArtifacts.variant('<name>')` публикуется один outgoing
84	build variant:
85
86	- primary configuration `<variant>Elements`;
87	- primary artifact slot на самой configuration;
88	- secondary variants внутри `configuration.outgoing.variants` для остальных slots.
89
90	Пример:
91
92	- `browserElements`
93	- primary slot: `typesPackage`
94	- secondary variants: `js`, `resources`
95
96	Это разделяет:
97
98	- graph selection build variant-а;
99	- artifact selection внутри уже выбранного variant-а.
100
101	### slot contributions и DSL
102
103	`slot('<name>')` описывает artifact representation не как один файл или одну
104	задачу, а как набор contributions, которые потом materialize-ятся в отдельный
105	`ArtifactAssembly`.
106
107	Текущий DSL поддерживает два вида contributions:
108
109	- topology-aware:
110	- `fromVariant { output(...) }`
111	- `fromRole('<role>') { output(...) }`
112	- `fromLayer('<layer>') { output(...) }`
113	- direct:
114	- `from(someFileOrProviderOrTaskOutput)`
115
116	Смысл DSL по слоям:
117
118	- `fromVariant/fromRole/fromLayer` выбирают область topology model, в которой
119	contribution активен;
120	- `output(...)` выбирает named output соответствующего `GenericSourceSet`;
121	- `from(Object)` добавляет direct contribution, не зависящий от
122	`variantSources` bindings;
123	- итоговый contribution при materialization:
124	- проверяет, подходит ли текущий `SourceSetUsageBinding`;
125	- выдает object для `files.from(...)`;
126	- при необходимости выдает `BindingKey`, если такой contribution должен
127	схлопываться по logical identity.
128
129	Связь slot-а с остальной моделью:
130
131	- `variants` задает topology variant/role/layer;
132	- `variantSources` превращает topology в concrete `SourceSetUsageBinding`;
133	- `variantArtifacts.slot(...)` описывает, какие bindings надо включить в slot;
134	- `VariantArtifactsResolver` превращает contributions slot-а в `FileCollection`;
135	- `VariantArtifactsPlugin` регистрирует для slot-а отдельный `ArtifactAssembly`;
136	- `OutgoingVariantPublication` и `OutgoingArtifactSlotPublication` публикуют
137	уже собранные slot artifacts наружу.
138
139	Каждый slot materialize-ится в отдельный `ArtifactAssembly`:
140
141	- task: `process<Variant><Slot>`;
142	- output dir: `build/variant-artifacts/<variant>/<slot>`.
143
144	### primary slot
145
146	Primary slot задает artifact, который публикуется как основной artifact
147	configuration `<variant>Elements`.
148
149	Формы DSL:
150
151	```groovy
152	variant('browser') {
153	primarySlot('typesPackage')
154
155	slot('typesPackage') {
156	fromVariant { output('types') }
157	}
158	}
159	```
160
161	или sugar:
162
163	```groovy
164	variant('browser') {
165	primarySlot('typesPackage') {
166	fromVariant { output('types') }
167	}
168	}
169	```
170
171	Правила:
172
173	- если slot один, он считается primary неявно;
174	- если slots несколько, `primarySlot(...)` обязателен;
175	- `primarySlot` должен ссылаться на существующий slot.
176		2
177	## LIFECYCLE	3	The `VariantArtifactsPlugin` implementation is now part of the `variants`
178		4	module, not the `common` module.
179	- `VariantsArtifactsPlugin` ждет `variants.whenFinalized(...)`;
180	- после этого валидирует `variantArtifacts`;
181	- регистрирует `ArtifactAssembly` по каждому slot;
182	- materialize-ит outgoing publications;
183	- вызывает `whenOutgoingVariant(...)`;
184	- callbacks replayable.
185
186	После finalize мутации `variantArtifacts` запрещены.
187
188	## EVENTS
189
190	### whenOutgoingVariant
191
192	Replayable callback на готовую outgoing publication variant-а.
193
194	Подходит для:
195
196	- настройки общих attributes build variant-а один раз;
197	- настройки per-slot artifact attributes;
198	- доконфигурации `ArtifactAssembly`.
199
200	## PAYLOAD TYPES
201
202	### OutgoingVariantPublication
203
204	Содержит:
205
206	- `variantName()`;
207	- `topologyVariant()`;
208	- `variantArtifact()`;
209	- `configuration()` — primary `<variant>Elements`;
210	- `primarySlot()`;
211	- `slots()` — все slot publications;
212	- `secondarySlots()`;
213	- `findSlot(name)`, `requireSlot(name)`.
214
215	Sugar:
216
217	- `configureConfiguration(Action\|Closure)`.
218
219	### OutgoingArtifactSlotPublication
220
221	Содержит:
222
223	- `slotName()`;
224	- `primary()`;
225	- `slot()` — модель `VariantArtifactSlot`;
226	- `assembly()`.
227
228	Sugar:
229
230	- `configureAssembly(Action\|Closure)`;
231	- `configureArtifactAttributes(Action\|Closure)`.
232
233	`configureArtifactAttributes(...)` пишет attributes:
234
235	- в `Configuration.attributes` для primary slot;
236	- в `ConfigurationVariant.attributes` для secondary slot.
237
238	## CONSUMER SIDE
239
240	### primary resolution
241
242	Обычное inter-project resolution выбирает primary artifact `<variant>Elements`.
243
244	Пример:
245
246	```groovy
247	configurations {
248	compileView {
249	canBeResolved = true
250	canBeConsumed = false
251	canBeDeclared = true
252	attributes {
253	attribute(variantAttr, 'browser')
254	attribute(slotAttr, 'typesPackage')
255	}
256	}
257	}
258
259	dependencies {
260	compileView project(':producer')
261	}
262	```
263
264	### artifact selection for secondary slots
265		5
266	Secondary artifacts выбираются через `artifactView`.	6	Current documentation is maintained in the root [README.md](../README.md) and
267		7	[variant_artifacts.md](../variant_artifacts.md).
268	```groovy
269	def jsFiles = configurations.compileView.incoming.artifactView {
270	attributes {
271	attribute(slotAttr, 'js')
272	}
273	}.files
274	```
275
276	Здесь graph variant уже выбран, а `artifactView` выбирает нужный secondary
277	artifact representation.
278
279	## VALIDATION
280
281	Проверяется:
282
283	- variant существует в topology model;
284	- slot contributions не ссылаются на неизвестные role/layer;
285	- при нескольких slots указан `primarySlot`;
286	- `primarySlot` ссылается на существующий slot.
287
288	## API
289
290	### VariantArtifactsExtension
291
292	- `variant(String)` — получить/создать variant artifact model;
293	- `variant(String, Action\|Closure)` — сконфигурировать variant artifact;
294	- `getVariants()` — контейнер variant artifacts;
295	- `findVariant(name)`, `requireVariant(name)`;
296	- `whenOutgoingVariant(...)`.
297
298	### VariantArtifact
299
300	- `slot(String)` — получить/создать slot;
301	- `slot(String, Action\|Closure)` — сконфигурировать slot;
302	- `primarySlot(String)` — назначить primary slot;
303	- `primarySlot(String, Action\|Closure)` — sugar: configure slot + mark as primary;
304	- `getSlots()`;
305	- `findSlot(name)`, `requireSlot(name)`;
306	- `findPrimarySlotName()`, `requirePrimarySlotName()`;
307	- `findPrimarySlot()`, `requirePrimarySlot()`.
308
309	### VariantArtifactSlot
310		8
311	- `from(Object)`;
312	- `fromVariant(...)`;
313	- `fromRole(String, ...)`;
314	- `fromLayer(String, ...)`.
315
316	Внутренняя модель:
317
318	- slot хранит contributions, а не строковые rules;
319	- `fromVariant/fromRole/fromLayer` создают topology-aware contributions;
320	- `from(Object)` создает direct contribution, который materialize-ится даже
321	если у variant-а нет ни одного `SourceSetUsageBinding`;
322	- slot отдельно хранит topology references для validation:
323	`referencedRoleNames()` и `referencedLayerNames()`.
324
325	### OutputSelectionSpec
326
327	- `output(name)`;
328	- `output(name, extra...)`.
329
330	`OutputSelectionSpec` это внутренний DSL-buffer для одного блока
331	`fromVariant/fromRole/fromLayer`. Он локально накапливает contributions и
332	передает их в slot только после успешного завершения configure-блока.
333
334	## KEY CLASSES
335
336	- `VariantsArtifactsPlugin` — plugin adapter и materialization outgoing variants.
337	- `VariantArtifactsExtension` — root DSL и lifecycle.
338	- `VariantArtifact` — outgoing build variant model.
339	- `VariantArtifactSlot` — artifact representation slot.
340	- `VariantArtifactsResolver` — adapter между `variantSources` bindings и
341	contribution model slot-а.
342	- `OutgoingVariantPublication` — payload variant-level publication callback.
343	- `OutgoingArtifactSlotPublication` — payload per-slot publication callback.
344	- `ArtifactAssembly` — assembled files for a slot.
345
346	## NOTES
347
348	- `common` не навязывает доменную логику выбора primary slot.
349	- `common` не фиксирует значения `usage`, `libraryelements` и прочих
350	slot-specific attributes.
351	- `common` не смешивает эту модель с отдельными publish осями вроде package
352	metadata.
353	- Closure callbacks используют delegate-first; для вложенных closure удобнее
354	явный параметр (`publication -> ...`, `slotPublication -> ...`).

common/variant-sources-plugin.md +6 -156

@@ -1,159 +1,9
1	# Variant Sources Plugin	1	# Moved: Variant Sources Plugin
2
3	## NAME
4
5	`VariantsSourcesPlugin` и extension `variantSources`.
6
7	## SYNOPSIS
8
9	```groovy
10	plugins {
11	id 'org.implab.gradle-variants-sources'
12	}
13
14	variants {
15	layer('main')
16
17	variant('browser') {
18	role('main') { layers('main') }
19	}
20
21	variant('node') {
22	role('main') { layers('main') }
23	}
24	}
25
26	variantSources {
27	bind('main').sourceSetNamePattern = '{layer}'
28
29	bind('main') {
30	configureSourceSet {
31	declareOutputs('compiled')
32	}
33	}
34
35	whenRegistered { sourceSetName() }
36	whenBound('browser') { roleName() }
37	}
38	```
39		2
40	## DESCRIPTION	3	The `VariantSourcesPlugin` implementation is now part of the `variants` module,
41		4	not the `common` module.
42	`VariantsSourcesPlugin` применяет `VariantsPlugin` и `SourcesPlugin`, затем
43	регистрирует source sets из модели `variants`.
44
45	Точка запуска registration:
46
47	- `variants.whenFinalized(model -> registerSourceSets(...))`
48
49	### registration
50
51	Для каждой usage-связки `variant/role/layer` вычисляется имя source set,
52	регистрируется `GenericSourceSet` (если он еще не существует), затем
53	вызываются callbacks.
54
55	### binding
56
57	`bind('<layer>')` возвращает `LayerBindingSpec` и задает policy для этого
58	слоя:
59
60	- как именовать source set;
61	- как конфигурировать source set;
62	- какие callbacks вызвать на registration/binding.
63
64	### sourceSetNamePattern
65
66	`sourceSetNamePattern` определяет naming policy зарегистрированного source set.
67
68	Default:
69
70	- `{variant}{layerCap}`
71
72	Tokens:
73
74	- `{variant}`, `{variantCap}`
75	- `{role}`, `{roleCap}`
76	- `{layer}`, `{layerCap}`
77
78	Имя санитизируется (`[^A-Za-z0-9_.-] -> _`).
79		5
80	Ограничение:	6	Current documentation is maintained in the root [README.md](../README.md),
81		7	[variant_sources.md](../variant_sources.md), and
82	- один `sourceSetName` не может быть порожден разными слоями.	8	[variant_sources_precedence.md](../variant_sources_precedence.md).
83
84	## EVENTS
85
86	### whenRegistered
87
88	- callback на новый уникальный source set;
89	- replayable;
90	- при shared source set срабатывает один раз.
91
92	### whenBound
93
94	- callback на каждую usage-связку `variant/role/layer`;
95	- replayable;
96	- подходит для per-usage логики.
97
98	### variant filter
99
100	Фильтр по варианту поддерживает только usage-binding:
101
102	- `whenBound(String variantName, ...)`
103
104	## PAYLOAD TYPES
105
106	`SourceSetRegistration` содержит:
107
108	- `layerName`, `sourceSetName`;
109	- `sourceSet` (`NamedDomainObjectProvider<GenericSourceSet>`).
110
111	Sugar:
112
113	- `configureSourceSet(Action\|Closure)`.
114
115	`SourceSetUsageBinding` содержит:
116
117	- `variantName`, `roleName`, `layerName`, `sourceSetName`;
118	- `sourceSet` (`NamedDomainObjectProvider<GenericSourceSet>`).
119		9
120	Sugar:
121
122	- `configureSourceSet(Action\|Closure)`.
123
124	## API
125
126	### VariantSourcesExtension
127
128	- `bind(BuildLayer)` — получить/создать binding для canonical layer identity.
129	- `bind(String)` — получить/создать binding по имени слоя.
130	- `bind(String, Action\|Closure)` — сконфигурировать binding.
131	- `bind(BuildLayer, Action\|Closure)` — сконфигурировать binding по `BuildLayer`.
132	- `getBindings()` — read-only snapshot текущих bindings.
133	- `whenRegistered(...)` — глобальные callbacks регистрации source set.
134	- `whenBound(...)` — глобальные callbacks usage-binding.
135	- `whenBound(String variantName, ...)` — usage-binding callbacks с variant-filter.
136
137	### LayerBindingSpec
138
139	- `sourceSetNamePattern` — naming policy для source set слоя.
140	- `configureSourceSet(...)` — слойная конфигурация `GenericSourceSet`.
141	- `whenRegistered(...)` — callbacks регистрации в рамках слоя.
142	- `whenBound(...)` — callbacks usage-binding в рамках слоя.
143
144	## KEY CLASSES
145
146	- `VariantsSourcesPlugin` — точка входа plugin adapter.
147	- `VariantSourcesExtension` — глобальный DSL bind/events.
148	- `LayerBindingSpec` — публичный DSL-contract layer-local policy/callbacks.
149	- `SourceSetRegistration` — payload регистрации source set.
150	- `SourceSetUsageBinding` — payload usage-binding.
151
152	## NOTES
153
154	- `sourceSetNamePattern` фиксируется при первом чтении в registration
155	(`finalizeValueOnRead`).
156	- runtime state bindings скрыт внутри adapter implementation (`LayerBinding`).
157	- name-based bindings резолвятся к canonical `BuildLayer` через registry `variants`.
158	- Closure callbacks используют delegate-first.
159	- Для вложенных closure лучше явный параметр (`ctx -> ...`).

common/variants-plugin.md +5 -109

@@ -1,112 +1,8
1	# Variants Plugin	1	# Moved: Variants Plugin
2
3	## NAME
4
5	`VariantsPlugin` и extension `variants`.
6
7	## SYNOPSIS
8
9	```groovy
10	plugins {
11	id 'org.implab.gradle-variants'
12	}
13
14	variants {
15	layer('mainBase')
16	layer('mainAmd')
17
18	variant('browser') {
19	attributes {
20	string('jsRuntime', 'browser')
21	string('jsModule', 'amd')
22	}
23
24	role('main') {
25	layers('mainBase', 'mainAmd')
26	}
27
28	artifactSlot('mainCompiled')
29	}
30	}
31	```
32
33	## DESCRIPTION
34
35	`VariantsPlugin` задает доменную модель сборки и ее валидацию. Плагин не
36	регистрирует compile/copy/bundle задачи напрямую.
37
38	### layers
39
40	Глобальные логические слои. Служат единым словарем имен, на которые затем
41	ссылаются роли.
42
43	### variants
44
45	Именованные варианты исполнения/пакетирования (`browser`, `node`, и т.д.).
46	Вариант агрегирует роли, атрибуты и artifact slots.
47
48	### roles
49
50	Роль описывает набор слоев в пределах варианта (`main`, `test`, `tools`).
51	Одна роль может ссылаться на несколько слоев.
52
53	### attributes
54		2
55	Typed-атрибуты (`Attribute<T> -> Provider<T>`) для передачи параметров в	3	The `VariantsPlugin` implementation is now part of the `variants` module, not
56	адаптеры и публикацию артефактов.	4	the `common` module.
57
58	### artifact slots
59
60	Именованные слоты ожидаемых артефактов варианта. Используются как контракт
61	между моделью варианта и плагинами, создающими/публикующими результаты.
62
63	## VALIDATION
64
65	В `finalizeModel()` выполняется проверка:
66
67	- роль не может ссылаться на неизвестный layer;
68	- пустые имена layer запрещены;
69	- имена ролей в варианте должны быть уникальны;
70	- имена artifact slots в варианте должны быть уникальны.
71
72	## LIFECYCLE
73
74	- `VariantsPlugin` вызывает `variants.finalizeModel()` на `afterEvaluate`.
75	- после `finalizeModel()` мутации модели запрещены.
76	- `whenFinalized(...)` replayable.
77
78	## API
79
80	### BuildVariantsExtension
81		5
82	- `layer(...)` — объявление или конфигурация `BuildLayer`.	6	Current documentation is maintained in the root [README.md](../README.md) and
83	- `variant(...)` — объявление или конфигурация `BuildVariant`.	7	the design notes in [variant_sources.md](../variant_sources.md).
84	- `layers { layer(...) }`, `variants { ... }` — grouped DSL без публикации container API наружу.
85	- `all(...)` — callback для всех вариантов.
86	- `findLayer(name)`, `requireLayer(name)`, `getAllLayers()` — доступ к registry слоев.
87	- `getAll()`, `find(name)`, `require(name)` — доступ к вариантам.
88	- `validate()` — явный запуск валидации.
89	- `finalizeModel()` — валидация + финализация модели.
90	- `whenFinalized(...)` — callback по завершенной модели (replayable).
91
92	### BuildVariant
93
94	- `attributes { ... }` — атрибуты варианта (+ sugar `string/bool/integer`).
95	- `role(...)`, `roles { ... }` — роли варианта.
96	- `artifactSlot(...)`, `artifactSlots { ... }` — артефактные слоты.
97		8
98	## KEY CLASSES
99
100	- `VariantsPlugin` — точка входа плагина.
101	- `BuildVariantsExtension` — root extension и lifecycle.
102	- `BuildVariant` — агрегатная модель варианта.
103	- `BuildLayer` — canonical identity-model слоя.
104	- `BuildRole` — модель роли.
105	- `BuildArtifactSlot` — модель артефактного слота.
106	- `VariantAttributes` — typed wrapper для variant attributes.
107
108	## NOTES
109
110	- Модель `variants` intentionally agnostic к toolchain.
111	- Layer registry хранится как явная identity-map, а не как публичный `NamedDomainObjectContainer`.
112	- Интеграция с задачами выполняется через `variantSources` и адаптеры.

gradle.properties +1 -1

@@ -1,2 +1,2
1	group=org.implab.gradle	1	group=org.implab.gradle
2	version=1.0 No newline at end of file	2	version=0.1.0

variant_artifacts.md +5 -1

             # Variants and Variant Artifacts
+            > Design note. The current user-facing DSL and local publication workflow are
+            > documented in [README.md](README.md). Some snippets below are conceptual and
+            > describe model direction rather than exact public API.
             ## Overview
             This document describes the artifact model built on top of `variants` and
             `variantSources`.
             The goal is to define:
             - a stable artifact-facing model for outgoing contracts;
             - a DSL for declaring slots and their inputs;
             - a resolver bridge between `variantArtifacts` and `variantSources`;
             - extension points for deduplication and similar policies;
             - a model that remains live during configuration and does not require an
               artificial freeze of slot content.
             The design follows the same split already used elsewhere:
             - `variants` defines the closed domain topology;
             - `variantSources` defines source materialization semantics over that topology;
             - `variantArtifacts` defines outgoing artifact contracts over that topology.
             ---
             ## Core idea
             `variantArtifacts` is not the owner of the variant model and not the owner of
             source-set materialization.
             Its purpose is narrower:
             - decide which variants participate in outgoing publication;
             - define artifact slots for those outgoing variants;
             - declare how each slot gathers its inputs.
             This makes `variantArtifacts` an outgoing-contract layer, not a compilation or
             source-materialization layer.
             ---
             ## Model boundaries
             ### What belongs to `variants`
             - identities: `Variant`, `Role`, `Layer`;
             - normalized topology relation `(variant, role, layer)`;
             - finalization of the core domain model;
             - `VariantsView` and derived topology views.
             ### What belongs to `variantSources`
             - compile units and role projections derived from finalized `variants`;
             - source-set naming policy;
             - source-set materialization;
             - lazy access to `GenericSourceSet` providers and their named outputs.
             ### What belongs to `variantArtifacts`
             - selection of outgoing variants;
             - slot identities inside an outgoing variant;
             - slot assembly declarations;
             - root outgoing configurations for outgoing variants;
             - slot-level assembly bodies;
             - publication-facing hooks.
             ### What does not belong to `variantArtifacts`
             - ownership of variant existence;
             - ownership of source-set naming;
             - direct mutation of source materialization internals;
             - compiler- or toolchain-specific logic;
             - eager flattening of source inputs into files during DSL declaration.
             ---
             ## Outgoing subset
             Not every declared `Variant` must become outgoing.
             `variantArtifacts` defines an outgoing subset of variants.
             For each outgoing variant there is one root outgoing aggregate:
             - one root consumable `Configuration`;
             - one or more artifact slots;
             - one primary slot;
             - optional secondary slots.
             This is why `OutgoingConfiguration` is a real model object and not merely a
             publication event payload.
             It represents a live build-facing aggregate:
             - it has its own attributes;
             - it is visible to other build logic as soon as registered;
             - it contains lazy handles rather than eagerly materialized state;
             - it is distinct from slot assembly state.
             ---
             ## Identity-first split
             The artifact model should preserve the same identity-first principle used for
             the rest of the project.
             ### Identity objects
             - `Variant`
             - `Slot`
             - `ArtifactSlot = (variant, slot)`
             These objects are:
             - cheap;
             - replayable;
             - suitable for discovery and selection.
             ### Stateful objects
             - `OutgoingConfiguration`
             - `ArtifactAssembly`
             These objects are:
             - build-facing;
             - allowed to contain Gradle lazy handles;
             - obtained through dedicated APIs rather than embedded into identity objects.
             ### Rule of thumb
             - slot identity is cheap and replayable;
             - inside one `OutgoingConfiguration`, `Slot` is the natural local identity;
             - `ArtifactSlot` is useful when slot identity must be referenced outside the
               parent outgoing configuration;
             - slot body is stateful and resolved separately;
             - outgoing configuration is a live aggregate, not a mere snapshot.
             ---
             ## Artifact model
             Conceptually:
             ```java
             interface VariantArtifactsContext {
                 VariantsView getVariants();
                 void all(Action<? super OutgoingConfiguration> action);
                 Optional<OutgoingConfiguration> findArtifacts(Variant variant);
                 OutgoingConfiguration requireArtifacts(Variant variant);
                 ArtifactAssemblies getAssemblies();
             }
             ```
             ```java
             interface OutgoingConfiguration {
                 Variant getVariant();
                 NamedDomainObjectProvider<Configuration> getOutgoingConfiguration();
                 NamedDomainObjectContainer<Slot> getSlots();
                 Property<Slot> getPrimarySlot();
             }
             ```
             ```java
             interface ArtifactAssemblies {
                 ArtifactAssembly resolveSlot(ArtifactSlot slot);
             }
             ```
             This intentionally uses a Gradle-style local slot container rather than a
             separate `ArtifactSlotsView`.
             The reason is simple:
             - inside one `OutgoingConfiguration`, slot identity is local and naturally
               expressed as `Slot`;
             - a dedicated `ArtifactSlotsView` would suggest a detached readonly projection
               without clearly owning mutation/configuration semantics;
             - `NamedDomainObjectContainer<Slot>` better matches the live configuration model
               and keeps the parent aggregate as the owner of slot structure.
             `ArtifactSlot` remains useful, but only as a fully qualified identity outside
             the parent aggregate:
             - resolver APIs;
             - global payloads;
             - cross-variant references.
             Important distinction:
             - `OutgoingConfiguration` describes outgoing publication structure;
             - `ArtifactAssembly` describes how one slot artifact is assembled.
             An `ArtifactAssembly` does not create the root outgoing configuration. It serves
             one already declared slot inside that configuration.
             ### Primary slot ownership
             Primary status belongs to the parent outgoing configuration, not to the slot
             itself.
             This is why the preferred container-level contract is:
             ```java
             Property<Slot> getPrimarySlot();
             ```
             and not a slot-local boolean or a derived `ArtifactSlot` reference.
             Reasons:
             - the primary role is assigned by the parent aggregate;
             - within one `OutgoingConfiguration`, the variant identity is already known, so
               `Slot` is sufficient and avoids redundant `(variant, slot)` duplication;
             - `Property` matches the rest of the Gradle-facing live model better than a
               custom `findPrimarySlot()` style API;
             - `Property` gives useful write/configure/finalize semantics without inventing a
               separate special lifecycle abstraction.
             Expected usage:
             - DSL or adapters may assign the primary slot through `set(...)`;
             - adapters that want to provide a default may use `convention(...)`;
             - the property may remain unset while the model is still incomplete;
             - at materialization time the property may be finalized;
             - if more than one slot exists and `primarySlot` is still unset at the
               materialization point, that is a model error.
             The model should still enforce that the selected primary slot belongs to the
             same `OutgoingConfiguration`.
             ### Proposed public shape
             With these constraints, the preferred public structure is:
             ```java
             interface VariantArtifactsContext {
                 VariantsView getVariants();
                 void all(Action<? super OutgoingConfiguration> action);
                 Optional<OutgoingConfiguration> findArtifacts(Variant variant);
                 OutgoingConfiguration requireArtifacts(Variant variant);
                 ArtifactAssemblies getAssemblies();
             }
             interface OutgoingConfiguration {
                 Variant getVariant();
                 NamedDomainObjectProvider<Configuration> getOutgoingConfiguration();
                 NamedDomainObjectContainer<Slot> getSlots();
                 Property<Slot> getPrimarySlot();
             }
             interface ArtifactAssemblies {
                 ArtifactAssembly resolveSlot(ArtifactSlot slot);
             }
             record ArtifactSlot(Variant variant, Slot slot) {}
             ```
             This gives:
             - one global registry of outgoing variants;
             - one local slot container per outgoing variant;
             - one fully qualified slot identity for resolver and cross-aggregate use;
             - one explicit service for slot assembly materialization.
             ### Minimal internal shape
             The preferred minimal internal structure is:
             ```java
             final class VariantArtifactsRegistry implements VariantArtifactsContext {
                 OutgoingConfiguration outgoingConfiguration(Variant variant);
                 ArtifactAssemblyRules slotRules(ArtifactSlot slot);
                 ArtifactAssemblies assemblies();
             }
             interface ArtifactAssemblyRules {
                 void from(Object input);
                 void fromVariant(Action<? super OutputSelectionSpec> action);
                 void fromRole(String roleName, Action<? super OutputSelectionSpec> action);
                 void fromLayer(String layerName, Action<? super OutputSelectionSpec> action);
             }
             ```
             Responsibility split:
             - `VariantArtifactsRegistry` owns the whole artifact model;
             - `OutgoingConfiguration` owns only the structural variant-local aggregate;
             - `ArtifactAssemblyRules` owns the content declaration of one slot;
             - `ArtifactAssemblies` materializes `ArtifactAssembly` from
               `ArtifactSlot -> ArtifactAssemblyRules`.
             This keeps `OutgoingConfiguration` focused on structure and avoids overloading it
             with slot-content APIs such as `rules(slot)`.
             ### DSL binding
             The DSL should be connected through the registry, not by making
             `OutgoingConfiguration` responsible for content rules.
             Conceptually:
             ```java
             variantArtifacts.variant("browser", spec -> {
                 spec.slot("runtime", assembly -> {
                     assembly.fromRole("production", out -> out.output("js"));
                 });
             });
             ```
             Operationally this means:
 . registry creates or returns `OutgoingConfiguration` for the variant;
 . slot declaration creates or returns `Slot` inside that outgoing configuration;
 . registry forms `ArtifactSlot(variant, slot)`;
 . registry resolves `slotRules(artifactSlot)`;
 . bound `ArtifactAssemblySpec` writes into those rules.
             So the DSL writes:
             - structure into `OutgoingConfiguration`;
             - slot content into registry-owned `ArtifactAssemblyRules`.
             This is the intended bridge point between the public DSL and the internal
             resolver/materialization model.
             ---
             ## Live model and monotonic structure
             `variantArtifacts` should be treated as a live configuration model during the
             whole configuration phase.
             This means:
             - slot inputs remain live;
             - `from(...)`, `fromVariant(...)`, `fromRole(...)`, `fromLayer(...)` may keep
               contributing inputs until task execution;
             - `ArtifactAssembly` may expose live `FileCollection`, `Provider`, and task
               wiring;
             - external task outputs remain outside the control of this model and must be
               accepted as live inputs.
             The model should therefore avoid a mandatory freeze phase for slot content.
             Instead, it should follow a monotonic rule:
             - outgoing variant existence may grow;
             - slot existence may grow;
             - slot content may grow;
             - publication-visible identity should not be retroactively redefined.
             In practice this means:
             - slot names are stable once declared;
             - primary slot designation is structural;
             - slot input content remains live.
             This also means that the model does not need a dedicated freeze phase for slot
             content merely because the root outgoing configuration was registered earlier.
             Early registration of the root `Configuration` and live evolution of slot input
             content are compatible concerns.
             ---
             ## DSL principles
             The DSL should remain declarative and symbolic.
             It should describe:
             - which variant is outgoing;
             - which slots exist;
             - which slot is primary;
             - which selectors contribute inputs to each slot.
             It should not directly expose:
             - `GenericSourceSet`;
             - `FileCollection`;
             - concrete resolved files from `variantSources`;
             - internal resolver state.
             ### DSL shape
             Conceptually:
             ```groovy
             variantArtifacts {
                 variant("browser") {
                     primarySlot("runtime") {
                         fromRole("production") {
                             output("js")
                             output("resources")
                         }
                     }
                     slot("types") {
                         fromVariant {
                             output("dts")
                         }
                     }
                     slot("sources") {
                         fromLayer("main") {
                             output("sources")
                         }
                     }
                     slot("bundleMetadata") {
                         from(someTask)
                         from(layout.buildDirectory.file("generated/meta.json"))
                     }
                 }
             }
             ```
             ### Meaning of contribution forms
             - `from(Object)` adds a direct input independent from `variantSources`;
             - `fromVariant { output(...) }` selects named outputs from all compile units of
               the current variant;
             - `fromRole(role) { output(...) }` selects named outputs from compile units that
               belong to the given role projection;
             - `fromLayer(layer) { output(...) }` selects named outputs from the compile unit
               of the current variant and the given layer, if such unit exists.
             The DSL stores declarations, not resolved file collections.
             ---
             ## Contribution model
             Internally the DSL should compile to slot contributions.
             Conceptually:
             - `DirectContribution`
             - `VariantOutputContribution`
             - `RoleOutputContribution`
             - `LayerOutputContribution`
             These contributions should remain symbolic for as long as possible.
             They should not resolve source sets or files at declaration time.
             Each contribution is expected to provide:
             - its selection scope;
             - the requested output names;
             - enough symbolic identity for later validation and resolver policies.
             ---
             ## Resolver bridge between `variantSources` and `variantArtifacts`
             This is the central integration point.
             `variantArtifacts` should not access mutable internals of `variantSources`.
             Instead, it should resolve slot inputs through the public finalized
             `VariantSourcesContext`.
             ### Bridge responsibilities
             The bridge:
             - takes slot contribution declarations;
             - expands them against finalized variant topology;
             - maps logical selectors to compile units and role projections;
             - obtains source sets lazily through `VariantSourcesContext`;
             - resolves named outputs from those source sets;
             - builds the live input model for an `ArtifactAssembly`.
             ### Bridge input
             - current outgoing variant identity;
             - slot contribution declarations;
             - `VariantSourcesContext`.
             ### Bridge output
             - a live collection of logical slot inputs;
             - later adapted to `FileCollection` or other assembly-facing input models.
             ### Resolution semantics
             For one outgoing variant:
             - `fromVariant { output(x) }`
               - expands to all `CompileUnit` of that variant;
             - `fromRole(role) { output(x) }`
               - expands to `RoleProjection(variant, role)` and then to its compile units;
             - `fromLayer(layer) { output(x) }`
               - expands to one compile unit `(variant, layer)` when it exists;
             - `from(Object)`
               - bypasses `variantSources` completely.
             After compile units are known, the bridge asks
             `ctx.getSourceSets().getSourceSet(unit)` for each selected unit and resolves the
             requested named output.
             This keeps `variantArtifacts` independent from source-set naming internals and
             other materialization details.
             ---
             ## Validation
             Validation should be structural and symbolic.
             It should validate:
             - outgoing variant refers to an existing `Variant`;
             - referenced `Role` exists in that variant projection space;
             - referenced `Layer` exists in that variant compile-unit space;
             - primary slot is defined when needed;
             - primary slot refers to a slot declared in the same outgoing configuration.
             Validation should not require eager materialization of source sets or eager
             resolution of files.
             ---
             ## Deduplication and policy extension points
             Deduplication is important, but it should not be baked into the DSL itself.
             The correct place for it is the resolver bridge, after symbolic contributions
             have been expanded to logical inputs but before they are finally adapted to
             assembly-facing file collections.
             ### Why not in the DSL
             At declaration time it is still unknown whether selectors overlap:
             - `fromVariant`
             - `fromRole`
             - `fromLayer`
             may all describe the same logical source output.
             ### Why not rely only on `FileCollection`
             `FileCollection` may still provide useful physical deduplication, but it is too
             late and too file-oriented to serve as the only semantic mechanism.
             The artifact model should first deduplicate logical inputs, then let Gradle
             perform any additional physical deduplication.
             ### Default expectation
             The default resolver should support:
             - deduplication of topology-aware inputs by logical identity;
             - no implicit deduplication of direct `from(Object)` inputs.
             Logical identity should be based on domain meaning, for example:
             - `(CompileUnit, outputName)`
             and not on projected source-set names.
             This is important because source-set naming policy belongs to `variantSources`
             and must not silently redefine artifact semantics.
             ### Extension points
             The model should provide explicit internal extension points for:
             - deduplication policy;
             - logical input identity;
             - adaptation of resolved logical inputs to assembly-facing objects.
             Conceptually:
             ```java
             interface SlotInputDedupPolicy { ... }
             interface LogicalSlotInputIdentity { ... }
             interface SlotInputAdapter { ... }
             ```
             The default implementation may remain simple, but these seams should exist from
             the start.
             ---
             ## Publication hooks
             Publication hooks remain useful, but they should observe the live structural
             model rather than define it.
             Examples:
-            - `whenOutgoingVariant(...)`
+            - `whenOutgoingConfiguration(...)`
             - `whenOutgoingSlot(...)`
             These hooks are adapter-facing customization points over already declared
             outgoing structure:
             - root configuration attributes;
             - slot artifact attributes;
             - assembly task tweaks.
             The recommended way to connect publication-facing `Spec` objects to the
             structural model is by backlink, not by moving slot rules into publication
             types.
             Conceptually:
             ```java
             interface OutgoingConfigurationSpec {
                 OutgoingConfiguration getOutgoingArtifacts();
                 Variant getVariant();
                 Configuration getConfiguration();
             }
             interface OutgoingArtifactSlotSpec {
                 ArtifactSlot getArtifactSlot();
                 ArtifactAssembly getAssembly();
                 boolean isPrimary();
             }
             ```
             In this arrangement:
             - `OutgoingConfigurationSpec` remains a publication-facing facade;
             - `OutgoingConfigurationSpec` may expose the structural aggregate when an
               adapter needs it;
             - slot rules still belong to `VariantArtifactsRegistry`;
             - publication specs do not become owners of declaration or resolver state.
             They should not become the primary structural API for the artifact model.
             This is why a separate phase-oriented `OutgoingPublicationsContext` is not
             required.
             The live `OutgoingConfiguration` aggregate is sufficient.
             ---
             ## Design principles
             ### 1. Keep topology ownership in `variants`
             `variantArtifacts` selects from the topology model. It does not own it.
             ### 2. Keep source ownership in `variantSources`
             `variantArtifacts` consumes source materialization through a resolver bridge. It
             does not own source-set semantics.
             ### 3. Keep the DSL symbolic
             The DSL declares intent and selection rules, not materialized files.
             ### 4. Keep slot content live
             Do not introduce an artificial finalize phase for slot content unless a real
             semantic need appears.
             ### 5. Fix only structural identity
             Slot name, primary designation, and outgoing shape are structural. Slot inputs
             remain live.
             ### 6. Resolve through dedicated bridges
             Cross-model integration belongs in a resolver service, not in DSL classes.
             ### 7. Add policy seams early
             Deduplication and similar concerns should have extension points from the start,
             even if the initial implementation is conservative.
             ---
             ## Summary
             `variantArtifacts` should be modeled as a live outgoing-contract layer over
             `variants`, with source input resolution delegated to a dedicated bridge over
             `variantSources`.
             The resulting shape is:
             - `variants` owns topology;
             - `variantSources` owns source materialization;
             - `variantArtifacts` owns outgoing contract structure;
             - a resolver bridge connects symbolic slot declarations to live source-derived
               inputs;
             - deduplication and similar concerns are policies of that bridge, not of the
               DSL itself;
             - slot content stays live during configuration;
             - only publication-visible structure is treated as stable identity.

variant_sources.md +7 -2

             # Variants and Variant Sources
+            > Design note. The current user-facing DSL and local publication workflow are
+            > documented in [README.md](README.md). Some snippets below are conceptual and
+            > describe model direction rather than exact public API.
             ## 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`
             * `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(...)`
+            * selector rules here mean `configureEach(...)`, `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
+            configureEach < 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`
             * `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();
                 SourceSetMaterializer getSourceSets();
             }
             ```
             This callback is also replayable.
             Example:
             ```java
             variantSources.whenFinalized(ctx -> {
                 var units = ctx.getCompileUnits();
                 var roles = ctx.getRoleProjections();
                 var sourceSets = ctx.getSourceSets();
             });
             ```
             ---
             ## `SourceSetMaterializer`
             ### Purpose
             `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 SourceSetMaterializer {
                 NamedDomainObjectProvider<GenericSourceSet> getSourceSet(CompileUnit unit);
             }
             ```
             ---
             ## 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
             * `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.

variant_sources_precedence.md +62 -17

             # `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:
+            Four selectors are available:
+            - `configureEach(...)`
             - `variant(...)`
             - `layer(...)`
             - `unit(...)`
             They all target the same set of compile units, but at different levels of specificity.
+            ### `configureEach(...)`
+            `configureEach(...)` applies configuration to every materialized compile-unit
+            source set.
+            Example:
+            ```groovy
+            variantSources {
+                configureEach {
+                    sourceSet {
+                        declareOutputs("js")
+                    }
+                }
+            }
+            ```
+            Use this selector for global source-set conventions.
+            ---
             ### `variant(...)`
             `variant(...)` applies configuration to all compile units that belong to the given variant.
             Example:
             ```groovy
             variantSources {
                 variant("browser") {
+                    sourceSet {
                         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") {
+                    sourceSet {
+                        sets.create("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") {
+                    sourceSet {
+                        sets.create("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
+            configureEach < variant < layer < unit
             ```
             This means:
-. `variant(...)` actions are applied first
+. `configureEach(...)` actions are applied first
-. `layer(...)` actions are applied next
+. `variant(...)` actions are applied next
-. `unit(...)` actions are applied last
+. `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(...)`
+            - selector rules here mean `configureEach(...)`, `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`
+              actual registration order, not in reconstructed
-              order
+              `configureEach < 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(...)`
+            - policy selection must happen before `variantSources.whenAvailable(...)`
               becomes observable
             - compile-unit names are projected and validated before queued
-              `whenFinalized(...)` callbacks are replayed
+              `whenAvailable(...)` callbacks are replayed
-            - changing naming policy from inside a `whenFinalized(...)` callback is too late
+            - changing naming policy from inside a `whenAvailable(...)` callback is too late
             ---
             ## Example
             ```groovy
             variantSources {
+                configureEach {
+                    sourceSet {
+                        declareOutputs("js", "dts")
+                    }
+                }
                 variant("browser") {
-                    declareOutputs("js", "dts")
+                    sourceSet {
+                        registerOutput("js", layout.projectDirectory.file("inputs/browser.js"))
+                    }
                 }
                 layer("main") {
-                    set("ts") {
+                    sourceSet {
+                        sets.create("ts") {
                             srcDir("src/main/ts")
                         }
                     }
+                }
                 unit("browser", "main") {
-                    set("resources") {
+                    sourceSet {
+                        sets.create("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")`
+            The global `configureEach(...)` selector is applied before the listed
+            variant/layer/unit selectors for every compile unit.
             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
+            configureEach < 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/build.gradle +7 -3

             plugins {
                 id "java-library"
                 id "ivy-publish"
             }
+            description = "Variant, source-set, and outgoing artifact model plugins for Gradle builds"
             java {
                 withJavadocJar()
                 withSourcesJar()
                 toolchain {
                     languageVersion = JavaLanguageVersion.of(21)
                 }
             }
             dependencies {
                 compileOnly libs.jdt.annotations
                 api gradleApi(),
-                    libs.bundles.jackson
+                    project(":common")
-                implementation project(":common")
                 testImplementation gradleTestKit()
                 testImplementation "org.junit.jupiter:junit-jupiter-api:5.11.4"
                 testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:5.11.4"
                 testRuntimeOnly "org.junit.platform:junit-platform-launcher:1.11.4"
             }
             task printVersion{
                 doLast {
                     println "project: $project.group:$project.name:$project.version"
                     println "jar: ${->jar.archiveFileName.get()}"
                 }
             }
             test {
                 useJUnitPlatform()
             }
             javadoc {
                 exclude "**/internal/**"
             }
             publishing {
                 repositories {
                     ivy {
                         url "${System.properties["user.home"]}/ivy-repo"
                     }
                 }
                 publications {
                     ivy(IvyPublication) {
                         from components.java
                         descriptor.description {
                             text = providers.provider({ description })
                         }
+                        descriptor.license {
+                            name = "BSD-2-Clause"
+                            url = "https://spdx.org/licenses/BSD-2-Clause.html"
                         }
                     }
                 }
+            }

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