project/lib/ui5Framework/AbstractResolver.js

  1. import path from "node:path";
  2. import os from "node:os";
  3. import {getLogger} from "@ui5/logger";
  4. const log = getLogger("ui5Framework:AbstractResolver");
  5. import semver from "semver";
  7. // Reduced Semantic Versioning pattern
  8. // Matches MAJOR or MAJOR.MINOR as a simple version range to be resolved to the latest minor/patch
  9. const VERSION_RANGE_REGEXP = /^(0|[1-9]\d*)(?:\.(0|[1-9]\d*))?(?:-SNAPSHOT)?$/;
  11. /**
  12.  * Abstract Resolver
  13.  *
  14.  * @abstract
  15.  * @public
  16.  * @class
  17.  * @alias @ui5/project/ui5Framework/AbstractResolver
  18.  * @hideconstructor
  19.  */
  20. class AbstractResolver {
  21. 	/* eslint-disable max-len */
  22. 	/**
  23. 	 * @param {*} options options
  24. 	 * @param {string} [options.version] Framework version to use. When omitted, all libraries need to be available
  25. 	 * via <code>providedLibraryMetadata</code> parameter. Otherwise an error is thrown.
  26. 	 * @param {boolean} [options.sources=false] Whether to install framework libraries as sources or
  27. 	 * 					pre-built (with build manifest)
  28. 	 * @param {string} [options.cwd=process.cwd()] Current working directory
  29. 	 * @param {string} [options.ui5HomeDir="~/.ui5"] UI5 home directory location. This will be used to store packages,
  30. 	 * metadata and configuration used by the resolvers. Relative to `process.cwd()`
  31. 	 * @param {object.<string, @ui5/project/ui5Framework/AbstractResolver~LibraryMetadataEntry>} [options.providedLibraryMetadata]
  32. 	 * Resolver skips installing listed libraries and uses the dependency information to resolve their dependencies.
  33. 	 * <code>version</code> can be omitted in case all libraries can be resolved via the <code>providedLibraryMetadata</code>.
  34. 	 * Otherwise an error is thrown.
  35. 	 */
  36. 	/* eslint-enable max-len */
  37. 	constructor({cwd, version, sources, ui5HomeDir, providedLibraryMetadata}) {
  38. 		if (new.target === AbstractResolver) {
  39. 			throw new TypeError("Class 'AbstractResolver' is abstract");
  40. 		}
  42. 		// In some CI environments, the homedir might be set explicitly to a relative
  43. 		// path (e.g. "./"), but tooling requires an absolute path
  44. 		this._ui5HomeDir = path.resolve(
  45. 			ui5HomeDir || path.join(os.homedir(), ".ui5")
  46. 		);
  47. 		this._cwd = cwd ? path.resolve(cwd) : process.cwd();
  48. 		this._version = version;
  50. 		// Environment variable should always enforce usage of sources
  51. 		if (process.env.UI5_PROJECT_USE_FRAMEWORK_SOURCES) {
  52. 			sources = true;
  53. 		}
  54. 		this._sources = !!sources;
  56. 		this._providedLibraryMetadata = providedLibraryMetadata;
  57. 	}
  59. 	async _processLibrary(libraryName, libraryMetadata, errors) {
  60. 		// Check if library is already processed
  61. 		if (libraryMetadata[libraryName]) {
  62. 			return;
  63. 		}
  64. 		// Mark library as handled
  65. 		libraryMetadata[libraryName] = Object.create(null);
  67. 		log.verbose("Processing " + libraryName);
  69. 		let promises;
  70. 		const providedLibraryMetadata = this._providedLibraryMetadata?.[libraryName];
  71. 		if (providedLibraryMetadata) {
  72. 			log.verbose(`Skipping install for ${libraryName} (provided)`);
  73. 			promises = {
  74. 				// Use existing metadata if library is provided from outside (e.g. workspace)
  75. 				metadata: Promise.resolve(providedLibraryMetadata),
  76. 				// Provided libraries are already "installed"
  77. 				install: Promise.resolve({
  78. 					pkgPath: providedLibraryMetadata.path
  79. 				})
  80. 			};
  81. 		} else if (!this._version) {
  82. 			throw new Error(`Unable to install library ${libraryName}. No framework version provided.`);
  83. 		} else {
  84. 			promises = await this.handleLibrary(libraryName);
  85. 		}
  87. 		const [metadata, {pkgPath}] = await Promise.all([
  88. 			promises.metadata.then((metadata) =>
  89. 				this._processDependencies(libraryName, metadata, libraryMetadata, errors)),
  90. 			promises.install
  91. 		]);
  93. 		// Add path to installed package to metadata
  94. 		metadata.path = pkgPath;
  96. 		// Add metadata entry
  97. 		libraryMetadata[libraryName] = metadata;
  98. 	}
  100. 	async _processDependencies(libraryName, metadata, libraryMetadata, errors) {
  101. 		if (metadata.dependencies.length > 0) {
  102. 			log.verbose("Processing dependencies of " + libraryName);
  103. 			await this._processLibraries(metadata.dependencies, libraryMetadata, errors);
  104. 			log.verbose("Done processing dependencies of " + libraryName);
  105. 		}
  106. 		return metadata;
  107. 	}
  109. 	async _processLibraries(libraryNames, libraryMetadata, errors) {
  110. 		const sourceErrors = new Set();
  111. 		const results = await Promise.all(libraryNames.map(async (libraryName) => {
  112. 			try {
  113. 				await this._processLibrary(libraryName, libraryMetadata, errors);
  114. 			} catch (err) {
  115. 				if (sourceErrors.has(err.message)) {
  116. 					return `Failed to resolve library ${libraryName}: Error already logged`;
  117. 				}
  118. 				sourceErrors.add(err.message);
  119. 				log.verbose(`Failed to process library ${libraryName}`);
  120. 				log.verbose(`Error: ${err.message}`);
  121. 				log.verbose(`Call stack: ${err.stack}`);
  122. 				return `Failed to resolve library ${libraryName}: ${err.message}`;
  123. 			}
  124. 		}));
  125. 		// Don't add empty results (success)
  126. 		errors.push(...results.filter(($) => $));
  127. 	}
  129. 	/**
  130. 	 * Library metadata entry
  131. 	 *
  132. 	 * @example
  133. 	 * const libraryMetadataEntry = {
  134. 	 *		"id": "@openui5/sap.ui.core",
  135. 	 *		"version": "1.75.0",
  136. 	 *		"path": "~/.ui5/framework/packages/@openui5/sap.ui.core/1.75.0",
  137. 	 *		"dependencies": [],
  138. 	 *		"optionalDependencies": []
  139. 	 * };
  140. 	 *
  141. 	 * @public
  142. 	 * @typedef {object} @ui5/project/ui5Framework/AbstractResolver~LibraryMetadataEntry
  143. 	 * @property {string} id Identifier
  144. 	 * @property {string} version Version
  145. 	 * @property {string} path Path
  146. 	 * @property {string[]} dependencies List of dependency ids
  147. 	 * @property {string[]} optionalDependencies List of optional dependency ids
  148. 	 */
  150. 	/**
  151. 	 * Install result
  152. 	 *
  153. 	 * @example
  154. 	 * const resolverInstallResult = {
  155. 	 * 	"libraryMetadata": {
  156. 	 * 		"sap.ui.core": {
  157. 	 * 			// ...
  158. 	 * 		},
  159. 	 * 		"sap.m": {
  160. 	 * 			// ...
  161. 	 * 		}
  162. 	 * 	}
  163. 	 * };
  164. 	 *
  165. 	 * @public
  166. 	 * @typedef {object} @ui5/project/ui5Framework/AbstractResolver~ResolverInstallResult
  167. 	 * @property {object.<string, @ui5/project/ui5Framework/AbstractResolver~LibraryMetadataEntry>} libraryMetadata
  168. 	 *   Object containing all installed libraries with library name as key
  169. 	 */
  171. 	/**
  172. 	 * Installs the provided libraries and their dependencies
  173. 	 *
  174. 	 * @example
  175. 	 * const resolver = new Sapui5Resolver({version: "1.76.0"});
  176. 	 * // Or for OpenUI5:
  177. 	 * // const resolver = new Openui5Resolver({version: "1.76.0"});
  178. 	 *
  179. 	 * resolver.install(["sap.ui.core", "sap.m"]).then(({libraryMetadata}) => {
  180. 	 * 	// Installation done
  181. 	 * }).catch((err) => {
  182. 	 * 	// Handle installation errors
  183. 	 * });
  184. 	 *
  185. 	 * @public
  186. 	 * @param {string[]} libraryNames List of library names to be installed
  187. 	 * @returns {@ui5/project/ui5Framework/AbstractResolver~ResolverInstallResult}
  188. 	 *   Resolves with an object containing the <code>libraryMetadata</code>
  189. 	 */
  190. 	async install(libraryNames) {
  191. 		const libraryMetadata = Object.create(null);
  192. 		const errors = [];
  194. 		await this._processLibraries(libraryNames, libraryMetadata, errors);
  196. 		if (errors.length === 1) {
  197. 			throw new Error(errors[0]);
  198. 		} if (errors.length > 1) {
  199. 			const msg = errors.map((err, idx) => `  ${idx + 1}. ${err}`).join("\n");
  200. 			throw new Error(`Resolution of framework libraries failed with errors:\n${msg}`);
  201. 		}
  203. 		return {
  204. 			libraryMetadata
  205. 		};
  206. 	}
  208. 	static async resolveVersion(version, {ui5HomeDir, cwd} = {}) {
  209. 		// Don't allow nullish values
  210. 		// An empty string is a valid semver range that converts to "*", which should not be supported
  211. 		if (!version) {
  212. 			throw new Error(`Framework version specifier "${version}" is incorrect or not supported`);
  213. 		}
  215. 		const spec = await this._getVersionSpec(version, {ui5HomeDir, cwd});
  217. 		// For all invalid cases which are not explicitly handled in _getVersionSpec
  218. 		if (!spec) {
  219. 			throw new Error(`Framework version specifier "${version}" is incorrect or not supported`);
  220. 		}
  222. 		const versions = await this.fetchAllVersions({ui5HomeDir, cwd});
  223. 		const resolvedVersion = semver.maxSatisfying(versions, spec, {
  224. 			// Allow ranges that end with -SNAPSHOT to match any -SNAPSHOT version
  225. 			// like a normal version in order to support ranges like 1.x.x-SNAPSHOT.
  226. 			includePrerelease: this._isSnapshotVersionOrRange(version)
  227. 		});
  229. 		if (!resolvedVersion) {
  230. 			if (semver.valid(spec)) {
  231. 				if (this.name === "Sapui5Resolver" && semver.lt(spec, "1.76.0")) {
  232. 					throw new Error(`Could not resolve framework version ${version}. ` +
  233. 						`Note that SAPUI5 framework libraries can only be consumed by the UI5 Tooling ` +
  234. 						`starting with SAPUI5 v1.76.0`);
  235. 				} else if (this.name === "Openui5Resolver" && semver.lt(spec, "1.52.5")) {
  236. 					throw new Error(`Could not resolve framework version ${version}. ` +
  237. 						`Note that OpenUI5 framework libraries can only be consumed by the UI5 Tooling ` +
  238. 						`starting with OpenUI5 v1.52.5`);
  239. 				}
  240. 			}
  241. 			throw new Error(
  242. 				`Could not resolve framework version ${version}. ` +
  243. 				`Make sure the version is valid and available in the configured registry.`);
  244. 		}
  246. 		return resolvedVersion;
  247. 	}
  249. 	static async _getVersionSpec(version, {ui5HomeDir, cwd}) {
  250. 		if (this._isSnapshotVersionOrRange(version)) {
  251. 			const versionMatch = version.match(VERSION_RANGE_REGEXP);
  252. 			if (versionMatch) {
  253. 				// For snapshot version ranges we need to insert a stand-in "x" for the patch level
  254. 				// and - in case none is provided - another "x" for the major version in order to
  255. 				// convert it to a valid semver range:
  256. 				// "1-SNAPSHOT" becomes "1.x.x-SNAPSHOT" and "1.112-SNAPSHOT" becomes "1.112.x-SNAPSHOT"
  257. 				return `${versionMatch[1]}.${versionMatch[2] || "x"}.x-SNAPSHOT`;
  258. 			}
  259. 		}
  261. 		// Covers versions and ranges, as versions are also valid ranges
  262. 		if (semver.validRange(version)) {
  263. 			return version;
  264. 		}
  266. 		// Check for invalid tag name (same check as npm does)
  267. 		if (encodeURIComponent(version) !== version) {
  268. 			return null;
  269. 		}
  271. 		const allTags = await this.fetchAllTags({ui5HomeDir, cwd});
  273. 		if (!allTags) {
  274. 			// Resolver doesn't support tags (e.g. Sapui5MavenSnapshotResolver)
  275. 			// Only latest and latest-snapshot are supported which both resolve
  276. 			// to the latest available version.
  277. 			// See "isSnapshotVersionOrRange" for -snapshot handling
  278. 			if ((version === "latest" || version === "latest-snapshot")) {
  279. 				return "*";
  280. 			} else {
  281. 				return null;
  282. 			}
  283. 		}
  285. 		if (!allTags[version]) {
  286. 			throw new Error(
  287. 				`Could not resolve framework version via tag '${version}'. ` +
  288. 				`Make sure the tag is available in the configured registry.`
  289. 			);
  290. 		}
  292. 		// Use version from tag
  293. 		return allTags[version];
  294. 	}
  296. 	static _isSnapshotVersionOrRange(version) {
  297. 		return version.toLowerCase().endsWith("-snapshot");
  298. 	}
  300. 	// To be implemented by resolver
  301. 	async getLibraryMetadata(libraryName) {
  302. 		throw new Error("AbstractResolver: getLibraryMetadata must be implemented!");
  303. 	}
  304. 	async handleLibrary(libraryName) {
  305. 		throw new Error("AbstractResolver: handleLibrary must be implemented!");
  306. 	}
  307. 	static fetchAllVersions(options) {
  308. 		throw new Error("AbstractResolver: static fetchAllVersions must be implemented!");
  309. 	}
  310. 	static fetchAllTags(options) {
  311. 		return null;
  312. 	}
  313. }
  315. export default AbstractResolver;