fix(core): prevent varargs null poisoning and empty string edge cases

This commit hardens the DSL's fail-fast capabilities for the 1.5.2 release:

- fix(dsl): add strict isEmpty() checks to anythingBut() and literal() to prevent runtime PatternSyntaxException
- fix(dsl): add internal loop validations in anyOf(), group(), and filteringWith() to prevent delayed NPEs from varargs
- refactor(core): remove redundant static factory method in NamedCapture
- docs(api): align Javadoc for ConnectorStep, QuantifierStep, and TypeStep with the current architecture
- docs(api): add missing lookahead/lookbehind examples in SiftPatterns
- test: add comprehensive JUnit 5 coverage for all new exception scenarios
- docs: update README with 1.5.1/1.5.2 bumps, null-safety feature, and Scarf telemetry

Author: Mirkoddd

README.md

@@ -1,7 +1,5 @@
 # Sift
-<img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=e931dfa9-02e9-406d-bde7-56f9e0000464"  alt=""/>
-
-[![sift-core](https://img.shields.io/maven-central/v/com.mirkoddd/sift-core?label=sift-core)](https://central.sonatype.com/artifact/com.mirkoddd/sift-core)
+<img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=e931dfa9-02e9-406d-bde7-56f9e0000464"  alt=""/>[![sift-core](https://img.shields.io/maven-central/v/com.mirkoddd/sift-core?label=sift-core)](https://central.sonatype.com/artifact/com.mirkoddd/sift-core)
 [![sift-annotations](https://img.shields.io/maven-central/v/com.mirkoddd/sift-annotations?label=sift-annotations)](https://central.sonatype.com/artifact/com.mirkoddd/sift-annotations)
 [![Java 8+](https://img.shields.io/badge/Java-8+-blue.svg)](https://adoptium.net/) [![Tests](https://github.com/mirkoddd/Sift/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/mirkoddd/Sift/actions)
 [![Coverage](https://raw.githubusercontent.com/mirkoddd/Sift/main/.github/badges/jacoco.svg)](https://github.com/mirkoddd/Sift/actions)
@@ -22,7 +20,7 @@ Add Sift to your project dependencies:
 **Maven:**
 
 ```XML
-   <!-- Replace <latest-version> with the version shown in the Maven Central badge above -->
+<!-- Replace <latest-version> with the version shown in the Maven Central badge above -->
 <dependency>
     <groupId>com.mirkoddd</groupId>
     <artifactId>sift-core</artifactId>
@@ -39,12 +37,12 @@ Add Sift to your project dependencies:
 
 ```Groovy
     // Replace <latest-version> with the version shown in the Maven Central badge above
-   
-    // Core Engine: Fluent API for Regex generation (Zero external dependencies)
-    implementation 'com.mirkoddd:sift-core:<latest-version>'
-    
-    // Optional: Integration with Jakarta Validation / Hibernate Validator
-    implementation 'com.mirkoddd:sift-annotations:<latest-version>'
+
+// Core Engine: Fluent API for Regex generation (Zero external dependencies)
+implementation 'com.mirkoddd:sift-core:<latest-version>'
+
+// Optional: Integration with Jakarta Validation / Hibernate Validator
+implementation 'com.mirkoddd:sift-annotations:<latest-version>'
  ```   
 ## Compatibility
 
@@ -73,12 +71,9 @@ However, the internal codebase and test suite utilize modern **Java 17** feature
 
 Forget about counting backslashes or memorizing obscure symbols. Sift guides your hand using your IDE's auto-completion.
 
-```Java
-
-    import static com.mirkoddd.sift.core.Sift.fromStart;
-    
+```Java    
     // Goal: Match an international username securely
-    String regex = fromStart()
+    String regex = Sift.fromStart()
         .exactly(1).unicodeLettersUppercaseOnly() // Must start with an uppercase letter
         .then()
         .between(3, 15).unicodeWordCharacters().withoutBacktracking() // Secure against ReDoS
@@ -87,8 +82,8 @@ Forget about counting backslashes or memorizing obscure symbols. Sift guides you
         .andNothingElse()
         .shake(); 
 
-    // Result: ^\p{Lu}[\p{L}\p{Nd}_]{3,15}+[0-9]?$
-    
+    // Result: ^[\p{Lu}][\p{L}\p{Nd}_]{3,15}+[0-9]?$
+
 ```
 
 # 2. Seamless Jakarta Validation
@@ -97,29 +92,29 @@ Stop duplicating regex logic in your DTOs. Centralize your rules and reuse them
 
 ```Java
 
-    // 1. Define your reusable rule (e.g., matching "PROMO123")
-    public class PromoCodeRule implements SiftRegexProvider {
-        
-        public String getRegex() {
-            return Sift.fromStart()
+// 1. Define your reusable rule (e.g., matching "PROMO123")
+public class PromoCodeRule implements SiftRegexProvider {
+
+    public String getRegex() {
+        return Sift.fromStart()
                 .atLeast(4).letters()
                 .then()
                 .exactly(3).digits()
                 .andNothingElse()
                 .shake();
-        }
     }
-    
-    // 2. Apply it to your models with Type-Safe Flags
-    public record ApplyPromoRequest(
+}
+
+// 2. Apply it to your models with Type-Safe Flags
+public record ApplyPromoRequest(
         @SiftMatch(
-            value = PromoCodeRule.class, 
-            flags = {SiftMatchFlag.CASE_INSENSITIVE}, // Allows "promo123" to pass
-            message = "Invalid promo code format"
+                value = PromoCodeRule.class,
+                flags = {SiftMatchFlag.CASE_INSENSITIVE}, // Allows "promo123" to pass
+                message = "Invalid promo code format"
         )
         String promoCode
-    ) {}
-    
+) {}
+
 ```
 
 *Sift compiles the Pattern only once during initialization, ensuring zero performance overhead during validation.*

build.gradle

@@ -1,6 +1,6 @@
 allprojects {
     group = 'com.mirkoddd'
-    version = '1.5.1'
+    version = '1.5.2'
 
     repositories {
         mavenCentral()

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

@@ -51,8 +51,4 @@ public String getName() {
     public SiftPattern getPattern() {
         return pattern;
     }
-
-    static NamedCapture create(GroupName name, SiftPattern pattern) {
-        return new NamedCapture(name, pattern);
-    }
 }

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

@@ -60,6 +60,11 @@ private Sift() {
     public static SiftStarter filteringWith(SiftGlobalFlag flag, SiftGlobalFlag... flags) {
         Objects.requireNonNull(flag, "Primary flag cannot be null");
         Objects.requireNonNull(flags, "Additional flags array cannot be null");
+
+        for (SiftGlobalFlag f : flags) {
+            Objects.requireNonNull(f, "Additional flag cannot be null");
+        }
+
         SiftGlobalFlag[] allFlags = new SiftGlobalFlag[flags.length + 1];
         allFlags[0] = flag;
         System.arraycopy(flags, 0, allFlags, 1, flags.length);

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

@@ -31,7 +31,8 @@
  */
 public final class SiftPatterns {
 
-    private SiftPatterns() {}
+    private SiftPatterns() {
+    }
 
     /**
      * Creates a pattern that matches ANY ONE of the provided options (Logical OR).
@@ -49,6 +50,10 @@ public static SiftPattern anyOf(SiftPattern option1, SiftPattern option2, SiftPa
         Objects.requireNonNull(option2, "Second option cannot be null");
         Objects.requireNonNull(additionalOptions, "Additional options array cannot be null");
 
+        for (SiftPattern opt : additionalOptions) {
+            Objects.requireNonNull(opt, "Additional option cannot be null");
+        }
+
         return () -> {
             StringBuilder sb = new StringBuilder();
             sb.append(RegexSyntax.NON_CAPTURING_GROUP_OPEN);
@@ -85,6 +90,16 @@ public static SiftPattern capture(SiftPattern pattern) {
      * Creates a <b>Positive Lookahead</b> {@code (?=...)}.
      * <p>
      * Asserts that the given pattern CAN be matched next, but does not consume any characters.
+     * <br><b>Example:</b>
+     * <pre>{@code
+     * // Match "test" only if followed by "123", without consuming "123"
+     * String regex = Sift.fromAnywhere()
+     *         .pattern(literal("test"))
+     *         .followedBy(positiveLookahead(literal("123")))
+     *         .shake();
+     * // Result: test(?=123)
+     * // "test123" matches "test" at position 0-4 (doesn't consume "123")
+     * }</pre>
      *
      * @param pattern The pattern that must follow.
      * @return A SiftPattern representing the positive lookahead.
@@ -98,6 +113,16 @@ public static SiftPattern positiveLookahead(SiftPattern pattern) {
      * Creates a <b>Negative Lookahead</b> {@code (?!...)}.
      * <p>
      * Asserts that the given pattern CANNOT be matched next, and does not consume any characters.
+     * <br><b>Example:</b>
+     * <pre>{@code
+     * // Match "test" only if NOT followed by "123"
+     * String regex = Sift.fromAnywhere()
+     *         .pattern(literal("test"))
+     *         .followedBy(negativeLookahead(literal("123")))
+     *         .shake();
+     * // Result: test(?!123)
+     * // "test999" matches "test", but "test123" fails entirely
+     * }</pre>
      *
      * @param pattern The pattern that must not follow.
      * @return A SiftPattern representing the negative lookahead.
@@ -111,6 +136,16 @@ public static SiftPattern negativeLookahead(SiftPattern pattern) {
      * Creates a <b>Positive Lookbehind</b> {@code (?<=...)}.
      * <p>
      * Asserts that the given pattern CAN be matched immediately before the current position.
+     * <br><b>Example:</b>
+     * <pre>{@code
+     * // Match "123" only if immediately preceded by "EUR"
+     * String regex = Sift.fromAnywhere()
+     *         .pattern(positiveLookbehind(literal("EUR")))
+     *         .followedBy(literal("123"))
+     *         .shake();
+     * // Result: (?<=EUR)123
+     * // Matches "123" in "EUR123", but fails in "USD123"
+     * }</pre>
      *
      * @param pattern The pattern that must precede.
      * @return A SiftPattern representing the positive lookbehind.
@@ -124,6 +159,16 @@ public static SiftPattern positiveLookbehind(SiftPattern pattern) {
      * Creates a <b>Negative Lookbehind</b> {@code (?<!...)}.
      * <p>
      * Asserts that the given pattern CANNOT be matched immediately before the current position.
+     * <br><b>Example:</b>
+     * <pre>{@code
+     * // Match "123" only if NOT preceded by "EUR"
+     * String regex = Sift.fromAnywhere()
+     *         .pattern(negativeLookbehind(literal("EUR")))
+     *         .followedBy(literal("123"))
+     *         .shake();
+     * // Result: (?<!EUR)123
+     * // Matches "123" in "USD123", but fails in "EUR123"
+     * }</pre>
      *
      * @param pattern The pattern that must not precede.
      * @return A SiftPattern representing the negative lookbehind.
@@ -143,11 +188,11 @@ 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).
-     * */
+     */
     public static NamedCapture capture(String groupName, SiftPattern pattern) {
         Objects.requireNonNull(pattern, "Pattern to capture cannot be null");
         GroupName validatedName = GroupName.of(groupName);
-        return NamedCapture.create(validatedName, pattern);
+        return new NamedCapture(validatedName, pattern);
     }
 
     /**
@@ -164,6 +209,10 @@ 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");
 
+        for (SiftPattern opt : then) {
+            Objects.requireNonNull(opt, "Additional option cannot be null");
+        }
+
         return () -> {
             StringBuilder sb = new StringBuilder();
             sb.append(RegexSyntax.NON_CAPTURING_GROUP_OPEN);
@@ -190,6 +239,11 @@ public static SiftPattern group(SiftPattern first, SiftPattern... then) {
      */
     public static SiftPattern literal(String text) {
         Objects.requireNonNull(text, "Literal text cannot be null");
+
+        if (text.isEmpty()) {
+            throw new IllegalArgumentException("Literal text cannot be empty. Use zero-width assertions if intentional.");
+        }
+
         return () -> {
             StringBuilder sb = new StringBuilder();
             RegexEscaper.escapeString(text, sb);
@@ -209,6 +263,11 @@ public static SiftPattern literal(String text) {
      */
     public static SiftPattern anythingBut(String chars) {
         Objects.requireNonNull(chars, "Excluded characters string cannot be null");
+
+        if (chars.isEmpty()) {
+            throw new IllegalArgumentException("Excluded characters string cannot be empty");
+        }
+
         return () -> {
             StringBuilder sb = new StringBuilder();
             sb.append(RegexSyntax.CLASS_OPEN);

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

@@ -23,8 +23,9 @@
  * <ul>
  * <li>Refine the current token (using {@code including} or {@code excluding}).</li>
  * <li>Append a new literal or pattern (using {@code followedBy(...)}).</li>
- * <li>Transition back to a quantifier for a new token (using {@code followedBy()}).</li>
- * <li>Finalize the regex structure (using {@code untilEnd()}).</li>
+ * <li>Transition back to a quantifier for a new token (using {@code then()}).</li>
+ * <li>Assert a word boundary (using {@code wordBoundary()}).</li>
+ * <li>Finalize the regex structure (using {@code andNothingElse()}).</li>
  * </ul>
  */
 public interface ConnectorStep extends SiftPattern {

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

@@ -18,16 +18,17 @@
 import com.mirkoddd.sift.core.NamedCapture;
 
 /**
- * Defines <b>HOW MANY TIMES</b> the next element should appear.
+ * Defines <b>HOW MANY TIMES</b> the next element should appear, or injects structural elements.
  * <p>
  * This interface extends {@link TypeStep}, which allows for a concise syntax:
  * if no quantifier is explicitly chosen, it defaults to matching <b>exactly once</b>.
  * <p>
  * <b>Flow Examples:</b>
  * <ul>
- * <li>Explicit: {@code .exactly(3).digits()}</li>
- * <li>Implicit: {@code .digits()} (implies exactly 1)</li>
- * <li>Sugar: {@code .withOptional(pattern)} (applies quantifier directly to argument)</li>
+ * <li>Explicit Quantity: {@code .exactly(3).digits()}</li>
+ * <li>Implicit Quantity: {@code .digits()} (implies exactly 1)</li>
+ * <li>Named Capture: {@code .namedCapture(groupDefinition)} (injects a named group)</li>
+ * <li>Backreference: {@code .backreference(groupDefinition)} (references a previous group)</li>
  * </ul>
  */
 public interface QuantifierStep extends TypeStep<ConnectorStep> {

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

@@ -18,12 +18,16 @@
 /**
  * Defines the <b>TYPE</b> of character or pattern to match.
  * <p>
- * This interface represents the state immediately after a quantifier has been set
- * (e.g., {@code exactly(3)} or {@code oneOrMore()}). The method selected here defines
- * <i>what</i> exactly applies to that quantifier.
+ * This interface represents the state where the exact token to be matched is selected.
+ * It can be reached in two ways:
+ * <ul>
+ * <li><b>Explicitly:</b> Immediately after a quantifier has been set (e.g., {@code .exactly(3).digits()}).</li>
+ * <li><b>Implicitly:</b> Directly from a state that expects a token (e.g., {@code .digits()}), which defaults to matching exactly once.</li>
+ * </ul>
  * <p>
  * Selecting a type consumes the pending quantifier and transitions the builder to the
- * {@link ConnectorStep}.
+ * next structural link (either a {@link ConnectorStep} or a {@link VariableConnectorStep},
+ * depending on the generic type {@code T}).
  */
 public interface TypeStep<T extends ConnectorStep> {