# Gradle Common Sources Model

## NAME

`gradle-common/common` — набор плагинов для моделирования вариантов сборки,
регистрации source sets и интеграции этой модели с toolchain-адаптерами.

## SYNOPSIS

```groovy
plugins {
    id 'org.implab.gradle-variants-sources'
}

variants {
    layer('mainBase')
    layer('mainAmd')

    variant('browser') {
        role('main') { layers('mainBase', 'mainAmd') }
    }
}

variantSources {
    bind('mainBase') {
        configureSourceSet {
            declareOutputs('compiled')
        }
    }

    bind('mainAmd').sourceSetNamePattern = '{variant}{layerCap}'

    whenRegistered { sourceSetName() }

    whenBound { ctx ->
        ctx.configureSourceSet {
            declareOutputs('typings')
        }
    }
}
```

## DESCRIPTION

Модуль состоит из трех логических частей:

- `variants` — декларативная доменная модель сборки;
- `sources` — модель физически регистрируемых source sets;
- `variantSources` — адаптер, который связывает первые две модели.

Ниже раскрытие каждой части.

### variants

`variants` задает структуру пространства сборки: какие есть слои, какие роли
используют эти слои в каждом варианте, какие есть атрибуты и artifact slots.
Модель не создает задачи и не привязана к TS/JS.

Практический смысл:

- формализовать архитектуру сборки;
- дать адаптерам единый источник правды.

### sources

`sources` описывает независимые source sets (`GenericSourceSet`) с именованными
outputs. Это уже "физический" уровень, к которому удобно привязывать задачи,
артефакты и task inputs/outputs.

Практический смысл:

- создать единый контракт по входам/выходам;
- регистрировать результаты задач как outputs source set;
- минимизировать ручные `dependsOn` за счет модели outputs.

### variantSources

`variantSources` регистрирует source sets на основе `variants`, применяет
конфигурацию layer-bindings и отдает события (`whenRegistered`, `whenBound`) для
адаптеров других плагинов.

Практический смысл:

- переводить логическую модель `variants` в executable-модель `sources`;
- навешивать политики toolchain на зарегистрированные source sets;
- синхронизировать плагины через replayable callback-контракт.

## DOMAIN MODEL

- `BuildLayer` — глобальный идентификатор слоя.
- `BuildVariant` — агрегат ролей, атрибутов, артефактных слотов.
- `BuildRole` — роль внутри варианта, содержит ссылки на layer names.
- `GenericSourceSet` — зарегистрированный набор исходников и outputs.
- `BuildLayerBinding` — правила registration source set для конкретного layer.
- `SourceSetRegistration` — payload события регистрации source set.
- `SourceSetUsageBinding` — payload события usage-binding.

## EVENT CONTRACT

- `whenRegistered`:
  - событие нового уникального source set name;
  - replayable.
- `whenBound`:
  - событие каждой usage-связки `variant/role/layer`;
  - replayable.

Closure callbacks работают в delegate-first режиме (`@DelegatesTo`). Для
вложенных closure рекомендуется явный параметр (`ctx -> ...`).

## KEY CLASSES

- `SourcesPlugin` — регистрирует extension `sources`.
- `GenericSourceSet` — модель источников/outputs для конкретного имени.
- `VariantsPlugin` — регистрирует extension `variants` и lifecycle finalize.
- `BuildVariantsExtension` — корневой API модели вариантов.
- `BuildVariant` — API ролей, attributes и artifact slots варианта.
- `VariantsSourcesPlugin` — применяет `variants` + `sources` и запускает адаптер.
- `VariantSourcesExtension` — API bind/events registration.
- `BuildLayerBinding` — слой-конкретный DSL для имени и конфигурации source set.
- `SourceSetRegistration` — payload `whenRegistered(...)`.
- `SourceSetUsageBinding` — payload `whenBound(...)`.

## NOTES

- Marker ids:
  - `org.implab.gradle-variants`
  - `org.implab.gradle-variants-sources`
- `SourcesPlugin` пока class-only (без marker id).

## SEE ALSO

- `sources-plugin.md`
- `variants-plugin.md`
- `variant-sources-plugin.md`