From 3c87df28830a54050856d7415ea0563c546dada2 Mon Sep 17 00:00:00 2001
From: Sergei Zharinov <zharinov@users.noreply.github.com>
Date: Tue, 12 Dec 2023 04:39:06 -0300
Subject: [PATCH] refactor: Clarify `VersioningApi` validation methods (#26235)

---
 lib/modules/versioning/types.ts | 44 +++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 13 deletions(-)

diff --git a/lib/modules/versioning/types.ts b/lib/modules/versioning/types.ts
index 6c9807d7c30e6c..e9e686470eac9e 100644
--- a/lib/modules/versioning/types.ts
+++ b/lib/modules/versioning/types.ts
@@ -12,33 +12,51 @@ export interface VersioningApi {
   // validation
 
   /**
-   * Check whether the `version` is compatible with the `current` value
-   * constraint.
+   * Check whether the `input` is the valid version or range.
+   *
+   * For some managers, ranges are called "constraints","specifiers", "requirements", etc.
+   * We stick to the term "range" for all of it.
    */
-  isCompatible(version: string, current?: string): boolean;
+  isValid(input: string): boolean;
 
   /**
-   * Check whether the `version` constraint is not a range, i.e. it only allows a
-   * single specific version.
+   * Check whether the `input` is a valid version.
+   *
+   * There is no direct way to determine whether the `input` is the range,
+   * but combination of `isVersion` and `isValid` can be used for that:
+   *
+   *    `isValid(input) && !isVersion(input)`
    */
-  isSingleVersion(version: string): boolean;
+  isVersion(input: string | undefined | null): boolean;
 
   /**
-   * Check whether the `version` is considered to be "stable".
+   * Check whether the `input` is the:
+   *
+   *   1. Version, or
+   *   2. Range with the special syntax of matching exactly one version:
+   *      - `==1.2.3` or `===1.2.3` for Python,
+   *      - `=1.2.3` for NPM,
+   *      - `[1.2.3]` for Maven or NuGet.
    *
-   * Example: in SemVer the version must not have a pre-release marker.
+   * This is used to provide pinning functionality.
    */
-  isStable(version: string): boolean;
+  isSingleVersion(input: string): boolean;
 
   /**
-   * Check whether the `input` is a valid version or a valid version range constraint.
+   * Check whether the `version` is considered to be "stable".
    */
-  isValid(input: string): boolean;
+  isStable(version: string): boolean;
 
   /**
-   * Check whether the `input` is a valid version string.
+   * Determines whether the version is compatible with the current one,
+   * in some manager-dependent way.
+   *
+   * For most managers, all valid versions are compatible between each other.
+   *
+   * However, for example, Docker versions `1.2.3` and `1.2.4-alpine` are not compatible,
+   * i.e. `1.2.4-alpine` is not a valid upgrade for `1.2.3`.
    */
-  isVersion(input: string | undefined | null): boolean;
+  isCompatible(version: string, current?: string): boolean;
 
   // digestion of version