Repository navigation
Expand file tree
/
Copy pathversionUtils.ts
More file actions
556 lines (509 loc) · 22.3 KB
/
Copy pathversionUtils.ts
File metadata and controls
556 lines (509 loc) · 22.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
/*!
* Copyright (c) Microsoft Corporation and contributors. All rights reserved.
* Licensed under the MIT License.
*/
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";
import { createRequire } from "node:module";
import * as path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { detectVersionScheme, fromInternalScheme } from "@fluid-tools/version-tools";
import { assert } from "@fluidframework/core-utils/internal";
import * as semver from "semver";
// ---------------------------------------------------------------------------
// Paths
// ---------------------------------------------------------------------------
// From compiled lib/, go up one level to reach the package root, then into compat-workspaces/
const compatWorkspacesDir = fileURLToPath(new URL("../compat-workspaces", import.meta.url));
const generatedVersionsCjsPath = path.join(compatWorkspacesDir, "generated-versions.cjs");
export const fullWorkspaceDir = path.join(compatWorkspacesDir, "full");
// ---------------------------------------------------------------------------
// generated-versions.cjs manifest
// ---------------------------------------------------------------------------
/**
* Schema for the committed `compat-workspaces/generated-versions.cjs` file.
*/
export interface CompatVersionsManifest {
/** All exact versions installed in `compat-workspaces/full/`, newest first. */
versions: string[];
}
let cachedManifest: CompatVersionsManifest | undefined;
/**
* Reads the committed versions manifest.
*/
export function readVersionsManifest(): CompatVersionsManifest {
if (cachedManifest !== undefined) return cachedManifest;
if (!existsSync(generatedVersionsCjsPath)) {
throw new Error("Could not read versions manifest");
}
cachedManifest = createRequire(import.meta.url)(
generatedVersionsCjsPath,
) as CompatVersionsManifest;
return cachedManifest;
}
// ---------------------------------------------------------------------------
// Version resolution
// ---------------------------------------------------------------------------
const resolutionCache = new Map<string, string>();
// See https://github.com/nodejs/node-v0.x-archive/issues/2318.
// Note that execFile and execFileSync are used to avoid command injection vulnerability flagging from CodeQL.
// pnpm is used instead of npm for package installation to enable security flags (--ignore-scripts, --prefer-offline).
const pnpmCmd = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
/**
* @returns A version of the provided function which caches outputs based on JSON-stringified arguments.
* @remarks
* Do not use this function if any of the arguments to the function are conceptually not primitives OR if they can be undefined.
* @privateRemarks
* The typing on this is constructed so that users of the cached function will have their inner function type (including e.g. parameter names) preserved.
*/
function cached<TFunc extends (...args: any[]) => unknown>(f: TFunc): TFunc {
const undefinedSentinel = Symbol("undefined");
const cache = new Map<string, ReturnType<TFunc> | typeof undefinedSentinel>();
return ((...args: Parameters<TFunc>) => {
const key = JSON.stringify(args);
let cachedOutput: ReturnType<TFunc> | typeof undefinedSentinel | undefined =
cache.get(key);
if (cachedOutput === undefined) {
cachedOutput = f(...args) as ReturnType<TFunc>;
cache.set(key, cachedOutput ?? undefinedSentinel);
}
return cachedOutput === undefinedSentinel ? undefined : cachedOutput;
}) as unknown as TFunc;
}
function validateRangeSpec(rangeSpec: string): void {
if (!semver.validRange(rangeSpec)) {
throw new Error(`Invalid semver range: "${rangeSpec}"`);
}
}
/**
* Resolves a semver dependency spec to the single highest version matching that spec which is published in the npm registry.
* @param rangeSpec - A valid (as per [semver](https://www.npmjs.com/package/semver)) range specification
*/
export const resolveRangeViaRegistry = cached((rangeSpec: string): string => {
if (semver.valid(rangeSpec)) {
return rangeSpec;
}
validateRangeSpec(rangeSpec);
let result: string;
try {
result = execFileSync(
pnpmCmd,
["view", `"@fluidframework/container-loader@${rangeSpec}"`, "version", "--json"],
{
encoding: "utf8",
// When using pnpm.cmd shell must be true: https://nodejs.org/en/blog/vulnerability/april-2024-security-releases-2
shell: true,
},
);
} catch (e) {
throw new Error(`pnpm view failed for range "${rangeSpec}": ${e}`);
}
if (!result) throw new Error(`No published version for range: ${rangeSpec}`);
const versions: string | string[] = JSON.parse(result);
const version = Array.isArray(versions) ? versions.sort(semver.rcompare)[0] : versions;
if (!version) throw new Error(`Could not resolve range: ${rangeSpec}`);
return version;
});
/**
* Resolves a semver dependency spec to the most recent installed version under compat-workspaces which
* satisfies that range.
*
* Throws if the currently installed compat workspace does not include any version that matches the spec.
* @param rangeSpec - A valid (as per [semver](https://www.npmjs.com/package/semver)) range specification
*/
export function resolveRangeViaManifest(rangeSpec: string): string {
if (semver.valid(rangeSpec)) {
return rangeSpec;
}
validateRangeSpec(rangeSpec);
const manifest = readVersionsManifest();
const matching = manifest.versions
.filter((v) => semver.valid(v) && semver.satisfies(v, rangeSpec))
.sort(semver.rcompare);
if (matching.length > 0) {
return matching[0];
}
throw new Error(`No version in manifest satisfies range: "${rangeSpec}"`);
}
// ---------------------------------------------------------------------------
// Installed package lookup
// ---------------------------------------------------------------------------
/**
* Resolves an exact version string to its installed module path in `compat-workspaces/full/`.
*
* The workspace is expected to be pre-installed via the package `postinstall` hook. Throws a
* descriptive error if the version directory is not found.
* @internal
*/
export function checkInstalled(requested: string): { version: string; modulePath: string } {
const version = resolveRangeViaManifest(requested);
const versionDir = path.join(fullWorkspaceDir, version);
if (existsSync(versionDir)) {
return { version, modulePath: versionDir };
}
throw new Error(
`Version ${version} is not installed in compat-workspaces/full/.\n` +
`Run \`pnpm run update-compat-versions\` after updating the compatibility matrix to regenerate the workspace dependencies.\n` +
`If it is already listed as a dependency of compat-workspaces/full, this error might indicate that the workspace was not installed correctly.\n` +
`Try running \`pnpm install\` from the repo root to ensure the workspace is installed.`,
);
}
// ---------------------------------------------------------------------------
// Package loading
// ---------------------------------------------------------------------------
/**
* Dynamically loads a package from the specified module path.
*
* @param modulePath - Path to the version directory (e.g. `compat-workspaces/full/2.83.0`).
* @param pkg - Package name to load (e.g. `@fluidframework/container-loader`).
* @remarks
* This function reimplements part of Node's module resolution logic. It would be possible to use `createRequire` / `import` alternatively,
* but if this approach is taken, the compat workspace where prior versions of FF get installed *must* be moved outside of a context that might
* have other versions of FF installed in parent folders. Otherwise, Node's module resolution might happily load incorrect versions of FF packages
* from parent folders instead of the intended versions, which would silently break the tests.
* @internal
*/
export const loadPackage = async (
modulePath: string,
pkg: string,
importPath: "." | `./${string}` = ".",
): Promise<any> => {
const pkgPath = path.join(modulePath, "node_modules", pkg);
// Because we put legacy versions in a specific subfolder of node_modules (.legacy/<version>), we need to reimplement
// some of Node's module loading logic here.
// It would be ideal to remove the need for this duplication (e.g. by using node:module APIs instead) if possible.
const pkgJson: { main?: string; exports?: string | Record<string, any> } = JSON.parse(
readFileSync(path.join(pkgPath, "package.json"), { encoding: "utf8" }),
);
// See: https://nodejs.org/docs/latest-v18.x/api/packages.html#package-entry-points
let primaryExport: string;
if (pkgJson.exports !== undefined) {
// See https://nodejs.org/docs/latest-v18.x/api/packages.html#conditional-exports for information on the spec
// if this assert fails.
// The v18 doc doesn't mention that export paths must start with ".", but the modern docs do:
// https://nodejs.org/api/packages.html#exports
for (const key of Object.keys(pkgJson.exports)) {
if (!key.startsWith(".")) {
throw new Error(
"Conditional exports not supported by test-version-utils. Legacy module loading logic needs to be updated.",
);
}
}
if (typeof pkgJson.exports === "string") {
primaryExport = pkgJson.exports;
} else {
const exp: any | undefined = pkgJson.exports[importPath] ?? pkgJson.exports["."];
primaryExport =
typeof exp === "string"
? exp
: exp.require !== undefined
? exp.require.default
: exp.default;
if (typeof primaryExport !== "string") {
// eslint-disable-next-line unicorn/prefer-type-error -- this isn't a TypeError really; it is an internal logic shortcoming; entry might not be a string
throw new Error(
`Package ${pkg} defined subpath exports but no recognizable ${importPath} entry.`,
);
}
}
} else {
if (pkgJson.main === undefined) {
throw new Error(`No main or exports in package.json for ${pkg}`);
}
if (importPath !== ".") {
console.warn(
`Package ${pkg} main used despite request for ${importPath} entry (no "exports" property found).`,
);
}
primaryExport = pkgJson.main;
}
return import(pathToFileURL(path.join(pkgPath, primaryExport)).href);
};
// ---------------------------------------------------------------------------
// Version arithmetic
// ---------------------------------------------------------------------------
/**
* Computes the semver range corresponding to a delta from a base version, without resolving it
* to an exact version. Used by both the test runtime and the `update-compat-versions` script.
*/
export function calculateRequestedRange(
baseVersion: string,
requested?: number | string,
adjustPublicMajor: boolean = false,
): string {
if (requested === undefined || requested === 0) {
return baseVersion;
}
if (typeof requested === "string") {
return requested;
}
if (requested > 0) {
throw new Error("Only negative values are supported for `requested` param.");
}
const scheme = detectVersionScheme(baseVersion);
// if the baseVersion passed is an internal version
if (
adjustPublicMajor === false &&
(scheme === "internal" || scheme === "internalPrerelease")
) {
const [publicVersion, internalVersion, prereleaseIdentifier] = fromInternalScheme(
baseVersion,
/** allowPrereleases */ true,
/** allowAnyPrereleaseId */ true,
);
const internalSchemeRange = internalSchema(
publicVersion.version,
internalVersion.version,
prereleaseIdentifier,
requested,
);
return internalSchemeRange;
}
let version: semver.SemVer;
try {
version = new semver.SemVer(baseVersion);
} catch (err: unknown) {
throw new Error(err as string);
}
// If the base version is a public version and `adjustPublicMajor` is false, then we need to ensure that we
// calculate N-1 as the previous major release, regardless if it is public or internal.
// The legacy scheme groups minor versions into decades and continues across the 2.x/3.x boundary.
// TODO: This is a temporary solution and we need to entirely rewrite this function to handle the changes the version schemas. See ADO:8198.
assert(version.major <= 3, "This legacy logic only known to work for 2.x and 3.x versions.");
if (adjustPublicMajor === false && version.major >= 2) {
// For each requested version to go back, we go back 10 minor versions.
const legacyMinorsToSkip = Math.abs(requested * 10);
// The range's major differs from the base only when a 3.x request crosses below 3.0.
const major =
version.major === 3 && legacyMinorsToSkip > version.minor ? 2 : version.major;
// 2.118 was the last 2.x release, so treat 3.0 as 2.120 only when crossing that boundary.
const minorOffset = major !== version.major ? 120 : 0;
const minor = version.minor + minorOffset;
if (minor < 10) {
// If 2.0 <= N < 2.10, then we can pretend that N is RC6 (*which doesn't exist*) and calculate the range as if it were an internal version.
const internalSchemeRange = internalSchema("2.0.0", "6.0.0", "rc", requested);
return internalSchemeRange;
} else {
if (legacyMinorsToSkip > minor) {
// If the number of minors we need to go back is greater than the minor version, then that means we will be going back to RC releases.
// Here we calculate how many more releases we need to go back **after** we take into account going from the current minor version to 2.0.
// For example, if N is 2.20, then the range we need to return for N-1 starts at 2.10, for N-2 it starts at 2.0, N-3 is RC5, N-4 is RC4, etc.
// So if N is 2.20 and requested is 4, then we still need to go back 2 more releases from 2.0 (treated as RC6).
const remainingRequested = (legacyMinorsToSkip - Math.floor(minor / 10) * 10) / 10;
const internalSchemeRange = internalSchema(
"2.0.0",
"6.0.0",
"rc",
remainingRequested * -1, // make sure the value is negative since we made it positive above
);
return internalSchemeRange;
}
// Here we know that the requested version will be >=2.0, so we can avoid all the RC releases.
// If N >= 2.10, then the range we need to return for N-1 starts at legacy breaking minor before the one N belongs to.
const lowerMinorRange = Math.floor((minor - legacyMinorsToSkip) / 10) * 10;
const upperMinorRange = lowerMinorRange + 10;
// Here we do a range that, when resolved, will result in the latest minor version that satisfies the request.
return `>=${major}.${lowerMinorRange}.0-0 <${major}.${upperMinorRange}.0-0`;
}
} else {
// calculate requested major version number
const requestedMajorVersion = version.major + requested;
// if the major version number is bigger than 0 then return it as normal
if (requestedMajorVersion > 0) {
return `^${requestedMajorVersion}.0.0-0`;
}
// if the major version number is <= 0 then we return the equivalent pre-releases
const lastPrereleaseVersion = new semver.SemVer("0.59.0");
// Minor number in 0.xx release represent a major change hence different rules
// are applied for computing the requested version.
const requestedMinorVersion = lastPrereleaseVersion.minor + requestedMajorVersion;
// too old a version / non existing version requested
if (requestedMinorVersion <= 0) {
// cap at min version
return "^0.0.1-0";
}
return `^0.${requestedMinorVersion}.0-0`;
}
}
/**
* Options for {@link getRequestedVersion}.
*
* @internal
*/
export interface GetRequestedVersionOptions {
/** The base version to move from (eg. "2.60.0"). */
baseVersion: string;
/**
* If the value is a negative number, the base version will be adjusted down.
* If the value is a string then it will be returned as-is. Throws on positive number.
*/
requested?: number | string;
/**
* If `baseVersion` is a Fluid internal version, this controls whether the public or internal
* version is adjusted by `requested`.
*/
adjustPublicMajor?: boolean;
/**
* When `true`, resolve against the npm registry. Defaults to `false`, which resolves against the
* committed compat versions manifest.
* @privateRemarks
* Likely a better design for expressing what set of versions to consider would be to decouple the discovery of the set of versions from the resolution logic.
* This could be done by creating a type which holds a set of versions to consider, and passing it into the resolution functions.
* Then we simply need a function to create this type from the manifest, and one to create it from the registry.
* We can then make the registry version package internal and only used by the update logic to help ensure registry dependency is avoided in other cases.
*/
useOnlineRegistry?: boolean;
}
/**
* Given a version, returns the most recently resolved version for the requested range.
*
* By default, this resolves against the committed compat versions manifest so test selection stays
* stable for a given lockfile. Set `useOnlineRegistry` to `true` to opt into npm registry
* resolution for workflows like regenerating the compat manifest.
*
* @remarks
*
* In typical use, `requested` is a negative value to ask for a previous version (e.g. `-1`).
*
* @example
* ```typescript
* const newVersion = getRequestedVersion({ baseVersion: "2.3.5", requested: -1 });
* ```
*
* @example
* ```typescript
* const newVersion = getRequestedVersion({
* baseVersion: "2.3.5",
* requested: -2,
* useOnlineRegistry: true,
* });
* ```
*
* @internal
*/
export function getRequestedVersion({
baseVersion,
requested,
adjustPublicMajor = false,
useOnlineRegistry = false,
}: GetRequestedVersionOptions): string {
// Current-version requests should stay pinned to the caller-provided base version.
// This avoids requiring the current version to exist in the compat manifest/registry.
if (requested === undefined || requested === 0) {
return baseVersion;
}
// Explicit version strings are already concrete requests, so return them directly.
if (typeof requested === "string") {
return requested;
}
const calculatedRange = calculateRequestedRange(baseVersion, requested, adjustPublicMajor);
const cacheKey = JSON.stringify({ calculatedRange, useOnlineRegistry });
const cachedResolution = resolutionCache.get(cacheKey);
if (cachedResolution !== undefined) {
return cachedResolution;
}
const resolveRange = useOnlineRegistry ? resolveRangeViaRegistry : resolveRangeViaManifest;
try {
// Returns the exact version that was requested (i.e. 2.0.0-rc.2.0.2).
// Will throw if the requested version range is not valid.
const resolvedVersion = resolveRange(calculatedRange);
resolutionCache.set(cacheKey, resolvedVersion);
return resolvedVersion;
} catch (err: any) {
// If we tried fetching N-1 and it failed, try N-2. It is possible that we are trying to bump the current branch
// to a new version. If that is the case, then N-1 may not be published yet, and we should try to use N-2 in its place.
if (requested === -1) {
const resolvedVersion = getRequestedVersion({
baseVersion,
requested: -2,
adjustPublicMajor,
useOnlineRegistry,
});
// Here we cache the result so we don't have to enter the try/catch flow again.
// Note: This will cache the resolved version range (i.e. >=2.0.0-rc.4.0.0 <2.0.0-rc.5.0.0). Because of this,
// it will not cause any conflicts when trying to fetch the current version —
// i.e. `getRequestedVersion({ baseVersion: "2.0.0-rc.5.0.0" })` will still return "2.0.0-rc.5.0.0".
resolutionCache.set(cacheKey, resolvedVersion);
return resolvedVersion;
}
throw new Error(`Error trying to getRequestedVersion: ${err}`);
}
}
// ---------------------------------------------------------------------------
// Internal helpers
// ---------------------------------------------------------------------------
/**
* Computes a semver range for a version expressed in Fluid's internal/RC scheme
* (e.g. `2.0.0-internal.3.0.0`) after applying a negative `requested` delta.
*
* Handles several cross-tier edge cases:
* - RC → internal: going back far enough from an RC release crosses into internal releases.
* - internal → public 1.x / 0.x: going back from early 2.0.0-internal.x versions crosses
* into the public 1.x and pre-1.0 (0.xx) release lines.
* - Skipping RC tiers when the delta spans into the internal series from RC.
*/
function internalSchema(
publicVersion: string,
internalVersion: string,
prereleaseIdentifier: string,
requested: number,
): string {
if (requested === 0) {
return `${publicVersion}-${prereleaseIdentifier}.${internalVersion}`;
}
// Here we handle edge cases of converting the early rc/internal releases.
// We convert early rc releases to internal releases, and early internal releases to public releases.
if (prereleaseIdentifier === "rc" || prereleaseIdentifier === "dev-rc") {
if (semver.eq(publicVersion, "2.0.0")) {
const parsed = semver.parse(internalVersion);
assert(parsed !== null, "internalVersion should be parsable");
if (parsed.major + requested < 1) {
// If the request will evaluate to a pre-RC release, we need to convert the request
// to the equivalent internal release request.
return internalSchema("2.0.0", "8.0.0", "internal", requested + parsed.major);
}
}
} else if (semver.eq(publicVersion, "2.0.0") && semver.lt(internalVersion, "2.0.0")) {
if (requested === -1) {
return `^1.0.0-0`;
}
if (requested === -2) {
return `^0.59.0-0`;
}
}
if (
semver.eq(publicVersion, "2.0.0") &&
semver.gte(internalVersion, "2.0.0") &&
semver.lt(internalVersion, "3.0.0") &&
requested === -2
) {
return `^1.0.0-0`;
}
// if the version number is for the older version scheme before 1.0.0
if (
semver.eq(publicVersion, "2.0.0") &&
semver.lte(internalVersion, "2.0.0") &&
requested < -2
) {
const lastPrereleaseVersion = new semver.SemVer("0.59.0");
const requestedMinorVersion = lastPrereleaseVersion.minor + requested + 2;
return `^0.${requestedMinorVersion}.0-0`;
}
let parsedVersion;
let semverInternal: string = internalVersion;
// applied for all the baseVersion passed as 2.0.0-internal-3.0.0 or greater in 2.0.0 internal series
if (semver.gt(internalVersion, publicVersion) && requested <= -2) {
const parsed = new semver.SemVer(internalVersion);
semverInternal = (parsed.major + requested + 1).toString().concat(".0.0");
}
try {
parsedVersion = new semver.SemVer(semverInternal);
} catch (err: unknown) {
throw new Error(err as string);
}
// Convert any pre/dev release indicators to internal or rc; default to "internal"
const idToUse = prereleaseIdentifier.includes("rc") ? "rc" : "internal";
return `>=${publicVersion}-${idToUse}.${
parsedVersion.major - 1
}.0.0 <${publicVersion}-${idToUse}.${parsedVersion.major}.0.0`;
}