Add a root meta-trait to declare root shapes

This adds a new `root` meta-trait. This trait marks a trait as a rooting
trait. Any shape marked by a rooting trait is considered to be a root
shape. Root shapes are shapes that are always considered to be
referenced.

Currently, service shapes and traits are considered to be root shapes. A
new metadata trait is being added that will also define new root shapes.

Beyond that, this trait is a necessary prerequisite for using Smithy to
define schemas and use-cases that are not bound to the context of a
service API.

For example, imagine a theoretical `jsonSchema` trait that uses Smithy
to define a plain JSONSchema definition that isn't tied to OpenAPI. We
wouldn't want those shapes to be considered unreferenced because that
might mean they get filtered away inappropriately and it would mean
the unreferenced shape linter would start producing a huge amount of
noise.

Author: JordonPhillips

.changes/next-release/feature-e6568a1e1dfc56615f929d210617007a032cb35e.json

@@ -0,0 +1,7 @@
+{
+  "type": "feature",
+  "description": "Added a new `root` meta-trait that marks a trait as a rooting trait. Shapes targeted by a rooting trait are considered root shapes, which are always considered to be referenced.",
+  "pull_requests": [
+    "[#3079](https://github.com/smithy-lang/smithy/pull/3079)"
+  ]
+}

docs/source-2.0/guides/model-linters.rst

@@ -78,7 +78,8 @@ configuration is provided, the linter will check if a shape is connected to
 the closure of any service shape. A selector can be provided to define a
 custom set of "root" shapes to customize how the linter determines if a shape
 is unreferenced. Shapes that are connected through the :ref:`idref-trait`
-are considered connected.
+are considered connected. Shapes targeted by traits marked with the
+:ref:`root-trait` are also considered connected.
 
 Rationale
     Just like unused variables in code, removing unused shapes from a model

docs/source-2.0/spec/model.rst

@@ -1123,6 +1123,7 @@ Is changed to:
 Then the change to the ``foo`` member from "a" to "b" is backward
 incompatible, as is the removal of the ``baz`` member.
 
+
 Referring to list members
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1250,6 +1251,58 @@ backward incompatible.
       effect.
 
 
+.. smithy-trait:: smithy.api#root
+.. _root-trait:
+
+``root`` trait
+--------------
+
+Summary
+    A meta-trait that marks a trait as a *rooting* trait. Shapes targeted by
+    a rooting trait, and all shapes transitively connected to them, are
+    considered root shapes and are never treated as unreferenced.
+Trait selector
+    ``[trait|trait]``
+Value type
+    Annotation trait
+
+Certain shapes in a Smithy model are considered *root shapes*. Root shapes
+sit at the top of a closure of shapes that serve some shared purpose. For
+example, :ref:`service shapes <service>` are root shapes because they are
+the entry point of a service API. Root shapes and all shapes transitively
+connected to them are always considered referenced.
+
+The :ref:`trait <trait-trait>` trait is itself marked with ``@root``, which
+is why all trait definitions and the shapes they reference are automatically
+considered root shapes. The ``@root`` trait allows custom traits to designate
+their targets as additional root shapes. This is useful when shapes are not
+connected to a service but should still be retained in the model.
+
+The following example defines a ``@myRoot`` trait that is marked with
+``@root``. Any shape that has ``@myRoot`` applied, along with all shapes
+transitively connected to it, will never be considered unreferenced:
+
+.. code-block:: smithy
+
+    @root
+    @trait
+    structure myRoot {}
+
+    @myRoot
+    structure MyShape {
+        value: MyString
+    }
+
+    // Not unreferenced because it is connected to MyShape,
+    // which is a root shape due to @myRoot.
+    string MyString
+
+.. seealso::
+
+    :ref:`UnreferencedShape`
+        The linter that detects shapes not connected to any root shape.
+
+
 ..  _prelude:
 
 -------

smithy-model/src/main/java/software/amazon/smithy/model/neighbor/UnreferencedShapes.java

@@ -13,7 +13,7 @@
 import software.amazon.smithy.model.selector.Selector;
 import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.model.shapes.ShapeId;
-import software.amazon.smithy.model.traits.TraitDefinition;
+import software.amazon.smithy.model.traits.RootTrait;
 import software.amazon.smithy.utils.FunctionalUtils;
 
 /**
@@ -25,6 +25,9 @@
  * that considers every matching shape a root shape. For example, a model might consider all shapes marked with
  * a trait called "root" to be a root shape.
  *
+ * <p>Root shapes will also always include any shapes targeted by a trait that has the
+ * {@link software.amazon.smithy.model.traits.RootTrait} and any shape that is connected to one of those shapes.
+ *
  * <p>Prelude shapes are never considered unreferenced.
  */
 public final class UnreferencedShapes {
@@ -77,9 +80,12 @@ public Set<Shape> compute(Model model) {
             shapeWalker.iterateShapes(root, traversed).forEachRemaining(shape -> connected.add(shape.getId()));
         }
 
-        // Don't remove shapes that are traits or connected to traits.
-        for (Shape trait : model.getShapesWithTrait(TraitDefinition.class)) {
-            shapeWalker.iterateShapes(trait, traversed).forEachRemaining(shape -> connected.add(shape.getId()));
+        // Don't remove root shapes or shapes that ar connected to them. This includes traits.
+        for (Shape rootTrait : model.getShapesWithTrait(RootTrait.class)) {
+            for (Shape shape : model.getShapesWithTrait(rootTrait.getId())) {
+                shapeWalker.iterateShapes(shape, traversed)
+                        .forEachRemaining(s -> connected.add(s.getId()));
+            }
         }
 
         // Any shape that wasn't identified as connected to a root is considered unreferenced.

smithy-model/src/main/java/software/amazon/smithy/model/traits/RootTrait.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package software.amazon.smithy.model.traits;
+
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.node.ObjectNode;
+import software.amazon.smithy.model.shapes.ShapeId;
+
+/**
+ * Indicates that the targeted trait is a rooting trait. Shapes targeted by a
+ * rooting trait are considered root shapes. Root shapes and shapes transitively
+ * connected to them are never considered to be unreferenced.
+ */
+public final class RootTrait extends AnnotationTrait {
+    public static final ShapeId ID = ShapeId.from("smithy.api#root");
+
+    public RootTrait(ObjectNode node) {
+        super(ID, node);
+    }
+
+    public RootTrait() {
+        this(Node.objectNode());
+    }
+
+    public static final class Provider extends AnnotationTrait.Provider<RootTrait> {
+        public Provider() {
+            super(ID, RootTrait::new);
+        }
+    }
+}

smithy-model/src/main/java/software/amazon/smithy/model/validation/linters/UnreferencedShapeValidator.java

@@ -81,6 +81,7 @@ public List<ValidationEvent> validate(Model model) {
         for (Shape shape : new UnreferencedShapes(config.rootShapeSelector).compute(model)) {
             events.add(note(shape,
                     "This shape is unreferenced. It has no modeled connections to shapes "
+                            + "targeted by a root trait or shapes "
                             + "that match the following selector: `" + config.rootShapeSelector + "`"));
         }
 

smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.traits.TraitService

@@ -58,6 +58,7 @@ software.amazon.smithy.model.traits.RequiredTrait$Provider
 software.amazon.smithy.model.traits.RequiresLengthTrait$Provider
 software.amazon.smithy.model.traits.ResourceIdentifierTrait$Provider
 software.amazon.smithy.model.traits.RetryableTrait$Provider
+software.amazon.smithy.model.traits.RootTrait$Provider
 software.amazon.smithy.model.traits.SensitiveTrait$Provider
 software.amazon.smithy.model.traits.SinceTrait$Provider
 software.amazon.smithy.model.traits.SparseTrait$Provider

smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude.smithy

@@ -63,6 +63,7 @@ structure Unit {}
 // --- Shapes below are traits and the private shapes that define them.
 
 /// Makes a shape a trait.
+@root
 @trait(
     selector: ":is(simpleType, list, map, structure, union)"
     breakingChanges: [
@@ -156,6 +157,22 @@ enum StructurallyExclusive {
     TARGET = "target"
 }
 
+/// Marks a trait as a rooting trait.
+///
+/// Shapes targeted by a rooting trait are considered root shapes. Root shapes
+/// and shapes transitively connected to them are never considered to be
+/// unreferenced.
+@trait(
+    selector: "[trait|trait]"
+    breakingChanges: [
+        {
+            change: "presence"
+            severity: "DANGER"
+        }
+    ]
+)
+structure root {}
+
 /// Marks a shape or member as deprecated.
 @trait
 structure deprecated {

smithy-model/src/test/java/software/amazon/smithy/model/neighbor/UnreferencedShapesTest.java

@@ -98,4 +98,27 @@ public void doesNotCheckShapeReferencesThroughIdRefOnUnconnectedShapes() {
                         ShapeId.from("com.foo#Referenced"),
                         ShapeId.from("com.foo#Unconnected")));
     }
+
+    @Test
+    public void rootTraitMarksTargetedShapesAsConnected() {
+        Model m = Model.assembler()
+                .addUnparsedModel("test.smithy",
+                        "$version: \"2.0\"\n"
+                                + "namespace ns.foo\n"
+                                + "@root\n"
+                                + "@trait\n"
+                                + "structure myRoot {}\n"
+                                + "@myRoot\n"
+                                + "string Rooted\n"
+                                + "string Unconnected\n")
+                .assemble()
+                .unwrap();
+
+        Set<ShapeId> ids = new UnreferencedShapes().compute(m)
+                .stream()
+                .map(Shape::getId)
+                .collect(Collectors.toSet());
+
+        assertThat(ids, containsInAnyOrder(ShapeId.from("ns.foo#Unconnected")));
+    }
 }

smithy-model/src/test/java/software/amazon/smithy/model/traits/RootTraitTest.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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 RootTraitTest {
+    @Test
+    public void loadsTrait() {
+        TraitFactory provider = TraitFactory.createServiceFactory();
+        Optional<Trait> trait = provider.createTrait(
+                ShapeId.from("smithy.api#root"),
+                ShapeId.from("ns.qux#foo"),
+                Node.objectNode());
+
+        assertTrue(trait.isPresent());
+        assertThat(trait.get(), instanceOf(RootTrait.class));
+        assertThat(trait.get().toNode(), equalTo(Node.objectNode()));
+    }
+}