Allow for moving truncation into the implementing API

pom.xml

@@ -19,7 +19,7 @@
 
   <properties>
     <java.level>8</java.level>
-    <revision>1.2.1</revision>
+    <revision>1.3.0</revision>
     <changelist>-SNAPSHOT</changelist>
 
     <!-- Jenkins Plug-in Dependencies Versions -->

src/main/java/io/jenkins/plugins/checks/api/ChecksOutput.java

@@ -5,20 +5,20 @@
 import java.util.List;
 import java.util.Optional;
 
-import static java.util.Objects.*;
+import static java.util.Objects.requireNonNull;
 
 /**
  * An output of a check. The output usually contains the most useful information like summary, description,
  * annotations, etc.
  */
 public class ChecksOutput {
     private final String title;
-    private final String summary;
-    private final String text;
+    private final TruncatedString summary;
+    private final TruncatedString text;
     private final List<ChecksAnnotation> annotations;
     private final List<ChecksImage> images;
 
-    private ChecksOutput(final String title, final String summary, final String text,
+    private ChecksOutput(final String title, final TruncatedString summary, final TruncatedString text,
             final List<ChecksAnnotation> annotations, final List<ChecksImage> images) {
         this.title = title;
         this.summary = summary;
@@ -34,7 +34,9 @@ private ChecksOutput(final String title, final String summary, final String text
      *         the source to copy from
      */
     public ChecksOutput(final ChecksOutput that) {
-        this(that.getTitle().orElse(null), that.getSummary().orElse(null), that.getText().orElse(null),
+        this(that.getTitle().orElse(null),
+                that.getSummary().map(TruncatedString::fromString).orElse(null),
+                that.getText().map(TruncatedString::fromString).orElse(null),
                 that.getChecksAnnotations(), that.getChecksImages());
     }
 
@@ -43,11 +45,31 @@ public Optional<String> getTitle() {
     }
 
     public Optional<String> getSummary() {
-        return Optional.ofNullable(summary);
+        return Optional.ofNullable(summary).map(TruncatedString::toString);
+    }
+
+    /**
+     * Get the output summary, truncated by {@link TruncatedString} to maxSize.
+     *
+     * @param maxSize maximum size to truncate summary to.
+     * @return Summary, truncated to maxSize with truncation message if appropriate.
+     */
+    public Optional<String> getSummary(final int maxSize) {
+        return Optional.ofNullable(summary).map(s -> s.build(maxSize));
     }
 
     public Optional<String> getText() {
-        return Optional.ofNullable(text);
+        return Optional.ofNullable(text).map(TruncatedString::toString);
+    }
+
+    /**
+     * Get the output text, truncated by {@link TruncatedString} to maxSize.
+     *
+     * @param maxSize maximum size to truncate text to.
+     * @return Text, truncated to maxSize with truncation message if appropriate.
+     */
+    public Optional<String> getText(final int maxSize) {
+        return Optional.ofNullable(text).map(s -> s.build(maxSize));
     }
 
     public List<ChecksAnnotation> getChecksAnnotations() {
@@ -74,8 +96,8 @@ public String toString() {
      */
     public static class ChecksOutputBuilder {
         private String title;
-        private String summary;
-        private String text;
+        private TruncatedString summary;
+        private TruncatedString text;
         private List<ChecksAnnotation> annotations;
         private List<ChecksImage> images;
 
@@ -114,6 +136,22 @@ public ChecksOutputBuilder withTitle(final String title) {
          */
         @SuppressWarnings("HiddenField") // builder pattern
         public ChecksOutputBuilder withSummary(final String summary) {
+            return withSummary(TruncatedString.fromString(summary));
+        }
+
+        /**
+         * Sets the summary of the check run, using a {@link TruncatedString}.
+         *
+         * <p>
+         *     Note that for the GitHub check runs, the {@code summary} supports Markdown.
+         * <p>
+         *
+         * @param summary
+         *         the summary of the check run as a {@link TruncatedString}
+         * @return this builder
+         */
+        @SuppressWarnings("HiddenField")
+        public ChecksOutputBuilder withSummary(final TruncatedString summary) {
             this.summary = requireNonNull(summary);
             return this;
         }
@@ -131,6 +169,22 @@ public ChecksOutputBuilder withSummary(final String summary) {
          */
         @SuppressWarnings("HiddenField") // builder pattern
         public ChecksOutputBuilder withText(final String text) {
+            return withText(TruncatedString.fromString(text));
+        }
+
+        /**
+         * Adds the details description for a check run, using a {@link TruncatedString}. This parameter supports Markdown.
+         *
+         * <p>
+         *     Note that for a GitHub check run, the {@code text} supports Markdown.
+         * <p>
+         *
+         * @param text
+         *         the details description in Markdown as a {@link TruncatedString}
+         * @return this builder
+         */
+        @SuppressWarnings("HiddenField")
+        public ChecksOutputBuilder withText(final TruncatedString text) {
             this.text = requireNonNull(text);
             return this;
         }

src/main/java/io/jenkins/plugins/checks/api/TruncatedString.java

@@ -0,0 +1,219 @@
+package io.jenkins.plugins.checks.api;
+
+import edu.umd.cs.findbugs.annotations.NonNull;
+
+import java.util.*;
+import java.util.function.BiConsumer;
+import java.util.function.BinaryOperator;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import java.util.stream.Collector;
+
+/**
+ * Utility wrapper that silently truncates output with a message at a certain size.
+ * <p>
+ * The GitHub Checks API has a size limit on text fields. Because it also accepts markdown, it is not trivial to
+ * truncate to the required length as this could lead to unterminated syntax. The use of this class allows for adding
+ * chunks of complete markdown until an overflow is detected, at which point a message will be added and all future
+ * additions will be silently discarded.
+ */
+public class TruncatedString {
+
+    @NonNull
+    private final List<String> chunks;
+    @NonNull
+    private final String truncationText;
+    private final boolean truncateStart;
+    private final boolean chunkOnNewlines;
+
+
+    private TruncatedString(@NonNull final List<String> chunks, @NonNull final String truncationText, final boolean truncateStart, final boolean chunkOnNewlines) {
+        this.chunks = Collections.unmodifiableList(Objects.requireNonNull(chunks));
+        this.truncationText = Objects.requireNonNull(truncationText);
+        this.truncateStart = truncateStart;
+        this.chunkOnNewlines = chunkOnNewlines;
+    }
+
+    /**
+     * Wrap the provided string as a {@link TruncatedString}.
+     *
+     * @param string String to wrap as a {@link TruncatedString}
+     * @return a {@link TruncatedString} wrapping the provided input
+     */
+    static TruncatedString fromString(final String string) {
+        return new Builder().setChunkOnNewlines().addText(string).build();
+    }
+
+    /**
+     * Builds the string without truncation.
+     *
+     * @return A string comprising the joined chunks.
+     */
+    @Override
+    public String toString() {
+        return String.join("", chunks);
+    }
+
+    private List<String> getChunks() {
+        if (chunkOnNewlines) {
+            return Arrays.asList(String.join("", chunks).split("(?<=\r?\n)"));
+        }
+        return new ArrayList<>(chunks);
+    }
+
+    /**
+     * Builds the string such that it does not exceed maxSize, including the truncation string.
+     *
+     * @param maxSize the maximum size of the resultant string.
+     * @return A string comprising as many of the joined chunks that will fit in the given size, plus the truncation
+     * string if truncation was necessary.
+     */
+    public String build(final int maxSize) {
+        List<String> parts = getChunks();
+        if (truncateStart) {
+            Collections.reverse(parts);
+        }
+        List<String> truncatedParts = parts.stream().collect(new Joiner(truncationText, maxSize));
+        if (truncateStart) {
+            Collections.reverse(truncatedParts);
+        }
+        return String.join("", truncatedParts);
+    }
+
+
+    /**
+     * Builder for {@link TruncatedString}.
+     */
+    public static class Builder {
+        private String truncationText = "Output truncated.";
+        private boolean truncateStart = false;
+        private boolean chunkOnNewlines = false;
+        private final List<String> chunks = new ArrayList<>();
+
+        /**
+         * Builds the {@link TruncatedString}.
+         *
+         * @return the build {@link TruncatedString}.
+         */
+        public TruncatedString build() {
+            return new TruncatedString(chunks, truncationText, truncateStart, chunkOnNewlines);
+        }
+
+        /**
+         * Adds a chunk of text to the builder.
+         *
+         * @param text the chunk of text to append to this builder
+         * @return this builder
+         */
+        public Builder addText(@NonNull final String text) {
+            this.chunks.add(Objects.requireNonNull(text));
+            return this;
+        }
+
+        /**
+         * Sets the truncation text.
+         *
+         * @param truncationText the text to append on overflow
+         * @return this builder
+         */
+        @SuppressWarnings("HiddenField")
+        public Builder withTruncationText(@NonNull final String truncationText) {
+            this.truncationText = Objects.requireNonNull(truncationText);
+            return this;
+        }
+
+        /**
+         * Sets truncator to remove excess text from the start, rather than the end.
+         *
+         * @return this builder
+         */
+        public Builder setTruncateStart() {
+            this.truncateStart = true;
+            return this;
+        }
+
+        /**
+         * Sets truncator to chunk on newlines rather than the chunks.
+         *
+         * @return this builder
+         */
+        public Builder setChunkOnNewlines() {
+            this.chunkOnNewlines = true;
+            return this;
+        }
+
+    }
+
+    private static class Joiner implements Collector<String, Joiner.Accumulator, List<String>> {
+
+        private final int maxLength;
+        private final String truncationText;
+
+        Joiner(final String truncationText, final int maxLength) {
+            if (maxLength < truncationText.length()) {
+                throw new IllegalArgumentException("Maximum length is less than truncation text.");
+            }
+            this.truncationText = truncationText;
+            this.maxLength = maxLength;
+        }
+
+        @Override
+        public Supplier<Joiner.Accumulator> supplier() {
+            return Accumulator::new;
+        }
+
+        @Override
+        public BiConsumer<Joiner.Accumulator, String> accumulator() {
+            return Accumulator::add;
+        }
+
+        @Override
+        public BinaryOperator<Accumulator> combiner() {
+            return Accumulator::combine;
+        }
+
+        @Override
+        public Function<Accumulator, List<String>> finisher() {
+            return Accumulator::truncate;
+        }
+
+        @Override
+        public Set<Characteristics> characteristics() {
+            return Collections.emptySet();
+        }
+
+        private class Accumulator {
+            private final List<String> chunks = new ArrayList<>();
+            private int length = 0;
+            private boolean truncated = false;
+
+            Accumulator combine(final Accumulator other) {
+                other.chunks.forEach(this::add);
+                return this;
+            }
+
+            void add(final String chunk) {
+                if (truncated) {
+                    return;
+                }
+                if (length + chunk.length() > maxLength) {
+                    truncated = true;
+                    return;
+                }
+                chunks.add(chunk);
+                length += chunk.length();
+            }
+
+            List<String> truncate() {
+                if (truncated) {
+                    if (length + truncationText.length() > maxLength) {
+                        chunks.remove(chunks.size() - 1);
+                    }
+                    chunks.add(truncationText);
+                }
+                return chunks;
+            }
+        }
+    }
+
+}

src/test/java/io/jenkins/plugins/checks/ArchitectureTest.java

@@ -3,8 +3,10 @@
 import com.tngtech.archunit.junit.AnalyzeClasses;
 import com.tngtech.archunit.junit.ArchTest;
 import com.tngtech.archunit.lang.ArchRule;
+import com.tngtech.archunit.lang.syntax.elements.ClassesShouldConjunction;
 import edu.hm.hafner.util.ArchitectureRules;
 import io.jenkins.plugins.util.PluginArchitectureRules;
+import org.junit.runner.RunWith;
 
 /**
  * Defines several architecture rules for the static analysis model and parsers.
@@ -18,7 +20,8 @@ class ArchitectureTest {
     static final ArchRule NO_JENKINS_INSTANCE_CALL = PluginArchitectureRules.NO_JENKINS_INSTANCE_CALL;
 
     @ArchTest
-    static final ArchRule NO_PUBLIC_TEST_CLASSES = PluginArchitectureRules.NO_PUBLIC_TEST_CLASSES;
+    static final ArchRule NO_PUBLIC_TEST_CLASSES = ((ClassesShouldConjunction) PluginArchitectureRules.NO_PUBLIC_TEST_CLASSES)
+            .andShould().notBeAnnotatedWith(RunWith.class); // Allow for JUnit4 tests.
 
     @ArchTest
     static final ArchRule NO_TEST_API_CALLED = ArchitectureRules.NO_TEST_API_CALLED;