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~~
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}'
	1	# Gradle Common
32	2
33		whenRegistered { sourceSetName() }
34
35		whenBound { ctx ->
36		ctx.configureSourceSet {
37		declareOutputs('typings')
38		}
39		}
40		}
41		```
42
43		## DESCRIPTION
44
45		Модуль состоит из трех логических частей:
	3	`common` is the shared utility module used by the Gradle plugins in this
	4	repository.
46	5
47		- `variants` — декларативная доменная модель сборки;
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
	6	It contains:
65	7
66		`sources` описывает независимые source sets (`GenericSourceSet`) с именованными
67		outputs. Это уже "физический" уровень, к которому удобно привязывать задачи,
68		артефакты и task inputs/outputs.
69
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
	8	- core Gradle helper utilities
	9	- small language/value helpers
	10	- shell execution helpers
	11	- JSON DSL and JSON-writing task support
99	12
100		- `whenRegistered`:
101		- событие нового уникального source set name;
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
	13	It no longer contains the variant/source/artifact plugin model. Those plugins
	14	live in the `variants` module.
111	15
112		- `SourcesPlugin` — регистрирует extension `sources`.
113		- `GenericSourceSet` — модель источников/outputs для конкретного имени.
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(...)`.
	16	See the root [README.md](../README.md) and [PUBLISHING.md](../PUBLISHING.md) for
	17	current build and local Ivy publication instructions.
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
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
	1	# Moved: Sources Plugin
40	2
41		Контейнер `SourceDirectorySet` внутри `GenericSourceSet`. Используется для
42		логического разделения подпапок (например `ts`, `js`, `typings`).
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`.
	3	The `SourcesPlugin` implementation is now part of the `variants` module, not
	4	the `common` module.
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
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.
	1	# Moved: Variant Artifacts Plugin
176	2
177		## LIFECYCLE
178
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
	3	The `VariantArtifactsPlugin` implementation is now part of the `variants`
	4	module, not the `common` module.
265	5
266		Secondary artifacts выбираются через `artifactView`.
267
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
	6	Current documentation is maintained in the root [README.md](../README.md) and
	7	[variant_artifacts.md](../variant_artifacts.md).
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
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		```
	1	# Moved: Variant Sources Plugin
39	2
40		## DESCRIPTION
41
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_.-] -> _`).
	3	The `VariantSourcesPlugin` implementation is now part of the `variants` module,
	4	not the `common` module.
79	5
80		Ограничение:
81
82		- один `sourceSetName` не может быть порожден разными слоями.
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>`).
	6	Current documentation is maintained in the root [README.md](../README.md),
	7	[variant_sources.md](../variant_sources.md), and
	8	[variant_sources_precedence.md](../variant_sources_precedence.md).
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
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
	1	# Moved: Variants Plugin
54	2
55		Typed-атрибуты (`Attribute<T> -> Provider<T>`) для передачи параметров в
56		адаптеры и публикацию артефактов.
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
	3	The `VariantsPlugin` implementation is now part of the `variants` module, not
	4	the `common` module.
81	5
82		- `layer(...)` — объявление или конфигурация `BuildLayer`.
83		- `variant(...)` — объявление или конфигурация `BuildVariant`.
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 { ... }` — артефактные слоты.
	6	Current documentation is maintained in the root [README.md](../README.md) and
	7	the design notes in [variant_sources.md](../variant_sources.md).
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	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 +67 -22

              # `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") {
-                     declareOutputs("js", "dts")
+                     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") {
-                         srcDir("src/main/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") {
-                         srcDir("src/browserMain/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
-. `layer(...)` actions are applied next
-. `unit(...)` actions are applied last
+. `configureEach(...)` actions are applied first
+. `variant(...)` actions are applied next
+. `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`
-               order
+               actual registration order, not in reconstructed
+               `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
-             - changing naming policy from inside a `whenFinalized(...)` callback is too late
+               `whenAvailable(...)` callbacks are replayed
+             - 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") {
-                         srcDir("src/main/ts")
+                     sourceSet {
+                         sets.create("ts") {
+                             srcDir("src/main/ts")
+                         }
                      }
                  }
                  unit("browser", "main") {
-                     set("resources") {
-                         srcDir("src/browserMain/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
-                 implementation project(":common")
+                     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