From 63a0ca6738e6730c3488d0a196ef58cfa35b1461 Mon Sep 17 00:00:00 2001 From: Chase Coalwell Date: Fri, 21 Feb 2020 10:09:31 -0800 Subject: [PATCH 1/3] Add unstable trait and validator --- .../amazon/smithy/model/loader/Prelude.java | 2 + .../smithy/model/traits/UnstableTrait.java | 40 +++++++++++++ .../validators/UnstableTraitValidator.java | 58 +++++++++++++++++++ ...re.amazon.smithy.model.traits.TraitService | 1 + ...e.amazon.smithy.model.validation.Validator | 1 + .../smithy/model/loader/prelude-traits.smithy | 4 ++ .../model/traits/UnstableTraitTest.java | 39 +++++++++++++ .../unstable-trait-validator.errors | 1 + .../validators/unstable-trait-validator.json | 31 ++++++++++ 9 files changed, 177 insertions(+) create mode 100644 smithy-model/src/main/java/software/amazon/smithy/model/traits/UnstableTrait.java create mode 100644 smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/UnstableTraitValidator.java create mode 100644 smithy-model/src/test/java/software/amazon/smithy/model/traits/UnstableTraitTest.java create mode 100644 smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.errors create mode 100644 smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.json diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/loader/Prelude.java b/smithy-model/src/main/java/software/amazon/smithy/model/loader/Prelude.java index 81afe18ec00..f43eaedf5f3 100644 --- a/smithy-model/src/main/java/software/amazon/smithy/model/loader/Prelude.java +++ b/smithy-model/src/main/java/software/amazon/smithy/model/loader/Prelude.java @@ -87,6 +87,7 @@ import software.amazon.smithy.model.traits.TitleTrait; import software.amazon.smithy.model.traits.TraitDefinition; import software.amazon.smithy.model.traits.UniqueItemsTrait; +import software.amazon.smithy.model.traits.UnstableTrait; import software.amazon.smithy.model.traits.XmlAttributeTrait; import software.amazon.smithy.model.traits.XmlFlattenedTrait; import software.amazon.smithy.model.traits.XmlNameTrait; @@ -193,6 +194,7 @@ public final class Prelude { TitleTrait.ID, TraitDefinition.ID, UniqueItemsTrait.ID, + UnstableTrait.ID, XmlAttributeTrait.ID, XmlFlattenedTrait.ID, XmlNameTrait.ID, diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/traits/UnstableTrait.java b/smithy-model/src/main/java/software/amazon/smithy/model/traits/UnstableTrait.java new file mode 100644 index 00000000000..32222c81a7c --- /dev/null +++ b/smithy-model/src/main/java/software/amazon/smithy/model/traits/UnstableTrait.java @@ -0,0 +1,40 @@ +/* + * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +package software.amazon.smithy.model.traits; + +import software.amazon.smithy.model.SourceLocation; +import software.amazon.smithy.model.shapes.ShapeId; + +/** + * Marks a shape as unstable. + */ +public final class UnstableTrait extends BooleanTrait { + public static final ShapeId ID = ShapeId.from("smithy.api#unstable"); + + public UnstableTrait(SourceLocation sourceLocation) { + super(ID, sourceLocation); + } + + public UnstableTrait() { + this(SourceLocation.NONE); + } + + public static final class Provider extends BooleanTrait.Provider { + public Provider() { + super(ID, UnstableTrait::new); + } + } +} diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/UnstableTraitValidator.java b/smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/UnstableTraitValidator.java new file mode 100644 index 00000000000..a047cfec66f --- /dev/null +++ b/smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/UnstableTraitValidator.java @@ -0,0 +1,58 @@ +/* + * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +package software.amazon.smithy.model.validation.validators; + +import static java.lang.String.format; + +import java.util.ArrayList; +import java.util.List; +import java.util.Set; +import java.util.stream.Collectors; +import software.amazon.smithy.model.Model; +import software.amazon.smithy.model.shapes.Shape; +import software.amazon.smithy.model.shapes.ShapeId; +import software.amazon.smithy.model.traits.UnstableTrait; +import software.amazon.smithy.model.validation.AbstractValidator; +import software.amazon.smithy.model.validation.ValidationEvent; + +/** + * Emits a validation event if a model contains shapes that are bound to unstable traits. + */ +public final class UnstableTraitValidator extends AbstractValidator { + @Override + public List validate(Model model) { + Set unstableTraits = model.getTraitShapes().stream() + .filter(trait -> trait.hasTrait(UnstableTrait.class)) + .map(Shape::getId) + .collect(Collectors.toSet()); + + return model.shapes() + .flatMap(shape -> validateShape(shape, unstableTraits).stream()) + .collect(Collectors.toList()); + } + + private List validateShape(Shape shape, Set unstableTraits) { + List events = new ArrayList<>(); + shape.getAllTraits().forEach((shapeId, trait) -> { + if (!unstableTraits.contains(trait.toShapeId())) { + return; + } + events.add(warning(shape, trait, format("This shape applies a trait that is unstable: %s", + trait.toShapeId()))); + }); + return events; + } +} diff --git a/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.traits.TraitService b/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.traits.TraitService index 667828fb915..bb2421785e0 100644 --- a/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.traits.TraitService +++ b/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.traits.TraitService @@ -42,6 +42,7 @@ software.amazon.smithy.model.traits.TimestampFormatTrait$Provider software.amazon.smithy.model.traits.TitleTrait$Provider software.amazon.smithy.model.traits.TraitDefinition$Provider software.amazon.smithy.model.traits.UniqueItemsTrait$Provider +software.amazon.smithy.model.traits.UnstableTrait$Provider software.amazon.smithy.model.traits.XmlAttributeTrait$Provider software.amazon.smithy.model.traits.XmlFlattenedTrait$Provider software.amazon.smithy.model.traits.XmlNamespaceTrait$Provider diff --git a/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator b/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator index 065e2bede6f..a5f87355976 100644 --- a/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator +++ b/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator @@ -33,4 +33,5 @@ software.amazon.smithy.model.validation.validators.TraitConflictValidator software.amazon.smithy.model.validation.validators.TraitTargetValidator software.amazon.smithy.model.validation.validators.TraitValueValidator software.amazon.smithy.model.validation.validators.UnstableFeatureValidator +software.amazon.smithy.model.validation.validators.UnstableTraitValidator software.amazon.smithy.model.validation.validators.XmlNamespaceTraitValidator diff --git a/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude-traits.smithy b/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude-traits.smithy index eb0459ad37e..8f2478ea345 100644 --- a/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude-traits.smithy +++ b/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude-traits.smithy @@ -358,6 +358,10 @@ structure required {} @trait(selector: "list") structure uniqueItems {} +/// unstable +@trait() +structure unstable {} + /// The paginated trait indicates that an operation intentionally limits the number /// of results returned in a single response and that multiple invocations might be /// necessary to retrieve all results. diff --git a/smithy-model/src/test/java/software/amazon/smithy/model/traits/UnstableTraitTest.java b/smithy-model/src/test/java/software/amazon/smithy/model/traits/UnstableTraitTest.java new file mode 100644 index 00000000000..4d2b47ea68e --- /dev/null +++ b/smithy-model/src/test/java/software/amazon/smithy/model/traits/UnstableTraitTest.java @@ -0,0 +1,39 @@ +/* + * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +package software.amazon.smithy.model.traits; + +import static org.hamcrest.MatcherAssert.assertThat; +import static org.hamcrest.Matchers.equalTo; +import static org.hamcrest.Matchers.instanceOf; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Optional; +import org.junit.jupiter.api.Test; +import software.amazon.smithy.model.node.Node; +import software.amazon.smithy.model.shapes.ShapeId; + +public class UnstableTraitTest { + @Test + public void loadsTrait() { + TraitFactory provider = TraitFactory.createServiceFactory(); + Optional trait = provider.createTrait( + ShapeId.from("smithy.api#unstable"), ShapeId.from("ns.qux#foo"), Node.from(true)); + + assertTrue(trait.isPresent()); + assertThat(trait.get(), instanceOf(UnstableTrait.class)); + assertThat(trait.get().toNode(), equalTo(Node.from(true))); + } +} diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.errors b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.errors new file mode 100644 index 00000000000..e8527d0a44f --- /dev/null +++ b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.errors @@ -0,0 +1 @@ +[WARNING] ns.foo#MyString: This shape applies a trait that is unstable: ns.foo#fooTrait | UnstableTrait diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.json b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.json new file mode 100644 index 00000000000..5bfdb2c5a22 --- /dev/null +++ b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.json @@ -0,0 +1,31 @@ +{ + "smithy": "0.5.0", + "shapes": { + "ns.foo#MyString": { + "type": "string", + "traits": { + "ns.foo#fooTrait": { }, + "ns.foo#barTrait": { } + } + }, + "ns.foo#fooTrait": { + "type": "structure", + "members": { }, + "traits": { + "smithy.api#unstable": { }, + "smithy.api#trait": { + "selector": "*" + } + } + }, + "ns.foo#barTrait": { + "type": "structure", + "members": { }, + "traits": { + "smithy.api#trait": { + "selector": "*" + } + } + } + } +} From b4ebe78004800ecbe978ac02566150aa5b1c0212 Mon Sep 17 00:00:00 2001 From: Chase Coalwell Date: Mon, 24 Feb 2020 10:51:10 -0800 Subject: [PATCH 2/3] Update spec, fix dates --- docs/source/spec/core.rst | 21 +++++++++++++++++++ .../smithy/model/traits/UnstableTrait.java | 2 +- .../validators/UnstableTraitValidator.java | 2 +- .../smithy/model/loader/prelude-traits.smithy | 2 +- .../model/traits/UnstableTraitTest.java | 2 +- 5 files changed, 25 insertions(+), 4 deletions(-) diff --git a/docs/source/spec/core.rst b/docs/source/spec/core.rst index 2b9fc5a72f3..5e3c046c21a 100644 --- a/docs/source/spec/core.rst +++ b/docs/source/spec/core.rst @@ -5550,6 +5550,27 @@ Value type } +.. _unstable-trait: + +``_unstable`` trait +--------------- + +Summary + Indicates a shape is unstable and may change in the future. +Trait selector + ``*`` + +Value type + Annotation trait + +.. tabs:: + + .. code-tab:: smithy + + @unstable + string MyString + + .. _endpoint-traits: Endpoint Traits diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/traits/UnstableTrait.java b/smithy-model/src/main/java/software/amazon/smithy/model/traits/UnstableTrait.java index 32222c81a7c..910c8c84e83 100644 --- a/smithy-model/src/main/java/software/amazon/smithy/model/traits/UnstableTrait.java +++ b/smithy-model/src/main/java/software/amazon/smithy/model/traits/UnstableTrait.java @@ -1,5 +1,5 @@ /* - * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). * You may not use this file except in compliance with the License. diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/UnstableTraitValidator.java b/smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/UnstableTraitValidator.java index a047cfec66f..2a9515932b1 100644 --- a/smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/UnstableTraitValidator.java +++ b/smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/UnstableTraitValidator.java @@ -1,5 +1,5 @@ /* - * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). * You may not use this file except in compliance with the License. diff --git a/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude-traits.smithy b/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude-traits.smithy index 8f2478ea345..b0f7271d925 100644 --- a/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude-traits.smithy +++ b/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude-traits.smithy @@ -358,7 +358,7 @@ structure required {} @trait(selector: "list") structure uniqueItems {} -/// unstable +/// Indicates that the shape is unstable and could change in the future. @trait() structure unstable {} diff --git a/smithy-model/src/test/java/software/amazon/smithy/model/traits/UnstableTraitTest.java b/smithy-model/src/test/java/software/amazon/smithy/model/traits/UnstableTraitTest.java index 4d2b47ea68e..430c4ad630f 100644 --- a/smithy-model/src/test/java/software/amazon/smithy/model/traits/UnstableTraitTest.java +++ b/smithy-model/src/test/java/software/amazon/smithy/model/traits/UnstableTraitTest.java @@ -1,5 +1,5 @@ /* - * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). * You may not use this file except in compliance with the License. From 3dd40ce3fe4206a9eb49fd20700fc885bf5f9d83 Mon Sep 17 00:00:00 2001 From: Chase Coalwell Date: Mon, 24 Feb 2020 11:12:31 -0800 Subject: [PATCH 3/3] Update spec --- docs/source/spec/core.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/source/spec/core.rst b/docs/source/spec/core.rst index 5e3c046c21a..1e75b5ac9fe 100644 --- a/docs/source/spec/core.rst +++ b/docs/source/spec/core.rst @@ -5556,7 +5556,10 @@ Value type --------------- Summary - Indicates a shape is unstable and may change in the future. + Indicates a shape is unstable and MAY change in the future. This trait can + be applied to trait definitions to indicate that a trait is unstable or + experimental. If possible, code generators SHOULD use this trait to warn + when code generated from unstable features are used. Trait selector ``*``