Merge pull request #166 from nulab/move-guess-interface

refactor: Deprecate com.nulabinc.zxcvbn.Guess and introduce new interface in com.nulabinc.zxcvbn.guesses

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

@@ -3,13 +3,38 @@
 import com.nulabinc.zxcvbn.matchers.Match;
 import java.util.Calendar;
 
+/**
+ * Represents a strategy for estimating the number of guesses required to crack a given {@link
+ * Match}.
+ *
+ * <p>Implementations of this interface are expected to evaluate the strength or weakness of a
+ * matched pattern within a password and return an estimated guess number.
+ *
+ * @deprecated This interface is deprecated. Use {@link com.nulabinc.zxcvbn.guesses.Guess} instead.
+ * @see Match
+ */
 public interface Guess {
 
-  public static final int BRUTEFORCE_CARDINALITY = 10;
-  public static final int MIN_SUBMATCH_GUESSES_SINGLE_CHAR = 10;
-  public static final int MIN_SUBMATCH_GUESSES_MULTI_CHAR = 50;
-  public static final int MIN_YEAR_SPACE = 20;
-  public static final int REFERENCE_YEAR = Calendar.getInstance().get(Calendar.YEAR);
+  /** Cardinality used in brute force attacks. */
+  int BRUTEFORCE_CARDINALITY = 10;
 
-  public double exec(Match match);
+  /** Minimum number of guesses when the sub-match contains a single character. */
+  int MIN_SUBMATCH_GUESSES_SINGLE_CHAR = 10;
+
+  /** Minimum number of guesses when the sub-match contains multiple characters. */
+  int MIN_SUBMATCH_GUESSES_MULTI_CHAR = 50;
+
+  /** The minimum range of years to be considered when evaluating date-based patterns. */
+  int MIN_YEAR_SPACE = 20;
+
+  /** Reference year used for date-based pattern evaluations. */
+  int REFERENCE_YEAR = Calendar.getInstance().get(Calendar.YEAR);
+
+  /**
+   * Evaluates the given {@link Match} and estimates the number of guesses required to crack it.
+   *
+   * @param match the matched pattern to evaluate.
+   * @return the estimated number of guesses required to crack the given match.
+   */
+  double exec(Match match);
 }

src/main/java/com/nulabinc/zxcvbn/guesses/BaseGuess.java

@@ -1,7 +1,6 @@
 package com.nulabinc.zxcvbn.guesses;
 
 import com.nulabinc.zxcvbn.Context;
-import com.nulabinc.zxcvbn.Guess;
 
 public abstract class BaseGuess implements Guess {
 

src/main/java/com/nulabinc/zxcvbn/guesses/EstimateGuess.java

@@ -1,7 +1,6 @@
 package com.nulabinc.zxcvbn.guesses;
 
 import com.nulabinc.zxcvbn.Context;
-import com.nulabinc.zxcvbn.Guess;
 import com.nulabinc.zxcvbn.Pattern;
 import com.nulabinc.zxcvbn.Scoring;
 import com.nulabinc.zxcvbn.matchers.Match;

src/main/java/com/nulabinc/zxcvbn/guesses/Guess.java

@@ -0,0 +1,39 @@
+package com.nulabinc.zxcvbn.guesses;
+
+import com.nulabinc.zxcvbn.matchers.Match;
+import java.util.Calendar;
+
+/**
+ * Represents a strategy for estimating the number of guesses required to crack a given {@link
+ * Match}.
+ *
+ * <p>Implementations of this interface are expected to evaluate the strength or weakness of a
+ * matched pattern within a password and return an estimated guess number.
+ *
+ * @see Match
+ */
+public interface Guess {
+
+  /** Cardinality used in brute force attacks. */
+  int BRUTEFORCE_CARDINALITY = 10;
+
+  /** Minimum number of guesses when the sub-match contains a single character. */
+  int MIN_SUBMATCH_GUESSES_SINGLE_CHAR = 10;
+
+  /** Minimum number of guesses when the sub-match contains multiple characters. */
+  int MIN_SUBMATCH_GUESSES_MULTI_CHAR = 50;
+
+  /** The minimum range of years to be considered when evaluating date-based patterns. */
+  int MIN_YEAR_SPACE = 20;
+
+  /** Reference year used for date-based pattern evaluations. */
+  int REFERENCE_YEAR = Calendar.getInstance().get(Calendar.YEAR);
+
+  /**
+   * Evaluates the given {@link Match} and estimates the number of guesses required to crack it.
+   *
+   * @param match the matched pattern to evaluate.
+   * @return the estimated number of guesses required to crack the given match.
+   */
+  double exec(Match match);
+}