fix(core): enforce absolute boundary validation in factories

- Prevented composition of absolute anchored patterns in SiftPatterns.
- Sealed nested group assembly to avoid silent logical boundaries collision.

Author: Mirkoddd

sift-core/src/main/java/com/mirkoddd/sift/core/PatternAssembler.java

@@ -43,7 +43,7 @@ private enum QuantifierModifier {
     private boolean canModifyMain = false;
     private final Set<String> registeredGroups = new HashSet<>();
     private final Set<String> requiredBackreferences = new HashSet<>();
-
+    private boolean containsAbsoluteAnchor = false;
     PatternAssembler() {
     }
 
@@ -63,12 +63,21 @@ Set<String> getRequiredBackreferences() {
         return requiredBackreferences;
     }
 
+    public boolean isContainsAbsoluteAnchor() {
+        return containsAbsoluteAnchor;
+    }
+
     void setQuantifier(String quantifier) {
         this.currentQuantifier = quantifier;
     }
 
     void addAnchor(String anchor) {
         flush();
+
+        if (RegexSyntax.START_OF_LINE.equals(anchor) || RegexSyntax.END_OF_LINE.equals(anchor)){
+            containsAbsoluteAnchor = true;
+        }
+
         mainPattern.append(anchor);
     }
 
@@ -145,6 +154,12 @@ void addCharacter(char literal) {
     }
 
     void addPattern(SiftPattern pattern) {
+        if (pattern.hasAbsoluteBoundaries()) {
+            throw new IllegalStateException(
+                    "Composition Error: Cannot embed a pattern that contains absolute boundaries (like fromStart() or andNothingElse()). " +
+                            "Reusable blocks must be created using fromAnywhere()."
+            );
+        }
         flush();
         extractAndCheckGroupsAndRequirements(pattern, null);
 
@@ -277,6 +292,7 @@ PatternAssembler copy() {
         clone.canModifyMain = this.canModifyMain;
         clone.registeredGroups.addAll(this.registeredGroups);
         clone.requiredBackreferences.addAll(this.requiredBackreferences);
+        clone.containsAbsoluteAnchor = this.containsAbsoluteAnchor;
         return clone;
     }
 

sift-core/src/main/java/com/mirkoddd/sift/core/SiftConnector.java

@@ -131,6 +131,11 @@ public void preventExternalImplementation(InternalToken token) {
         }
     }
 
+    @Override
+    public boolean hasAbsoluteBoundaries() {
+        return assembler.isContainsAbsoluteAnchor();
+    }
+
     @Override
     public String toString() {
         return shake();

sift-core/src/main/java/com/mirkoddd/sift/core/SiftPatterns.java

@@ -46,14 +46,21 @@ private SiftPatterns() {
      * @param option2           The second mandatory alternative.
      * @param additionalOptions Any further alternative patterns.
      * @return A composable {@link SiftPattern} representing the logical OR.
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
      */
     public static SiftPattern anyOf(SiftPattern option1, SiftPattern option2, SiftPattern... additionalOptions) {
         Objects.requireNonNull(option1, "First option cannot be null");
         Objects.requireNonNull(option2, "Second option cannot be null");
         Objects.requireNonNull(additionalOptions, "Additional options array cannot be null");
 
+        requireUnanchored(option1);
+        requireUnanchored(option2);
+
         for (SiftPattern opt : additionalOptions) {
             Objects.requireNonNull(opt, "Additional option cannot be null");
+            requireUnanchored(opt);
         }
 
         return memoize(() -> {
@@ -80,6 +87,9 @@ public static SiftPattern anyOf(SiftPattern option1, SiftPattern option2, SiftPa
      * @param patterns A list of SiftPatterns.
      * @return A SiftPattern combining the provided options.
      * @throws IllegalArgumentException if the list is null or empty.
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
      */
     public static SiftPattern anyOf(java.util.List<? extends SiftPattern> patterns) {
         if (patterns == null || patterns.isEmpty()) {
@@ -89,6 +99,10 @@ public static SiftPattern anyOf(java.util.List<? extends SiftPattern> patterns)
             return patterns.get(0); // QoL Optimization: no need to wrap a single element
         }
 
+        for (SiftPattern pattern: patterns) {
+            requireUnanchored(pattern);
+        }
+
         return memoize(() -> {
             StringBuilder sb = new StringBuilder();
             sb.append(RegexSyntax.NON_CAPTURING_GROUP_OPEN);
@@ -117,9 +131,13 @@ public static SiftPattern anyOf(java.util.List<? extends SiftPattern> patterns)
      *
      * @param pattern The pattern to capture.
      * @return A SiftPattern wrapped in parentheses.
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
      */
     public static SiftPattern capture(SiftPattern pattern) {
         Objects.requireNonNull(pattern, "Pattern to capture cannot be null");
+        requireUnanchored(pattern);
         return memoize(() -> RegexSyntax.GROUP_OPEN + pattern.shake() + RegexSyntax.GROUP_CLOSE);
     }
 
@@ -140,9 +158,13 @@ public static SiftPattern capture(SiftPattern pattern) {
      *
      * @param pattern The pattern that must follow.
      * @return A SiftPattern representing the positive lookahead.
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
      */
     public static SiftPattern positiveLookahead(SiftPattern pattern) {
         Objects.requireNonNull(pattern, "Lookahead pattern cannot be null");
+        requireUnanchored(pattern);
         return memoize(() -> RegexSyntax.POSITIVE_LOOKAHEAD_OPEN + pattern.shake() + RegexSyntax.GROUP_CLOSE);
     }
 
@@ -163,9 +185,13 @@ public static SiftPattern positiveLookahead(SiftPattern pattern) {
      *
      * @param pattern The pattern that must not follow.
      * @return A SiftPattern representing the negative lookahead.
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
      */
     public static SiftPattern negativeLookahead(SiftPattern pattern) {
         Objects.requireNonNull(pattern, "Lookahead pattern cannot be null");
+        requireUnanchored(pattern);
         return memoize(() -> RegexSyntax.NEGATIVE_LOOKAHEAD_OPEN + pattern.shake() + RegexSyntax.GROUP_CLOSE);
     }
 
@@ -186,9 +212,13 @@ public static SiftPattern negativeLookahead(SiftPattern pattern) {
      *
      * @param pattern The pattern that must precede.
      * @return A SiftPattern representing the positive lookbehind.
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
      */
     public static SiftPattern positiveLookbehind(SiftPattern pattern) {
         Objects.requireNonNull(pattern, "Lookbehind pattern cannot be null");
+        requireUnanchored(pattern);
         return memoize(() -> RegexSyntax.POSITIVE_LOOKBEHIND_OPEN + pattern.shake() + RegexSyntax.GROUP_CLOSE);
     }
 
@@ -209,9 +239,13 @@ public static SiftPattern positiveLookbehind(SiftPattern pattern) {
      *
      * @param pattern The pattern that must not precede.
      * @return A SiftPattern representing the negative lookbehind.
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
      */
     public static SiftPattern negativeLookbehind(SiftPattern pattern) {
         Objects.requireNonNull(pattern, "Lookbehind pattern cannot be null");
+        requireUnanchored(pattern);
         return memoize(() -> RegexSyntax.NEGATIVE_LOOKBEHIND_OPEN + pattern.shake() + RegexSyntax.GROUP_CLOSE);
     }
 
@@ -225,9 +259,13 @@ public static SiftPattern negativeLookbehind(SiftPattern pattern) {
      * @param pattern   The pattern to capture within this group.
      * @return A NamedCapture definition.
      * @throws IllegalArgumentException if {@code groupName} is null, empty, starts with a digit, or contains non-alphanumeric characters (e.g., spaces, underscores, or symbols).
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
      */
     public static NamedCapture capture(String groupName, SiftPattern pattern) {
         Objects.requireNonNull(pattern, "Pattern to capture cannot be null");
+        requireUnanchored(pattern);
         GroupName validatedName = GroupName.of(groupName);
         return new NamedCapture(validatedName, pattern);
     }
@@ -241,13 +279,19 @@ public static NamedCapture capture(String groupName, SiftPattern pattern) {
      * @param first The first required pattern.
      * @param then  Optional additional patterns to include in the same group.
      * @return A SiftPattern representing the concatenated non-capturing group.
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
      */
     public static SiftPattern group(SiftPattern first, SiftPattern... then) {
         Objects.requireNonNull(first, "First pattern in group cannot be null");
         Objects.requireNonNull(then, "Additional patterns array cannot be null");
 
+        requireUnanchored(first);
+
         for (SiftPattern opt : then) {
             Objects.requireNonNull(opt, "Additional option cannot be null");
+            requireUnanchored(opt);
         }
 
         return memoize(() -> {
@@ -370,6 +414,25 @@ public Pattern sieve() {
             public void preventExternalImplementation(InternalToken unused) {
                 // unused intentionally to prevent external implementations
             }
+
+            @Override
+            public boolean hasAbsoluteBoundaries() {
+                // SiftPatterns components are explicitly validated to be unanchored
+                // before this memoized instance is created.
+                return false;
+            }
         };
     }
+
+    /**
+     * Internal security check to prevent nesting of anchored patterns.
+     */
+    private static void requireUnanchored(SiftPattern pattern) {
+        if (pattern.hasAbsoluteBoundaries()) {
+            throw new IllegalStateException(
+                    "Composition Error: Cannot embed a pattern that contains absolute boundaries " +
+                            "(like fromStart() or andNothingElse()). Reusable blocks must be unanchored."
+            );
+        }
+    }
 }

sift-core/src/main/java/com/mirkoddd/sift/core/dsl/ConnectorStep.java

@@ -59,6 +59,9 @@ public interface ConnectorStep extends SiftPattern {
      * @param pattern            The first mandatory sub-pattern to append.
      * @param additionalPatterns Any further sub-patterns to append in the specified order.
      * @return The current connector step, allowing immediate chaining.
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
      */
     ConnectorStep followedBy(SiftPattern pattern, SiftPattern... additionalPatterns);
 

sift-core/src/main/java/com/mirkoddd/sift/core/dsl/SiftPattern.java

@@ -84,6 +84,11 @@ public void preventExternalImplementation(InternalToken unused) {
                 // Intentionally left blank. Ensures this anonymous class
                 // complies with the internal Sift interface contract.
             }
+
+            @Override
+            public boolean hasAbsoluteBoundaries() {
+                return SiftPattern.this.hasAbsoluteBoundaries();
+            }
         };
     }
 
@@ -126,4 +131,12 @@ default boolean matches(CharSequence input) {
      * <b>Strictly for internal Sift API use. Do not call or implement.</b>
      */
     void preventExternalImplementation(InternalToken token);
+
+    /**
+     * Indicates whether this pattern contains absolute boundaries (^ or $).
+     * Patterns with absolute boundaries cannot be embedded inside other patterns.
+     */
+    default boolean hasAbsoluteBoundaries() {
+        return false;
+    }
 }

sift-core/src/main/java/com/mirkoddd/sift/core/dsl/TypeStep.java

@@ -62,7 +62,10 @@ public interface TypeStep<T extends ConnectorStep, C extends CharacterClassConne
      *
      * @param pattern The sub-pattern to apply the quantifier to.
      * @return The standard connector step to continue building.
-     */
+     * @throws IllegalStateException if the provided pattern contains absolute boundaries
+     * (e.g., created with {@code fromStart()} or closed with {@code andNothingElse()}).
+     * Reusable blocks must be unanchored.
+     * */
     T pattern(SiftPattern pattern);
 
     /**

sift-core/src/test/java/com/mirkoddd/sift/core/SiftPatternsTest.java

@@ -393,4 +393,19 @@ void testPatternMatchesConvenienceMethod() {
         assertTrue(pattern.matches(sbInput),
                 "Should natively support other CharSequence implementations like StringBuilder without allocations");
     }
+
+    @Test
+    @DisplayName("Should throw exception when passing anchored pattern to SiftPatterns factories")
+    void shouldThrowWhenPassingAnchoredPatternToFactories() {
+        SiftPattern radioActivePattern = Sift.fromStart().exactly(3).digits();
+
+        IllegalStateException exception = assertThrows(IllegalStateException.class, () ->
+                SiftPatterns.positiveLookahead(radioActivePattern));
+
+        assertTrue(exception.getMessage().contains("absolute boundaries"),
+                "Exception message should indicate the boundary violation.");
+
+        assertThrows(IllegalStateException.class, () ->
+                SiftPatterns.capture("invalidGroup", radioActivePattern));
+    }
 }