implab/gradle-common Commit - r29:b379fb9b52c4

variants API cleanup

cin -

r29:b379fb9b52c4 default

parent child

Context file:

r29:b379fb9b52c4

Collapse all files

AGENTS.md created 644 +12 0

@@ -0,0 +1,12
	1	# AGENTS.md
	2
	3	## Проектные договоренности
	4
	5	### Публичное API библиотек
	6
	7	- Предпочтителен `non-null` подход.
	8	- Там, где значение живет в Gradle Provider API, возвращается `Provider<T>` (не `null`).
	9	- Там, где lookup синхронный, возвращается `Optional<T>` (не `null`).
	10	- `find` рассматривается как синоним legacy `get` (поиск без `fail-fast`).
	11	- `require` это `find` + `fail-fast` с понятной ошибкой в месте вызова.
	12	- Для нового API предпочтительны формы `find/require`; новые `get*` по возможности не добавлять.

common/src/main/java/org/implab/gradle/common/sources/BuildVariant.java +27 -17

             package org.implab.gradle.common.sources;
             import java.util.ArrayList;
             import java.util.Collection;
             import java.util.Collections;
             import java.util.LinkedHashMap;
-            import java.util.LinkedHashSet;
             import java.util.List;
-            import java.util.Set;
+            import java.util.Optional;
             import javax.inject.Inject;
             import org.implab.gradle.common.core.lang.Closures;
             import org.gradle.api.Action;
             import org.gradle.api.InvalidUserDataException;
             import org.gradle.api.Named;
             import org.gradle.api.model.ObjectFactory;
             import org.gradle.api.provider.Provider;
             import org.gradle.api.provider.ProviderFactory;
             import org.gradle.api.attributes.Attribute;
             import groovy.lang.Closure;
             public abstract class BuildVariant implements Named {
                 private final String name;
                 private final ObjectFactory objects;
                 private boolean finalized;
                 /**
                  * Variant aggregate parts.
                  */
                 private final VariantAttributes attributes;
                 private final LinkedHashMap<String, BuildRole> roles = new LinkedHashMap<>();
                 private final List<LayerLink> links = new ArrayList<>();
                 private final LinkedHashMap<String, BuildArtifactSlot> artifactSlots = new LinkedHashMap<>();
                 @Inject
                 public BuildVariant(String name, ObjectFactory objects, ProviderFactory providers) {
                     this.name = name;
                     this.objects = objects;
                     attributes = new VariantAttributes(providers);
                 }
                 @Override
                 public String getName() {
                     return name;
                 }
                 /**
                  * Generic variant attributes interpreted by adapters.
                  */
                 public VariantAttributes getAttributes() {
                     return attributes;
                 }
                 public void attributes(Action<? super AttributesSpec> action) {
                     ensureMutable("configure attributes");
                     action.execute(new AttributesSpec(attributes));
                 }
                 public void attributes(Closure<?> configure) {
                     attributes(Closures.action(configure));
                 }
                 public <T> void attribute(Attribute<T> key, T value) {
                     ensureMutable("set attributes");
                     attributes.attribute(key, value);
                 }
                 public <T> void attributeProvider(Attribute<T> key, Provider<? extends T> value) {
                     ensureMutable("set attributes");
                     attributes.attributeProvider(key, value);
                 }
                 public Collection<BuildRole> getRoles() {
                     return Collections.unmodifiableCollection(roles.values());
                 }
                 public void roles(Action<? super RolesSpec> action) {
                     ensureMutable("configure roles");
                     action.execute(new RolesSpec());
                 }
                 public void roles(Closure<?> configure) {
                     roles(Closures.action(configure));
                 }
                 public BuildRole role(String name, Action<? super BuildRole> configure) {
                     ensureMutable("configure roles");
                     var role = roles.computeIfAbsent(name, this::newRole);
                     configure.execute(role);
                     return role;
                 }
                 public BuildRole role(String name, Closure<?> configure) {
                     return role(name, Closures.action(configure));
                 }
                 public BuildRole role(String name) {
                     return role(name, r -> {
                     });
                 }
-                public BuildRole getRoleByName(String name) {
+                public Optional<BuildRole> findRole(String name) {
-                    return roles.get(name);
+                    return Optional.ofNullable(roles.get(name));
+                }
+                public BuildRole requireRole(String name) {
+                    return findRole(name)
+                            .orElseThrow(() -> new InvalidUserDataException(
+                                    "Variant '" + this.name + "' doesn't define role '" + name + "'"));
                 }
                 public Collection<LayerLink> getLinks() {
                     return Collections.unmodifiableList(links);
                 }
                 public void links(Action<? super LinksSpec> action) {
                     ensureMutable("configure links");
                     action.execute(new LinksSpec());
                 }
                 public void links(Closure<?> configure) {
                     links(Closures.action(configure));
                 }
                 public LayerLink link(String from, String to, String kind) {
                     ensureMutable("add links");
                     var link = new LayerLink(
                             requireLinkValue("from", from),
                             requireLinkValue("to", to),
                             requireLinkValue("kind", kind));
                     links.add(link);
                     return link;
                 }
                 public Collection<BuildArtifactSlot> getArtifactSlots() {
                     return Collections.unmodifiableCollection(artifactSlots.values());
                 }
                 public void artifactSlots(Action<? super ArtifactSlotsSpec> action) {
                     ensureMutable("configure artifact slots");
                     action.execute(new ArtifactSlotsSpec());
                 }
                 public void artifactSlots(Closure<?> configure) {
                     artifactSlots(Closures.action(configure));
                 }
                 public BuildArtifactSlot artifactSlot(String name) {
                     return artifactSlot(name, it -> {
                     });
                 }
                 public BuildArtifactSlot artifactSlot(String name, Action<? super BuildArtifactSlot> configure) {
                     ensureMutable("configure artifact slots");
                     var slot = artifactSlots.computeIfAbsent(name, this::newArtifactSlot);
                     configure.execute(slot);
                     return slot;
                 }
                 public BuildArtifactSlot artifactSlot(String name, Closure<?> configure) {
                     return artifactSlot(name, Closures.action(configure));
                 }
-                public BuildArtifactSlot getArtifactSlotByName(String name) {
+                public Optional<BuildArtifactSlot> findArtifactSlot(String name) {
-                    return artifactSlots.get(name);
+                    return Optional.ofNullable(artifactSlots.get(name));
                 }
-                Set<String> declaredLayerNames() {
+                public BuildArtifactSlot requireArtifactSlot(String name) {
-                    var result = new LinkedHashSet<String>();
+                    return findArtifactSlot(name)
+                            .orElseThrow(() -> new InvalidUserDataException(
-                    for (var role : roles.values())
+                                    "Variant '" + this.name + "' doesn't define artifact slot '" + name + "'"));
-                        result.addAll(role.getLayers().getOrElse(java.util.List.of()));
-                    return result;
                 }
                 void finalizeModel() {
                     if (finalized)
                         return;
                     for (var role : roles.values())
                         role.finalizeModel();
                     attributes.finalizeModel();
                     finalized = true;
                 }
                 private BuildRole newRole(String roleName) {
                     return objects.newInstance(BuildRole.class, roleName);
                 }
                 private BuildArtifactSlot newArtifactSlot(String slotName) {
                     return objects.newInstance(BuildArtifactSlot.class, slotName);
                 }
                 private void ensureMutable(String operation) {
                     if (finalized)
                         throw new InvalidUserDataException("Variant '" + name + "' is finalized and cannot " + operation);
                 }
                 private static String requireLinkValue(String field, String value) {
                     if (value == null || value.trim().isEmpty())
                         throw new InvalidUserDataException("Link '" + field + "' must not be null or blank");
                     return value.trim();
                 }
                 public final class RolesSpec {
                     public BuildRole role(String name, Action<? super BuildRole> configure) {
                         return BuildVariant.this.role(name, configure);
                     }
                     public BuildRole role(String name, Closure<?> configure) {
                         return BuildVariant.this.role(name, configure);
                     }
                     public BuildRole role(String name) {
                         return BuildVariant.this.role(name);
                     }
                     public Collection<BuildRole> getAll() {
                         return BuildVariant.this.getRoles();
                     }
-                    public BuildRole getByName(String name) {
+                    public Optional<BuildRole> find(String name) {
-                        return BuildVariant.this.getRoleByName(name);
+                        return BuildVariant.this.findRole(name);
+                    }
+                    public BuildRole require(String name) {
+                        return BuildVariant.this.requireRole(name);
                     }
                 }
                 public final class LinksSpec {
                     public LayerLink link(String from, String to, String kind) {
                         return BuildVariant.this.link(from, to, kind);
                     }
                     public Collection<LayerLink> getAll() {
                         return BuildVariant.this.getLinks();
                     }
                 }
                 public final class ArtifactSlotsSpec {
                     public BuildArtifactSlot artifactSlot(String name, Action<? super BuildArtifactSlot> configure) {
                         return BuildVariant.this.artifactSlot(name, configure);
                     }
                     public BuildArtifactSlot artifactSlot(String name, Closure<?> configure) {
                         return BuildVariant.this.artifactSlot(name, configure);
                     }
                     public BuildArtifactSlot artifactSlot(String name) {
                         return BuildVariant.this.artifactSlot(name);
                     }
                     public Collection<BuildArtifactSlot> getAll() {
                         return BuildVariant.this.getArtifactSlots();
                     }
-                    public BuildArtifactSlot getByName(String name) {
+                    public Optional<BuildArtifactSlot> find(String name) {
-                        return BuildVariant.this.getArtifactSlotByName(name);
+                        return BuildVariant.this.findArtifactSlot(name);
+                    }
+                    public BuildArtifactSlot require(String name) {
+                        return BuildVariant.this.requireArtifactSlot(name);
                     }
                 }
                 public static final class AttributesSpec {
                     private final VariantAttributes attributes;
                     AttributesSpec(VariantAttributes attributes) {
                         this.attributes = attributes;
                     }
                     public <T> void attribute(Attribute<T> key, T value) {
                         attributes.attribute(key, value);
                     }
                     public <T> void attributeProvider(Attribute<T> key, Provider<? extends T> value) {
                         attributes.attributeProvider(key, value);
                     }
                     public void string(String name, String value) {
                         attribute(Attribute.of(name, String.class), value);
                     }
                     public void string(String name, Provider<? extends String> value) {
                         attributeProvider(Attribute.of(name, String.class), value);
                     }
                     public void bool(String name, boolean value) {
                         attribute(Attribute.of(name, Boolean.class), value);
                     }
                     public void bool(String name, Provider<? extends Boolean> value) {
                         attributeProvider(Attribute.of(name, Boolean.class), value);
                     }
                     public void integer(String name, int value) {
                         attribute(Attribute.of(name, Integer.class), value);
                     }
                     public void integer(String name, Provider<? extends Integer> value) {
                         attributeProvider(Attribute.of(name, Integer.class), value);
                     }
                     public VariantAttributes asAttributes() {
                         return attributes;
                     }
                 }
             }

common/src/main/java/org/implab/gradle/common/sources/BuildVariantsExtension.java +8 -2

             package org.implab.gradle.common.sources;
             import java.util.ArrayList;
             import java.util.Collection;
             import java.util.Collections;
             import java.util.HashMap;
             import java.util.HashSet;
             import java.util.LinkedHashMap;
             import java.util.LinkedHashSet;
             import java.util.List;
             import java.util.Map;
+            import java.util.Optional;
             import java.util.Set;
             import javax.inject.Inject;
             import org.implab.gradle.common.core.lang.Closures;
             import org.gradle.api.Action;
             import org.gradle.api.InvalidUserDataException;
             import org.gradle.api.NamedDomainObjectContainer;
             import org.gradle.api.model.ObjectFactory;
             import groovy.lang.Closure;
             public abstract class BuildVariantsExtension {
                 private final NamedDomainObjectContainer<BuildLayer> layers;
                 private final NamedDomainObjectContainer<BuildVariant> variants;
                 private final List<Action<? super BuildVariantsExtension>> finalizedActions = new ArrayList<>();
                 private boolean finalized;
                 @Inject
                 public BuildVariantsExtension(ObjectFactory objects) {
                     layers = objects.domainObjectContainer(BuildLayer.class);
                     variants = objects.domainObjectContainer(BuildVariant.class);
                     layers.all(layer -> {
                         if (finalized)
                             throw new InvalidUserDataException(
                                     "Variants model is finalized and cannot add layer '" + layer.getName() + "'");
                     });
                     variants.all(variant -> {
                         if (finalized)
                             throw new InvalidUserDataException(
                                     "Variants model is finalized and cannot add variant '" + variant.getName() + "'");
                     });
                 }
                 public NamedDomainObjectContainer<BuildLayer> getLayers() {
                     return layers;
                 }
                 public NamedDomainObjectContainer<BuildVariant> getVariants() {
                     return variants;
                 }
                 public void layers(Action<? super NamedDomainObjectContainer<BuildLayer>> action) {
                     ensureMutable("configure layers");
                     action.execute(layers);
                 }
                 public void layers(Closure<?> configure) {
                     layers(Closures.action(configure));
                 }
                 public void variants(Action<? super NamedDomainObjectContainer<BuildVariant>> action) {
                     ensureMutable("configure variants");
                     action.execute(variants);
                 }
                 public void variants(Closure<?> configure) {
                     variants(Closures.action(configure));
                 }
                 public BuildLayer layer(String name, Action<? super BuildLayer> configure) {
                     ensureMutable("configure layers");
                     var layer = layers.maybeCreate(name);
                     configure.execute(layer);
                     return layer;
                 }
                 public BuildLayer layer(String name, Closure<?> configure) {
                     return layer(name, Closures.action(configure));
                 }
                 public BuildLayer layer(String name) {
                     return layer(name, it -> {
                     });
                 }
                 public BuildVariant variant(String name, Action<? super BuildVariant> configure) {
                     ensureMutable("configure variants");
                     var variant = variants.maybeCreate(name);
                     configure.execute(variant);
                     return variant;
                 }
                 public BuildVariant variant(String name, Closure<?> configure) {
                     return variant(name, Closures.action(configure));
                 }
                 public BuildVariant variant(String name) {
                     return variant(name, it -> {
                     });
                 }
                 public void all(Action<? super BuildVariant> action) {
                     variants.all(action);
                 }
                 public void all(Closure<?> configure) {
                     all(Closures.action(configure));
                 }
                 public Collection<BuildVariant> getAll() {
                     var all = new ArrayList<BuildVariant>();
                     variants.forEach(all::add);
                     return Collections.unmodifiableList(all);
                 }
-                public BuildVariant getByName(String name) {
+                public Optional<BuildVariant> find(String name) {
-                    return variants.findByName(name);
+                    return Optional.ofNullable(variants.findByName(name));
+                }
+                public BuildVariant require(String name) {
+                    return find(name)
+                            .orElseThrow(() -> new InvalidUserDataException("Variant '" + name + "' isn't defined"));
                 }
                 public void whenFinalized(Action<? super BuildVariantsExtension> action) {
                     if (finalized) {
                         action.execute(this);
                         return;
                     }
                     finalizedActions.add(action);
                 }
                 public void whenFinalized(Closure<?> configure) {
                     whenFinalized(Closures.action(configure));
                 }
                 public boolean isFinalized() {
                     return finalized;
                 }
                 public void finalizeModel() {
                     if (finalized)
                         return;
                     validate();
                     for (var variant : variants)
                         variant.finalizeModel();
                     finalized = true;
                     var actions = new ArrayList<>(finalizedActions);
                     finalizedActions.clear();
                     for (var action : actions)
                         action.execute(this);
                 }
                 public void validate() {
                     var errors = new ArrayList<String>();
                     var layersByName = new LinkedHashMap<String, BuildLayer>();
                     for (var layer : layers) {
                         var layerName = normalize(layer.getName());
                         if (layerName == null) {
                             errors.add("Layer name must not be blank");
                             continue;
                         }
                         var previous = layersByName.putIfAbsent(layerName, layer);
                         if (previous != null) {
                             errors.add("Layer '" + layerName + "' is declared more than once");
                         }
                     }
                     for (var variant : variants)
                         validateVariant(variant, layersByName, errors);
                     if (!errors.isEmpty()) {
                         var message = new StringBuilder("Invalid variants model:");
                         for (var error : errors)
                             message.append("\n - ").append(error);
                         throw new InvalidUserDataException(message.toString());
                     }
                 }
                 private static void validateVariant(BuildVariant variant, Map<String, BuildLayer> layersByName, List<String> errors) {
                     var variantName = normalize(variant.getName());
                     if (variantName == null) {
                         errors.add("Variant name must not be blank");
                         return;
                     }
                     validateRoleAndArtifactNames(variant, errors);
                     var variantLayers = validateRoleMappings(variant, layersByName, errors);
                     validateLinks(variant, variantLayers, errors);
                 }
                 private static void validateRoleAndArtifactNames(BuildVariant variant, List<String> errors) {
                     var roleNames = new LinkedHashSet<String>();
                     for (var role : variant.getRoles()) {
                         var roleName = normalize(role.getName());
                         if (roleName == null) {
                             errors.add("Variant '" + variant.getName() + "' contains blank role name");
                             continue;
                         }
                         if (!roleNames.add(roleName)) {
                             errors.add("Variant '" + variant.getName() + "' contains duplicated role name '" + roleName + "'");
                         }
                     }
                     var slotNames = new LinkedHashSet<String>();
                     for (var slot : variant.getArtifactSlots()) {
                         var slotName = normalize(slot.getName());
                         if (slotName == null) {
                             errors.add("Variant '" + variant.getName() + "' contains blank artifact slot name");
                             continue;
                         }
                         if (!slotNames.add(slotName)) {
                             errors.add("Variant '" + variant.getName() + "' contains duplicated artifact slot name '" + slotName + "'");
                         }
                     }
                 }
                 private static Set<String> validateRoleMappings(BuildVariant variant, Map<String, BuildLayer> layersByName,
                         List<String> errors) {
                     var variantLayers = new LinkedHashSet<String>();
                     for (var role : variant.getRoles()) {
                         var seenLayers = new LinkedHashSet<String>();
                         for (var layerName : role.getLayers().getOrElse(List.of())) {
                             var normalizedLayerName = normalize(layerName);
                             if (normalizedLayerName == null) {
                                 errors.add("Variant '" + variant.getName() + "', role '" + role.getName() + "' contains blank layer name");
                                 continue;
                             }
                             var layer = layersByName.get(normalizedLayerName);
                             if (layer == null) {
                                 errors.add("Variant '" + variant.getName() + "' references unknown layer '" + normalizedLayerName + "'");
                                 continue;
                             }
                             if (!seenLayers.add(normalizedLayerName)) {
                                 errors.add("Variant '" + variant.getName() + "', role '" + role.getName()
                                         + "' contains duplicated layer reference '" + normalizedLayerName + "'");
                                 continue;
                             }
                             variantLayers.add(normalizedLayerName);
                         }
                     }
                     return variantLayers;
                 }
                 private static void validateLinks(BuildVariant variant, Set<String> variantLayers, List<String> errors) {
                     var seenLinks = new HashSet<String>();
                     var edgesByKind = new HashMap<String, Map<String, Set<String>>>();
                     for (var link : variant.getLinks()) {
                         var from = normalize(link.from());
                         var to = normalize(link.to());
                         var kind = normalize(link.kind());
                         if (from == null || to == null || kind == null) {
                             errors.add("Variant '" + variant.getName() + "' has incomplete link (from/to/kind are required)");
                             continue;
                         }
                         if (!variantLayers.contains(from)) {
                             errors.add("Variant '" + variant.getName() + "' link references unknown source layer '"
                                     + from + "'");
                             continue;
                         }
                         if (!variantLayers.contains(to)) {
                             errors.add("Variant '" + variant.getName() + "' link references unknown target layer '"
                                     + to + "'");
                             continue;
                         }
                         var linkKey = from + "\u0000" + to + "\u0000" + kind;
                         if (!seenLinks.add(linkKey)) {
                             errors.add("Variant '" + variant.getName() + "' has duplicated link tuple (from='" + from
                                     + "', to='" + to + "', kind='" + kind + "')");
                         }
                         edgesByKind
                                 .computeIfAbsent(kind, x -> new LinkedHashMap<>())
                                 .computeIfAbsent(from, x -> new LinkedHashSet<>())
                                 .add(to);
                     }
                     for (var entry : edgesByKind.entrySet()) {
                         if (hasCycle(variantLayers, entry.getValue())) {
                             errors.add("Variant '" + variant.getName() + "' contains cycle in links with kind '" + entry.getKey() + "'");
                         }
                     }
                 }
                 private static boolean hasCycle(Set<String> nodes, Map<String, Set<String>> edges) {
                     var state = new HashMap<String, Integer>();
                     for (var node : nodes) {
                         if (dfs(node, state, edges))
                             return true;
                     }
                     return false;
                 }
                 private static boolean dfs(String node, Map<String, Integer> state, Map<String, Set<String>> edges) {
                     var current = state.getOrDefault(node, 0);
                     if (current == 1)
                         return true;
                     if (current == 2)
                         return false;
                     state.put(node, 1);
                     for (var next : edges.getOrDefault(node, Set.of())) {
                         if (dfs(next, state, edges))
                             return true;
                     }
                     state.put(node, 2);
                     return false;
                 }
                 private static String normalize(String value) {
                     if (value == null)
                         return null;
                     var trimmed = value.trim();
                     return trimmed.isEmpty() ? null : trimmed;
                 }
                 private static boolean isBlank(String value) {
                     return normalize(value) == null;
                 }
                 private void ensureMutable(String operation) {
                     if (finalized)
                         throw new InvalidUserDataException("Variants model is finalized and cannot " + operation);
                 }
             }

common/src/main/java/org/implab/gradle/common/sources/VariantAttributes.java +14 -2

             package org.implab.gradle.common.sources;
             import java.util.Collections;
             import java.util.LinkedHashMap;
             import java.util.Map;
             import org.gradle.api.InvalidUserDataException;
             import org.gradle.api.attributes.Attribute;
             import org.gradle.api.provider.ProviderFactory;
             import org.gradle.api.provider.Provider;
             /**
              * Typed attribute storage used by build variants.
              */
             public final class VariantAttributes {
                 private final ProviderFactory providers;
                 private final LinkedHashMap<Attribute<?>, Provider<?>> values = new LinkedHashMap<>();
+                private final Provider<Object> emptyValueProvider;
                 private boolean finalized;
                 VariantAttributes(ProviderFactory providers) {
                     this.providers = providers;
+                    this.emptyValueProvider = providers.provider(() -> null);
                 }
                 public <T> void attribute(Attribute<T> key, T value) {
                     ensureMutable("set attribute '" + key.getName() + "'");
                     attributeProvider(key, providers.provider(() -> value));
                 }
                 public <T> void attributeProvider(Attribute<T> key, Provider<? extends T> value) {
                     ensureMutable("set attribute provider '" + key.getName() + "'");
                     values.put(key, value);
                 }
                 @SuppressWarnings("unchecked")
-                public <T> Provider<T> get(Attribute<T> key) {
+                public <T> Provider<T> find(Attribute<T> key) {
-                    return (Provider<T>) values.get(key);
+                    return providers
+                            .provider(() -> (Provider<T>) values.getOrDefault(key, emptyValueProvider))
+                            .flatMap(provider -> provider);
+                }
+                public <T> Provider<T> require(Attribute<T> key) {
+                    var value = find(key);
+                    if (!value.isPresent())
+                        throw new InvalidUserDataException("Attribute '" + key.getName() + "' doesn't have a value");
+                    return value;
                 }
                 public boolean contains(Attribute<?> key) {
                     return values.containsKey(key);
                 }
                 public int size() {
                     return values.size();
                 }
                 public Map<Attribute<?>, Provider<?>> asMap() {
                     return Collections.unmodifiableMap(values);
                 }
                 void finalizeModel() {
                     finalized = true;
                 }
                 private void ensureMutable(String operation) {
                     if (finalized)
                         throw new InvalidUserDataException("Variant attributes are finalized and cannot " + operation);
                 }
             }

common/src/test/java/org/implab/gradle/common/sources/VariantsPluginFunctionalTest.java +4 -4

             package org.implab.gradle.common.sources;
             import static org.junit.jupiter.api.Assertions.assertNotNull;
             import static org.junit.jupiter.api.Assertions.assertThrows;
             import static org.junit.jupiter.api.Assertions.assertTrue;
             import java.io.File;
             import java.io.IOException;
             import java.nio.file.Files;
             import java.nio.file.Path;
             import java.util.List;
             import org.gradle.testkit.runner.BuildResult;
             import org.gradle.testkit.runner.GradleRunner;
             import org.gradle.testkit.runner.TaskOutcome;
             import org.gradle.testkit.runner.UnexpectedBuildFailure;
             import org.junit.jupiter.api.Test;
             import org.junit.jupiter.api.io.TempDir;
             class VariantsPluginFunctionalTest {
                 private static final String SETTINGS_FILE = "settings.gradle";
                 private static final String BUILD_FILE = "build.gradle";
                 private static final String ROOT_NAME = "rootProject.name = 'variants-fixture'\n";
                 @TempDir
                 Path testProjectDir;
                 @Test
                 void configuresVariantModelWithDsl() throws Exception {
                     writeFile(SETTINGS_FILE, ROOT_NAME);
                     writeFile(BUILD_FILE, """
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('mainBase') {
                             }
                             layer('mainAmd') {
                             }
                             variant('browser') {
                                 attributes {
                                     string('jsRuntime', 'browser')
                                     string('jsModule', 'amd')
                                 }
                                 role('main') {
                                     layers('mainBase', 'mainAmd')
                                 }
                                 link('mainBase', 'mainAmd', 'ts:api')
                                 artifactSlot('mainCompiled')
                             }
                         }
-                        tasks.register('probe') {
+                            tasks.register('probe') {
-                            doLast {
+                                doLast {
-                                def browser = variants.getByName('browser')
+                                def browser = variants.require('browser')
                                 println('attributes=' + browser.attributes.size())
                                 println('roles=' + browser.roles.size())
                                 println('links=' + browser.links.size())
                                 println('slots=' + browser.artifactSlots.size())
                             }
                         }
                         """);
                     BuildResult result = runner("probe").build();
                     assertTrue(result.getOutput().contains("attributes=2"));
                     assertTrue(result.getOutput().contains("roles=1"));
                     assertTrue(result.getOutput().contains("links=1"));
                     assertTrue(result.getOutput().contains("slots=1"));
                     assertTrue(result.task(":probe").getOutcome() == TaskOutcome.SUCCESS);
                 }
                 @Test
                 void failsOnUnknownLayerReference() throws Exception {
                     assertBuildFails("""
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('mainBase') {
                             }
                             variant('browser') {
                                 role('main') {
                                     layers('mainBase', 'missingLayer')
                                 }
                             }
                         }
                         """, "references unknown layer 'missingLayer'");
                 }
                 @Test
                 void failsOnCycleInLinksByKind() throws Exception {
                     assertBuildFails("""
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('a')
                             layer('b')
                             variant('browser') {
                                 role('main') {
                                     layers('a', 'b')
                                 }
                                 link('a', 'b', 'ts:api')
                                 link('b', 'a', 'ts:api')
                             }
                         }
                         """, "contains cycle in links with kind 'ts:api'");
                 }
                 @Test
                 void allowsUsingLayerFromDifferentVariantRole() throws Exception {
                     writeFile(SETTINGS_FILE, ROOT_NAME);
                     writeFile(BUILD_FILE, """
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('mainBase')
                             variant('browser') {
                                 role('test') {
                                     layers('mainBase')
                                 }
                             }
                         }
                         """);
                     BuildResult result = runner("help").build();
                     assertTrue(result.getOutput().contains("BUILD SUCCESSFUL"));
                 }
                 @Test
                 void failsOnIncompleteLink() throws Exception {
                     assertBuildFails("""
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('a')
                             layer('b')
                             variant('browser') {
                                 role('main') {
                                     layers('a', 'b')
                                 }
                                 link('a', 'b', null)
                             }
                         }
                         """, "Link 'kind' must not be null or blank");
                 }
                 @Test
                 void failsOnDuplicatedLinkTuple() throws Exception {
                     assertBuildFails("""
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('a')
                             layer('b')
                             variant('browser') {
                                 role('main') {
                                     layers('a', 'b')
                                 }
                                 link('a', 'b', 'ts:api')
                                 link('a', 'b', 'ts:api')
                             }
                         }
                         """, "has duplicated link tuple (from='a', to='b', kind='ts:api')");
                 }
                 @Test
                 void failsOnUnknownSourceLayerInLink() throws Exception {
                     assertBuildFails("""
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('a') {
                             }
                             variant('browser') {
                                 role('main') {
                                     layers('a')
                                 }
                                 link('missing', 'a', 'ts:api')
                             }
                         }
                         """, "references unknown source layer 'missing'");
                 }
                 @Test
                 void failsOnUnknownTargetLayerInLink() throws Exception {
                     assertBuildFails("""
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('a') {
                             }
                             variant('browser') {
                                 role('main') {
                                     layers('a')
                                 }
                                 link('a', 'missing', 'ts:api')
                             }
                         }
                         """, "references unknown target layer 'missing'");
                 }
                 @Test
                 void failsOnDuplicatedLayerReferenceInRole() throws Exception {
                     assertBuildFails("""
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('a')
                             variant('browser') {
                                 role('main') {
                                     layers('a', 'a')
                                 }
                             }
                         }
                         """, "contains duplicated layer reference 'a'");
                 }
                 @Test
                 void failsOnLateLayerMutationAfterFinalize() throws Exception {
                     assertBuildFails("""
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('a')
                             variant('browser') {
                                 role('main') { layers('a') }
                             }
                         }
                         afterEvaluate {
                             variants.layer('late')
                         }
                         """, "Variants model is finalized and cannot configure layers");
                 }
                 @Test
                 void failsOnLateVariantMutationAfterFinalize() throws Exception {
                     assertBuildFails("""
                         plugins {
                             id 'org.implab.gradle-variants'
                         }
                         variants {
                             layer('a')
                             variant('browser') {
                                 role('main') { layers('a') }
                             }
                         }
                         afterEvaluate {
-                            variants.getByName('browser').role('late') { layers('a') }
+                            variants.require('browser').role('late') { layers('a') }
                         }
                         """, "Variant 'browser' is finalized and cannot configure roles");
                 }
                 private GradleRunner runner(String... arguments) {
                     return GradleRunner.create()
                             .withProjectDir(testProjectDir.toFile())
                             .withPluginClasspath(pluginClasspath())
                             .withArguments(arguments)
                             .forwardOutput();
                 }
                 private void assertBuildFails(String buildScript, String expectedError) throws Exception {
                     writeFile(SETTINGS_FILE, ROOT_NAME);
                     writeFile(BUILD_FILE, buildScript);
                     var ex = assertThrows(UnexpectedBuildFailure.class, () -> runner("help").build());
                     var output = ex.getBuildResult().getOutput();
                     assertTrue(output.contains(expectedError), () -> "Expected [" + expectedError + "] in output:\n" + output);
                 }
                 private static List<File> pluginClasspath() {
                     try {
                         var classesDir = Path.of(BuildVariant.class
                                 .getProtectionDomain()
                                 .getCodeSource()
                                 .getLocation()
                                 .toURI());
                         var markerResource = VariantsPlugin.class.getClassLoader()
                                 .getResource("META-INF/gradle-plugins/org.implab.gradle-variants.properties");
                         assertNotNull(markerResource, "Plugin marker resource is missing from test classpath");
                         var markerPath = Path.of(markerResource.toURI());
                         var resourcesDir = markerPath.getParent().getParent().getParent();
                         return List.of(classesDir.toFile(), resourcesDir.toFile());
                     } catch (Exception e) {
                         throw new RuntimeException("Unable to build plugin classpath for test", e);
                     }
                 }
                 private void writeFile(String relativePath, String content) throws IOException {
                     Path path = testProjectDir.resolve(relativePath);
                     Files.createDirectories(path.getParent());
                     Files.writeString(path, content);
                 }
             }

common/variants-plugin.md +1 -1

             # Variants Plugin
             ## NAME
             `VariantsPlugin` и extension `variants`.
             ## SYNOPSIS
             ```groovy
             plugins {
                 id 'org.implab.gradle-variants'
             }
             variants {
                 layer('mainBase')
                 layer('mainAmd')
                 variant('browser') {
                     attributes {
                         string('jsRuntime', 'browser')
                         string('jsModule', 'amd')
                     }
                     role('main') {
                         layers('mainBase', 'mainAmd')
                     }
                     link('mainBase', 'mainAmd', 'ts:api')
                     artifactSlot('mainCompiled')
                 }
             }
             ```
             ## DESCRIPTION
             `VariantsPlugin` задает доменную модель сборки и ее валидацию. Плагин не
             регистрирует compile/copy/bundle задачи напрямую.
             ### layers
             Глобальные логические слои. Служат единым словарем имен, на которые затем
             ссылаются роли и связи.
             ### variants
             Именованные варианты исполнения/пакетирования (`browser`, `node`, и т.д.).
             Вариант агрегирует роли, связи, атрибуты и artifact slots.
             ### roles
             Роль описывает набор слоев в пределах варианта (`main`, `test`, `tools`).
             Одна роль может ссылаться на несколько слоев.
             ### links
             `link(from, to, kind)` — ориентированная связь между слоями внутри варианта.
             `kind` задает независимый тип графа (например `ts:api`, `bundle:runtime`). Это
             позволяет вести несколько параллельных графов зависимостей над теми же слоями.
             Практические сценарии использования `link` в адаптерах:
             - расчет topological order по выбранному `kind`;
             - wiring task inputs/outputs между слоями;
             - проверка допустимости дополнительных pipeline-зависимостей.
             ### attributes
             Typed-атрибуты (`Attribute<T> -> Provider<T>`) для передачи параметров в
             адаптеры и публикацию артефактов.
             ### artifact slots
             Именованные слоты ожидаемых артефактов варианта. Используются как контракт
             между моделью варианта и плагинами, создающими/публикующими результаты.
             ## VALIDATION
             В `finalizeModel()` выполняется проверка:
             - роль не может ссылаться на неизвестный layer;
             - пустые имена layer запрещены;
             - у link обязательны `from`, `to`, `kind`;
             - `from`/`to` должны входить в слойную область варианта;
             - tuple `(from, to, kind)` должен быть уникален;
             - циклы в графе одного `kind` запрещены.
             ## LIFECYCLE
             - `VariantsPlugin` вызывает `variants.finalizeModel()` на `afterEvaluate`.
             - после `finalizeModel()` мутации модели запрещены.
             - `whenFinalized(...)` replayable.
             ## API
             ### BuildVariantsExtension
             - `layer(...)` — объявление или конфигурация `BuildLayer`.
             - `variant(...)` — объявление или конфигурация `BuildVariant`.
             - `layers { ... }`, `variants { ... }` — контейнерный DSL.
             - `all(...)` — callback для всех вариантов.
-            - `getAll()`, `getByName(name)` — доступ к вариантам.
+            - `getAll()`, `find(name)`, `require(name)` — доступ к вариантам.
             - `validate()` — явный запуск валидации.
             - `finalizeModel()` — валидация + финализация модели.
             - `whenFinalized(...)` — callback по завершенной модели (replayable).
             ### BuildVariant
             - `attributes { ... }` — атрибуты варианта (+ sugar `string/bool/integer`).
             - `role(...)`, `roles { ... }` — роли варианта.
             - `link(...)`, `links { ... }` — связи слоев внутри варианта.
             - `artifactSlot(...)`, `artifactSlots { ... }` — артефактные слоты.
             ## KEY CLASSES
             - `VariantsPlugin` — точка входа плагина.
             - `BuildVariantsExtension` — root extension и lifecycle.
             - `BuildVariant` — агрегатная модель варианта.
             - `BuildLayer` — модель слоя.
             - `BuildRole` — модель роли.
             - `LayerLink` — модель направленной связи.
             - `BuildArtifactSlot` — модель артефактного слота.
             - `VariantAttributes` — typed wrapper для variant attributes.
             ## NOTES
             - Модель `variants` intentionally agnostic к toolchain.
             - Интеграция с задачами выполняется через `variantSources` и адаптеры.

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