.

Author: spirit-at-canva

commonmark/src/main/java/org/commonmark/node/NodeTraversal.java

@@ -0,0 +1,89 @@
+package org.commonmark.node;
+
+import java.util.Objects;
+
+/**
+ * Immutable configuration for limiting node traversal depth.
+ * <p>
+ * Traversal limits are enforced by {@link AbstractVisitor#visitChildren(Node)} and renderer recursion through the
+ * public renderer contexts. Helper traversals outside those entry points need to opt in explicitly.
+ */
+public final class NodeTraversal {
+
+    public enum LimitExceededBehavior {
+        FAIL_FAST,
+        SUCCEED_LOSSY
+    }
+
+    private static final NodeTraversal UNLIMITED = new NodeTraversal(null, null);
+
+    private final Integer maxDepth;
+    private final LimitExceededBehavior limitExceededBehavior;
+
+    private NodeTraversal(Integer maxDepth, LimitExceededBehavior limitExceededBehavior) {
+        this.maxDepth = maxDepth;
+        this.limitExceededBehavior = limitExceededBehavior;
+    }
+
+    public static NodeTraversal unlimited() {
+        return UNLIMITED;
+    }
+
+    public static NodeTraversal failFast(int maxDepth) {
+        return limited(maxDepth, LimitExceededBehavior.FAIL_FAST);
+    }
+
+    public static NodeTraversal succeedLossy(int maxDepth) {
+        return limited(maxDepth, LimitExceededBehavior.SUCCEED_LOSSY);
+    }
+
+    public boolean isUnlimited() {
+        return maxDepth == null;
+    }
+
+    /**
+     * @return the inclusive max depth, or {@code null} if this traversal is unlimited
+     */
+    public Integer getMaxDepth() {
+        return maxDepth;
+    }
+
+    /**
+     * @return the behavior when the depth limit is exceeded, or {@code null} if this traversal is unlimited
+     */
+    public LimitExceededBehavior getLimitExceededBehavior() {
+        return limitExceededBehavior;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof NodeTraversal)) {
+            return false;
+        }
+        NodeTraversal that = (NodeTraversal) o;
+        return Objects.equals(maxDepth, that.maxDepth) && limitExceededBehavior == that.limitExceededBehavior;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(maxDepth, limitExceededBehavior);
+    }
+
+    @Override
+    public String toString() {
+        if (isUnlimited()) {
+            return "NodeTraversal.unlimited()";
+        }
+        return "NodeTraversal." + (limitExceededBehavior == LimitExceededBehavior.FAIL_FAST ? "failFast(" : "succeedLossy(") + maxDepth + ")";
+    }
+
+    private static NodeTraversal limited(int maxDepth, LimitExceededBehavior limitExceededBehavior) {
+        if (maxDepth < 0) {
+            throw new IllegalArgumentException("maxDepth must be >= 0");
+        }
+        return new NodeTraversal(maxDepth, Objects.requireNonNull(limitExceededBehavior, "limitExceededBehavior must not be null"));
+    }
+}

commonmark/src/main/java/org/commonmark/node/NodeTraversalLimitExceededException.java

@@ -0,0 +1,24 @@
+package org.commonmark.node;
+
+/**
+ * Thrown when a traversal attempts to descend beyond its configured max depth.
+ */
+public final class NodeTraversalLimitExceededException extends RuntimeException {
+
+    private final int maxDepth;
+    private final int attemptedDepth;
+
+    public NodeTraversalLimitExceededException(int maxDepth, int attemptedDepth) {
+        super("Node traversal exceeded max depth of " + maxDepth + " when attempting to visit child depth " + attemptedDepth);
+        this.maxDepth = maxDepth;
+        this.attemptedDepth = attemptedDepth;
+    }
+
+    public int getMaxDepth() {
+        return maxDepth;
+    }
+
+    public int getAttemptedDepth() {
+        return attemptedDepth;
+    }
+}