Add more version helpers. (#14910)

There are still some gaps in functionality related to Python versions. This change fills in those gaps and brings consistency to the existing utilities.

Note that utilities for extracting Python versions from filenames (executables) will be handled in a separate change.

Author: ericsnowcurrently

src/client/common/utils/version.ts

@@ -77,27 +77,46 @@ export const EMPTY_VERSION: RawBasicVersionInfo = {
         micro: undefined,
     },
 };
+Object.freeze(EMPTY_VERSION);
+
+function copyStrict<T extends BasicVersionInfo>(info: T): RawBasicVersionInfo {
+    const copied: RawBasicVersionInfo = {
+        major: info.major,
+        minor: info.minor,
+        micro: info.micro,
+    };
+
+    const unnormalized = ((info as unknown) as RawBasicVersionInfo).unnormalized;
+    if (unnormalized !== undefined) {
+        copied.unnormalized = {
+            major: unnormalized.major,
+            minor: unnormalized.minor,
+            micro: unnormalized.micro,
+        };
+    }
+
+    return copied;
+}
 
 /**
  * Make a copy and set all the properties properly.
  *
- * Only the "basic" version info will be normalized.  The caller
- * is responsible for any other properties beyond that.
+ * Only the "basic" version info will be set (and normalized).
+ * The caller is responsible for any other properties beyond that.
  */
 export function normalizeBasicVersionInfo<T extends BasicVersionInfo>(info: T | undefined): T {
     if (!info) {
         return EMPTY_VERSION as T;
     }
-    const norm: T = { ...info };
-    const raw = (norm as unknown) as RawBasicVersionInfo;
+    const norm = copyStrict(info);
     // Do not normalize if it has already been normalized.
-    if (raw.unnormalized === undefined) {
-        raw.unnormalized = {};
-        [norm.major, raw.unnormalized.major] = normalizeVersionPart(norm.major);
-        [norm.minor, raw.unnormalized.minor] = normalizeVersionPart(norm.minor);
-        [norm.micro, raw.unnormalized.micro] = normalizeVersionPart(norm.micro);
+    if (norm.unnormalized === undefined) {
+        norm.unnormalized = {};
+        [norm.major, norm.unnormalized.major] = normalizeVersionPart(norm.major);
+        [norm.minor, norm.unnormalized.minor] = normalizeVersionPart(norm.minor);
+        [norm.micro, norm.unnormalized.micro] = normalizeVersionPart(norm.micro);
     }
-    return norm;
+    return norm as T;
 }
 
 function validateVersionPart(prop: string, part: number, unnormalized?: ErrorMsg) {
@@ -230,6 +249,55 @@ export function isVersionInfoEmpty<T extends BasicVersionInfo>(info: T): boolean
     return info.major < 0 && info.minor < 0 && info.micro < 0;
 }
 
+/**
+ * Decide if two versions are the same or if one is "less".
+ *
+ * Note that a less-complete object that otherwise matches
+ * is considered "less".
+ *
+ * Additional checks for an otherwise "identical" version may be made
+ * through `compareExtra()`.
+ *
+ * @returns - the customary comparison indicator (e.g. -1 means left is "more")
+ * @returns - a string that indicates the property where they differ (if any)
+ */
+export function compareVersions<T extends BasicVersionInfo, V extends BasicVersionInfo>(
+    // the versions to compare:
+    left: T,
+    right: V,
+    compareExtra?: (v1: T, v2: V) => [number, string],
+): [number, string] {
+    if (left.major < right.major) {
+        return [1, 'major'];
+    } else if (left.major > right.major) {
+        return [-1, 'major'];
+    } else if (left.major === -1) {
+        // Don't bother checking minor or micro.
+        return [0, ''];
+    }
+
+    if (left.minor < right.minor) {
+        return [1, 'minor'];
+    } else if (left.minor > right.minor) {
+        return [-1, 'minor'];
+    } else if (left.minor === -1) {
+        // Don't bother checking micro.
+        return [0, ''];
+    }
+
+    if (left.micro < right.micro) {
+        return [1, 'micro'];
+    } else if (left.micro > right.micro) {
+        return [-1, 'micro'];
+    }
+
+    if (compareExtra !== undefined) {
+        return compareExtra(left, right);
+    }
+
+    return [0, ''];
+}
+
 //===========================
 // base version info
 
@@ -246,15 +314,12 @@ export type VersionInfo = BasicVersionInfo & {
  * Make a copy and set all the properties properly.
  */
 export function normalizeVersionInfo<T extends VersionInfo>(info: T): T {
-    const basic = normalizeBasicVersionInfo(info);
-    if (!info) {
-        basic.raw = '';
-        return basic;
-    }
-    const norm = { ...info, ...basic };
+    const norm = normalizeBasicVersionInfo(info);
+    norm.raw = info.raw;
     if (!norm.raw) {
         norm.raw = '';
     }
+    // Any string value of "raw" is considered normalized.
     return norm;
 }
 
@@ -285,6 +350,52 @@ export function parseVersionInfo<T extends VersionInfo>(verStr: string): ParseRe
     return result;
 }
 
+/**
+ * Checks if major, minor, and micro match.
+ *
+ * Additional checks may be made through `compareExtra()`.
+ */
+export function areIdenticalVersion<T extends BasicVersionInfo, V extends BasicVersionInfo>(
+    // the versions to compare:
+    left: T,
+    right: V,
+    compareExtra?: (v1: T, v2: V) => [number, string],
+): boolean {
+    const [result] = compareVersions(left, right, compareExtra);
+    return result === 0;
+}
+
+/**
+ * Checks if the versions are identical or one is more complete than other (and otherwise the same).
+ *
+ * At the least the major version must be set (non-negative).
+ */
+export function areSimilarVersions<T extends BasicVersionInfo, V extends BasicVersionInfo>(
+    // the versions to compare:
+    left: T,
+    right: V,
+    compareExtra?: (v1: T, v2: V) => [number, string],
+): boolean {
+    const [result, prop] = compareVersions(left, right, compareExtra);
+    if (result === 0) {
+        return true;
+    }
+
+    if (prop === 'major') {
+        // An empty version is never similar (except to another empty version).
+        return false;
+    }
+
+    // tslint:disable:no-any
+    if (result < 0) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return ((right as unknown) as any)[prop] === -1;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return ((left as unknown) as any)[prop] === -1;
+    // tslint:enable:no-any
+}
+
 //===========================
 // semver
 

src/client/pythonEnvironments/base/info/env.ts

@@ -8,7 +8,7 @@ import { Architecture } from '../../../common/utils/platform';
 import { arePathsSame } from '../../common/externalDependencies';
 import { getPrioritizedEnvKinds } from './envKind';
 import { parseVersionFromExecutable } from './executable';
-import { areEqualVersions, areEquivalentVersions, isVersionEmpty } from './pythonVersion';
+import { areIdenticalVersion, areSimilarVersions, isVersionEmpty } from './pythonVersion';
 
 import { FileInfo, PythonDistroInfo, PythonEnvInfo, PythonEnvKind, PythonReleaseLevel, PythonVersion } from '.';
 
@@ -277,8 +277,8 @@ export function areSameEnv(
         const rightVersion = typeof right === 'string' ? undefined : right.version;
         if (leftVersion && rightVersion) {
             if (
-                areEqualVersions(leftVersion, rightVersion) ||
-                (allowPartialMatch && areEquivalentVersions(leftVersion, rightVersion))
+                areIdenticalVersion(leftVersion, rightVersion) ||
+                (allowPartialMatch && areSimilarVersions(leftVersion, rightVersion))
             ) {
                 return true;
             }