Deprecate com.nulabinc.zxcvbn.Matcher and introduce new interface in …

…com.nulabinc.zxcvbn.matchers

src/main/java/com/nulabinc/zxcvbn/Matcher.java

@@ -3,6 +3,11 @@
 import com.nulabinc.zxcvbn.matchers.Match;
 import java.util.List;
 
+/**
+ * @deprecated This interface is deprecated. Use {@link com.nulabinc.zxcvbn.matchers.Matcher}
+ *     instead.
+ */
+@Deprecated
 public interface Matcher {
-  public List<Match> execute(CharSequence password);
+  List<Match> execute(CharSequence password);
 }

src/main/java/com/nulabinc/zxcvbn/matchers/BaseMatcher.java

@@ -1,7 +1,6 @@
 package com.nulabinc.zxcvbn.matchers;
 
 import com.nulabinc.zxcvbn.Context;
-import com.nulabinc.zxcvbn.Matcher;
 import java.io.Serializable;
 import java.util.Collections;
 import java.util.Comparator;

src/main/java/com/nulabinc/zxcvbn/matchers/Matcher.java

@@ -0,0 +1,21 @@
+package com.nulabinc.zxcvbn.matchers;
+
+import java.util.List;
+
+/**
+ * Represents a matcher responsible for identifying patterns within passwords.
+ *
+ * <p>Implementations of this interface provide specific matching strategies to detect various
+ * patterns such as dictionary words, sequences, and spatial patterns.
+ *
+ * @see Match
+ */
+public interface Matcher {
+  /**
+   * Analyzes the given password and returns a list of detected patterns as {@link Match} objects.
+   *
+   * @param password the password to analyze for patterns.
+   * @return a list of matches identifying patterns found within the password.
+   */
+  List<Match> execute(CharSequence password);
+}

src/main/java/com/nulabinc/zxcvbn/matchers/OmnibusMatcher.java

@@ -1,7 +1,6 @@
 package com.nulabinc.zxcvbn.matchers;
 
 import com.nulabinc.zxcvbn.Context;
-import com.nulabinc.zxcvbn.Matcher;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;