refactor(core): implement value semantics and optimize string analysis

- Implement value semantics using `collection` dependency for core models
- Consolidate character set validation from `ConfigAwarePasswordValidator` into `PolicyValidationMixin`
- Optimize string allocations in `containsAnyOf` by using `String.contains` directly
- Fix `satisfiesPolicy` to evaluate base config even when policy is null
- Add fallback pool size for passwords consisting entirely of unmapped characters
- Align generator interfaces and update related tests

Author: dhruvanbhalara

analysis_options.yaml

@@ -3,7 +3,6 @@ include: package:lints/recommended.yaml
 analyzer:
   exclude:
     - "lib/l10n/*.i18n.dart"
-    -
 linter:
   rules:
     prefer_single_quotes: true

lib/src/config/password_generator_config.dart

@@ -1,3 +1,5 @@
+import 'package:collection/collection.dart';
+
 import '../model/character_set_profile.dart';
 import '../model/password_policy.dart';
 import 'password_generator_config_builder.dart';
@@ -42,7 +44,10 @@ class PasswordGeneratorConfig {
           map['policy'] != null
               ? PasswordPolicy.fromMap(map['policy'] as Map<String, dynamic>)
               : null,
-      extra: (map['extra'] as Map<String, dynamic>?) ?? const {},
+      extra:
+          map['extra'] != null
+              ? Map.unmodifiable(map['extra'] as Map<String, dynamic>)
+              : const {},
     );
   }
 
@@ -83,6 +88,35 @@ class PasswordGeneratorConfig {
   /// Additional configuration parameters for custom strategies.
   final Map<String, dynamic> extra;
 
+  /// Returns a copy of this configuration with the given fields replaced.
+  PasswordGeneratorConfig copyWith({
+    int? length,
+    bool? useUpperCase,
+    bool? useLowerCase,
+    bool? useNumbers,
+    bool? useSpecialChars,
+    bool? excludeAmbiguousChars,
+    CharacterSetProfile? characterSetProfile,
+    int? maxGenerationAttempts,
+    Object? policy = _sentinel,
+    Map<String, dynamic>? extra,
+  }) {
+    return PasswordGeneratorConfig(
+      length: length ?? this.length,
+      useUpperCase: useUpperCase ?? this.useUpperCase,
+      useLowerCase: useLowerCase ?? this.useLowerCase,
+      useNumbers: useNumbers ?? this.useNumbers,
+      useSpecialChars: useSpecialChars ?? this.useSpecialChars,
+      excludeAmbiguousChars:
+          excludeAmbiguousChars ?? this.excludeAmbiguousChars,
+      characterSetProfile: characterSetProfile ?? this.characterSetProfile,
+      maxGenerationAttempts:
+          maxGenerationAttempts ?? this.maxGenerationAttempts,
+      policy: policy == _sentinel ? this.policy : policy as PasswordPolicy?,
+      extra: extra ?? this.extra,
+    );
+  }
+
   /// Converts this configuration to a map.
   Map<String, dynamic> toMap() {
     return {
@@ -98,4 +132,43 @@ class PasswordGeneratorConfig {
       'extra': extra,
     };
   }
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+    final collectionEquals = const DeepCollectionEquality().equals;
+
+    return other is PasswordGeneratorConfig &&
+        other.length == length &&
+        other.useUpperCase == useUpperCase &&
+        other.useLowerCase == useLowerCase &&
+        other.useNumbers == useNumbers &&
+        other.useSpecialChars == useSpecialChars &&
+        other.excludeAmbiguousChars == excludeAmbiguousChars &&
+        other.characterSetProfile == characterSetProfile &&
+        other.maxGenerationAttempts == maxGenerationAttempts &&
+        other.policy == policy &&
+        collectionEquals(other.extra, extra);
+  }
+
+  @override
+  int get hashCode {
+    return length.hashCode ^
+        useUpperCase.hashCode ^
+        useLowerCase.hashCode ^
+        useNumbers.hashCode ^
+        useSpecialChars.hashCode ^
+        excludeAmbiguousChars.hashCode ^
+        characterSetProfile.hashCode ^
+        maxGenerationAttempts.hashCode ^
+        policy.hashCode ^
+        const DeepCollectionEquality().hash(extra);
+  }
+
+  @override
+  String toString() {
+    return 'PasswordGeneratorConfig(length: $length, useUpperCase: $useUpperCase, useLowerCase: $useLowerCase, useNumbers: $useNumbers, useSpecialChars: $useSpecialChars, excludeAmbiguousChars: $excludeAmbiguousChars, characterSetProfile: $characterSetProfile, maxGenerationAttempts: $maxGenerationAttempts, policy: $policy, extra: $extra)';
+  }
 }
+
+const Object _sentinel = Object();

lib/src/generator/ipassword_generator.dart

@@ -1,4 +1,5 @@
 import '../model/password_feedback.dart';
+import '../model/password_strength.dart';
 
 /// Interface for password generators.
 abstract interface class IPasswordGenerator {
@@ -15,6 +16,9 @@ abstract interface class IPasswordGenerator {
   /// Generates a strong password, retrying until validation passes.
   String refreshPassword();
 
+  /// Estimates the [PasswordStrength] of the given [password].
+  PasswordStrength estimateStrength(String password);
+
   /// Returns user-facing [PasswordFeedback] for the given [password].
   PasswordFeedback estimateFeedback(String password);
 }

lib/src/generator/password_generator.dart

@@ -112,6 +112,7 @@ final class PasswordGenerator implements IPasswordGenerator {
   }
 
   /// Estimates the [PasswordStrength] of the given [password].
+  @override
   PasswordStrength estimateStrength(String password) {
     return _strengthEstimator.estimatePasswordStrength(
       _normalizer.normalize(password),

lib/src/model/character_set_profile.dart

@@ -116,4 +116,36 @@ class CharacterSetProfile {
       'specialCharactersNonAmbiguous': specialCharactersNonAmbiguous,
     };
   }
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+
+    return other is CharacterSetProfile &&
+        other.upperCaseLetters == upperCaseLetters &&
+        other.lowerCaseLetters == lowerCaseLetters &&
+        other.numbers == numbers &&
+        other.specialCharacters == specialCharacters &&
+        other.upperCaseLettersNonAmbiguous == upperCaseLettersNonAmbiguous &&
+        other.lowerCaseLettersNonAmbiguous == lowerCaseLettersNonAmbiguous &&
+        other.numbersNonAmbiguous == numbersNonAmbiguous &&
+        other.specialCharactersNonAmbiguous == specialCharactersNonAmbiguous;
+  }
+
+  @override
+  int get hashCode {
+    return upperCaseLetters.hashCode ^
+        lowerCaseLetters.hashCode ^
+        numbers.hashCode ^
+        specialCharacters.hashCode ^
+        upperCaseLettersNonAmbiguous.hashCode ^
+        lowerCaseLettersNonAmbiguous.hashCode ^
+        numbersNonAmbiguous.hashCode ^
+        specialCharactersNonAmbiguous.hashCode;
+  }
+
+  @override
+  String toString() {
+    return 'CharacterSetProfile(upperCaseLetters: $upperCaseLetters, lowerCaseLetters: $lowerCaseLetters, numbers: $numbers, specialCharacters: $specialCharacters, upperCaseLettersNonAmbiguous: $upperCaseLettersNonAmbiguous, lowerCaseLettersNonAmbiguous: $lowerCaseLettersNonAmbiguous, numbersNonAmbiguous: $numbersNonAmbiguous, specialCharactersNonAmbiguous: $specialCharactersNonAmbiguous)';
+  }
 }

lib/src/model/password_feedback.dart

@@ -1,3 +1,5 @@
+import 'package:collection/collection.dart';
+
 import 'password_strength.dart';
 
 /// User-facing feedback for password strength results.
@@ -51,4 +53,31 @@ class PasswordFeedback {
       'score': score,
     };
   }
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+    final collectionEquals = const DeepCollectionEquality().equals;
+
+    return other is PasswordFeedback &&
+        other.strength == strength &&
+        other.warning == warning &&
+        collectionEquals(other.suggestions, suggestions) &&
+        other.estimatedEntropy == estimatedEntropy &&
+        other.score == score;
+  }
+
+  @override
+  int get hashCode {
+    return strength.hashCode ^
+        warning.hashCode ^
+        const DeepCollectionEquality().hash(suggestions) ^
+        estimatedEntropy.hashCode ^
+        score.hashCode;
+  }
+
+  @override
+  String toString() {
+    return 'PasswordFeedback(strength: $strength, warning: $warning, suggestions: $suggestions, estimatedEntropy: $estimatedEntropy, score: $score)';
+  }
 }

lib/src/model/password_policy.dart

@@ -79,27 +79,33 @@ class PasswordPolicy {
   /// Returns a copy of this policy with the given fields replaced.
   PasswordPolicy copyWith({
     int? minLength,
-    int? maxLength,
+    Object? maxLength = _sentinel,
     bool? requireUppercase,
     bool? requireLowercase,
     bool? requireNumber,
     bool? requireSpecial,
     bool? allowSpaces,
     bool? allowUnicode,
-    PasswordStrength? strengthThreshold,
-    int? scoreThreshold,
+    Object? strengthThreshold = _sentinel,
+    Object? scoreThreshold = _sentinel,
   }) {
     return PasswordPolicy(
       minLength: minLength ?? this.minLength,
-      maxLength: maxLength ?? this.maxLength,
+      maxLength: maxLength == _sentinel ? this.maxLength : maxLength as int?,
       requireUppercase: requireUppercase ?? this.requireUppercase,
       requireLowercase: requireLowercase ?? this.requireLowercase,
       requireNumber: requireNumber ?? this.requireNumber,
       requireSpecial: requireSpecial ?? this.requireSpecial,
       allowSpaces: allowSpaces ?? this.allowSpaces,
       allowUnicode: allowUnicode ?? this.allowUnicode,
-      strengthThreshold: strengthThreshold ?? this.strengthThreshold,
-      scoreThreshold: scoreThreshold ?? this.scoreThreshold,
+      strengthThreshold:
+          strengthThreshold == _sentinel
+              ? this.strengthThreshold
+              : strengthThreshold as PasswordStrength?,
+      scoreThreshold:
+          scoreThreshold == _sentinel
+              ? this.scoreThreshold
+              : scoreThreshold as int?,
     );
   }
 
@@ -124,6 +130,42 @@ class PasswordPolicy {
       'scoreThreshold': scoreThreshold,
     };
   }
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+
+    return other is PasswordPolicy &&
+        other.minLength == minLength &&
+        other.maxLength == maxLength &&
+        other.requireUppercase == requireUppercase &&
+        other.requireLowercase == requireLowercase &&
+        other.requireNumber == requireNumber &&
+        other.requireSpecial == requireSpecial &&
+        other.allowSpaces == allowSpaces &&
+        other.allowUnicode == allowUnicode &&
+        other.strengthThreshold == strengthThreshold &&
+        other.scoreThreshold == scoreThreshold;
+  }
+
+  @override
+  int get hashCode {
+    return minLength.hashCode ^
+        maxLength.hashCode ^
+        requireUppercase.hashCode ^
+        requireLowercase.hashCode ^
+        requireNumber.hashCode ^
+        requireSpecial.hashCode ^
+        allowSpaces.hashCode ^
+        allowUnicode.hashCode ^
+        strengthThreshold.hashCode ^
+        scoreThreshold.hashCode;
+  }
+
+  @override
+  String toString() {
+    return 'PasswordPolicy(minLength: $minLength, maxLength: $maxLength, requireUppercase: $requireUppercase, requireLowercase: $requireLowercase, requireNumber: $requireNumber, requireSpecial: $requireSpecial, allowSpaces: $allowSpaces, allowUnicode: $allowUnicode, strengthThreshold: $strengthThreshold, scoreThreshold: $scoreThreshold)';
+  }
 }
 
 /// Builder for creating and modifying [PasswordPolicy] instances.
@@ -240,3 +282,5 @@ extension PasswordPolicyX on PasswordPolicy {
     return length;
   }
 }
+
+const Object _sentinel = Object();

lib/src/strategy/passphrase_password_strategy.dart

@@ -34,7 +34,7 @@ final class PassphrasePasswordStrategy implements IPasswordGenerationStrategy {
   String generate(PasswordGeneratorConfig config) {
     validate(config);
 
-    final wordCount = config.length;
+    final wordCount = config.extra['wordCount'] as int? ?? config.length;
     final random = _random;
     final words = <String>[];
 
@@ -63,10 +63,11 @@ final class PassphrasePasswordStrategy implements IPasswordGenerationStrategy {
     if (_wordlist.any((word) => word.isEmpty)) {
       throw ArgumentError(messages.error.wordlistHasEmptyWords);
     }
-    if (config.length <= 0) {
+    final wordCount = config.extra['wordCount'] as int? ?? config.length;
+    if (wordCount <= 0) {
       throw ArgumentError(messages.error.wordCountPositive);
     }
-    if (!allowDuplicates && config.length > _uniqueWordlist.length) {
+    if (!allowDuplicates && wordCount > _uniqueWordlist.length) {
       throw ArgumentError(messages.error.wordCountExceedsWordlist);
     }
   }

lib/src/strategy/random_password_strategy.dart

@@ -41,7 +41,8 @@ final class RandomPasswordStrategy implements IPasswordGenerationStrategy {
   @override
   void validate(PasswordGeneratorConfig config) {
     final messages = const Messages();
-    final minLength = PasswordPolicy.defaultMinLength;
+    final minLength =
+        config.policy?.minLength ?? PasswordPolicy.defaultMinLength;
     if (config.length < minLength) {
       throw ArgumentError(messages.error.passwordLengthMin(minLength));
     }

lib/src/strength_estimator/password_strength_estimator.dart

@@ -58,7 +58,11 @@ final class PasswordStrengthEstimator implements IPasswordStrengthEstimator {
       characterPoolSize += specialCharacters.length;
     }
 
-    if (characterPoolSize == 0) return 0;
+    if (characterPoolSize == 0) {
+      // Fallback for passwords consisting entirely of unmapped characters (e.g., Unicode).
+      // We assume a large arbitrary pool size to give credit for these characters.
+      characterPoolSize = 100000;
+    }
 
     return password.length * log(characterPoolSize) / log(2);
   }