Always run IO structure reuse validator

This adds a validation step to the plugin that runs the IO structure
reuse validator at the danger level, adding some additional context
for how it impacts docs specifically. This also removes the
invocation to always create dedicated input and output shapes.

Author: JordonPhillips

smithy-docgen-core/build.gradle

@@ -16,4 +16,5 @@ dependencies {
     implementation("software.amazon.smithy:smithy-model:$smithyVersion")
     implementation("software.amazon.smithy:smithy-utils:$smithyVersion")
     implementation("software.amazon.smithy:smithy-codegen-core:$smithyVersion")
+    implementation("software.amazon.smithy:smithy-linters:$smithyVersion")
 }

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DirectedDocGen.java

@@ -5,7 +5,6 @@
 
 package software.amazon.smithy.docgen.core;
 
-import java.util.logging.Logger;
 import software.amazon.smithy.codegen.core.SymbolProvider;
 import software.amazon.smithy.codegen.core.directed.CreateContextDirective;
 import software.amazon.smithy.codegen.core.directed.CreateSymbolProviderDirective;
@@ -27,8 +26,6 @@
 @SmithyUnstableApi
 final class DirectedDocGen implements DirectedCodegen<DocGenerationContext, DocSettings, DocIntegration> {
 
-    private static final Logger LOGGER = Logger.getLogger(DirectedDocGen.class.getName());
-
     @Override
     public SymbolProvider createSymbolProvider(CreateSymbolProviderDirective<DocSettings> directive) {
         return new DocSymbolProvider(directive.model(), directive.settings());

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/SmithyDocPlugin.java

@@ -6,11 +6,21 @@
 package software.amazon.smithy.docgen.core;
 
 
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
 import java.util.logging.Logger;
 import software.amazon.smithy.build.PluginContext;
 import software.amazon.smithy.build.SmithyBuildPlugin;
 import software.amazon.smithy.codegen.core.directed.CodegenDirector;
+import software.amazon.smithy.docgen.core.validation.DocValidationEventDecorator;
 import software.amazon.smithy.docgen.core.writers.DocWriter;
+import software.amazon.smithy.linters.InputOutputStructureReuseValidator;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.validation.ValidatedResult;
+import software.amazon.smithy.model.validation.ValidationEvent;
+import software.amazon.smithy.model.validation.ValidationEventDecorator;
+import software.amazon.smithy.model.validation.suppressions.ModelBasedEventDecorator;
 import software.amazon.smithy.utils.SmithyInternalApi;
 
 /**
@@ -29,20 +39,44 @@ public String getName() {
     @Override
     public void execute(PluginContext pluginContext) {
         LOGGER.fine("Beginning documentation generation.");
-        DocSettings docSettings = DocSettings.from(pluginContext.getSettings());
+        DocSettings settings = DocSettings.from(pluginContext.getSettings());
 
         CodegenDirector<DocWriter, DocIntegration, DocGenerationContext, DocSettings> runner
                 = new CodegenDirector<>();
 
         runner.directedCodegen(new DirectedDocGen());
         runner.integrationClass(DocIntegration.class);
         runner.fileManifest(pluginContext.getFileManifest());
-        runner.model(pluginContext.getModel());
-        runner.settings(docSettings);
-        runner.service(docSettings.service());
+        runner.model(getValidatedModel(pluginContext.getModel()).unwrap());
+        runner.settings(settings);
+        runner.service(settings.service());
         runner.performDefaultCodegenTransforms();
-        runner.createDedicatedInputsAndOutputs();
         runner.run();
         LOGGER.fine("Finished documentation generation.");
     }
+
+    private ValidatedResult<Model> getValidatedModel(Model model) {
+        // This decorator will add context for why these are particularly important for docs.
+        ValidationEventDecorator eventDecorator = new DocValidationEventDecorator();
+
+        // This will discover and apply suppressions from the model.
+        Optional<ValidationEventDecorator> modelDecorator = new ModelBasedEventDecorator()
+                .createDecorator(model).getResult();
+        if (modelDecorator.isPresent()) {
+            eventDecorator = ValidationEventDecorator.compose(List.of(modelDecorator.get(), eventDecorator));
+        }
+
+        var events = new ArrayList<ValidationEvent>();
+        for (var event : validate(model)) {
+            if (eventDecorator.canDecorate(event)) {
+                event = eventDecorator.decorate(event);
+            }
+            events.add(event);
+        }
+        return new ValidatedResult<>(model, events);
+    }
+
+    private List<ValidationEvent> validate(Model model) {
+        return new InputOutputStructureReuseValidator().validate(model);
+    }
 }

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/sections/ShapeMembersSection.java

@@ -25,7 +25,6 @@
  */
 @SmithyUnstableApi
 public record ShapeMembersSection(
-
         DocGenerationContext context,
         Shape shape,
         Collection<MemberShape> members,

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/validation/DocValidationEventDecorator.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.docgen.core.validation;
+
+import software.amazon.smithy.model.validation.Severity;
+import software.amazon.smithy.model.validation.ValidationEvent;
+import software.amazon.smithy.model.validation.ValidationEventDecorator;
+import software.amazon.smithy.utils.SmithyInternalApi;
+
+/**
+ * Adds context to validation events describing how they impact docs.
+ */
+@SmithyInternalApi
+public class DocValidationEventDecorator implements ValidationEventDecorator {
+    private static final String REUSE_DOCUMENTATION_CONTEXT = """
+            Additionally, reusing your input and output structures can make your \
+            documentation confusing for customers, because they'll see those \
+            structures both as the inputs or outputs of your operation and as \
+            standalone structures. This can be particularly confusing if not all of \
+            your operation inputs and outputs do this.""";
+
+    @Override
+    public boolean canDecorate(ValidationEvent event) {
+        return event.containsId("InputOutputStructureReuse");
+    }
+
+    @Override
+    public ValidationEvent decorate(ValidationEvent event) {
+        return event.toBuilder()
+                .message(event.getMessage() + " " + REUSE_DOCUMENTATION_CONTEXT)
+                .severity(Severity.DANGER)
+                .build();
+    }
+}