[pub_semver] Discourage modification of properties intended to be unmodifiable (#2020)

Author: parlough

pkgs/pub_semver/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.1.6
+
+- Clarify that the lists returned by
+  the `preRelease` and `build` properties of `Version` and
+  the `ranges` property of `VersionUnion` should not be modified.
+- Note that `VersionConstraint.any` and `VersionConstraint.empty` static fields
+  shouldn't be reassigned and will be made `final` in a future release.
+
 ## 2.1.5
 
 - Require Dart `3.4.0`.

pkgs/pub_semver/lib/src/version.dart

@@ -70,13 +70,17 @@ class Version implements VersionConstraint, VersionRange {
   /// This is split into a list of components, each of which may be either a
   /// string or a non-negative integer. It may also be empty, indicating that
   /// this version has no pre-release identifier.
+  ///
+  /// **Note:** The returned list shouldn't be modified.
   final List<Object> preRelease;
 
   /// The build identifier: "foo" in "1.2.3+foo".
   ///
   /// This is split into a list of components, each of which may be either a
   /// string or a non-negative integer. It may also be empty, indicating that
   /// this version has no build identifier.
+  ///
+  /// **Note:** The returned list shouldn't be modified.
   final List<Object> build;
 
   /// The original string representation of the version number.
@@ -96,8 +100,10 @@ class Version implements VersionConstraint, VersionRange {
 
   Version._(this.major, this.minor, this.patch, String? preRelease,
       String? build, this._text)
-      : preRelease = preRelease == null ? <Object>[] : _splitParts(preRelease),
-        build = build == null ? [] : _splitParts(build) {
+      : preRelease = preRelease == null || preRelease.isEmpty
+            ? []
+            : _splitParts(preRelease),
+        build = build == null || build.isEmpty ? [] : _splitParts(build) {
     if (major < 0) throw ArgumentError('Major version must be non-negative.');
     if (minor < 0) throw ArgumentError('Minor version must be non-negative.');
     if (patch < 0) throw ArgumentError('Patch version must be non-negative.');

pkgs/pub_semver/lib/src/version_constraint.dart

@@ -16,9 +16,15 @@ import 'version_union.dart';
 /// version.
 abstract class VersionConstraint {
   /// A [VersionConstraint] that allows all versions.
+  ///
+  /// **Note:** This property shouldn't be reassigned.
+  /// It will be made `final` in a future release.
   static VersionConstraint any = VersionRange();
 
   /// A [VersionConstraint] that allows no versions -- the empty set.
+  ///
+  /// **Note:** This property shouldn't be reassigned.
+  /// It will be made `final` in a future release.
   static VersionConstraint empty = const _EmptyVersion();
 
   /// Parses a version constraint.

pkgs/pub_semver/lib/src/version_union.dart

@@ -23,6 +23,8 @@ class VersionUnion implements VersionConstraint {
   /// * Its contents are disjoint and non-adjacent. In other words, for any two
   ///   constraints next to each other in the list, there's some version between
   ///   those constraints that they don't match.
+  ///
+  /// **Note:** The returned list shouldn't be modified.
   final List<VersionRange> ranges;
 
   @override

pkgs/pub_semver/pubspec.yaml

@@ -1,5 +1,5 @@
 name: pub_semver
-version: 2.1.5
+version: 2.1.6
 description: >-
   Versions and version constraints implementing pub's versioning policy. This
   is very similar to vanilla semver, with a few corner cases.