project/lib/specifications/types/Library.js

  1. import fsPath from "node:path";
  2. import posixPath from "node:path/posix";
  3. import {promisify} from "node:util";
  4. import ComponentProject from "../ComponentProject.js";
  5. import * as resourceFactory from "@ui5/fs/resourceFactory";
  7. /**
  8.  * Library
  9.  *
  10.  * @public
  11.  * @class
  12.  * @alias @ui5/project/specifications/types/Library
  13.  * @extends @ui5/project/specifications/ComponentProject
  14.  * @hideconstructor
  15.  */
  16. class Library extends ComponentProject {
  17. 	constructor(parameters) {
  18. 		super(parameters);
  20. 		this._pManifest = null;
  21. 		this._pDotLibrary = null;
  22. 		this._pLibraryJs = null;
  24. 		this._srcPath = "src";
  25. 		this._testPath = "test";
  26. 		this._testPathExists = false;
  27. 		this._isSourceNamespaced = true;
  29. 		this._propertiesFilesSourceEncoding = "UTF-8";
  30. 	}
  32. 	/* === Attributes === */
  33. 	/**
  34. 	*
  35. 	* @private
  36. 	*/
  37. 	getLibraryPreloadExcludes() {
  38. 		return this._config.builder && this._config.builder.libraryPreload &&
  39. 			this._config.builder.libraryPreload.excludes || [];
  40. 	}
  42. 	/**
  43. 	* @private
  44. 	*/
  45. 	getJsdocExcludes() {
  46. 		return this._config.builder && this._config.builder.jsdoc && this._config.builder.jsdoc.excludes || [];
  47. 	}
  49. 	/**
  50. 	 * Get the path of the project's source directory. This might not be POSIX-style on some platforms.
  51. 	 *
  52. 	 * @public
  53. 	 * @returns {string} Absolute path to the source directory of the project
  54. 	 */
  55. 	getSourcePath() {
  56. 		return fsPath.join(this.getRootPath(), this._srcPath);
  57. 	}
  59. 	/* === Resource Access === */
  60. 	/**
  61. 	* Get a resource reader for the sources of the project (excluding any test resources)
  62. 	*
  63. 	* @param {string[]} excludes List of glob patterns to exclude
  64. 	* @returns {@ui5/fs/ReaderCollection} Reader collection
  65. 	*/
  66. 	_getSourceReader(excludes) {
  67. 		// TODO: Throw for libraries with additional namespaces like sap.ui.core?
  68. 		let virBasePath = "/resources/";
  69. 		if (!this._isSourceNamespaced) {
  70. 			// In case the namespace is not represented in the source directory
  71. 			// structure, add it to the virtual base path
  72. 			virBasePath += `${this._namespace}/`;
  73. 		}
  74. 		return resourceFactory.createReader({
  75. 			fsBasePath: this.getSourcePath(),
  76. 			virBasePath,
  77. 			name: `Source reader for library project ${this.getName()}`,
  78. 			project: this,
  79. 			excludes
  80. 		});
  81. 	}
  83. 	/**
  84. 	* Get a resource reader for the test-resources of the project
  85. 	*
  86. 	* @param {string[]} excludes List of glob patterns to exclude
  87. 	* @returns {@ui5/fs/ReaderCollection} Reader collection
  88. 	*/
  89. 	_getTestReader(excludes) {
  90. 		if (!this._testPathExists) {
  91. 			return null;
  92. 		}
  93. 		let virBasePath = "/test-resources/";
  94. 		if (!this._isSourceNamespaced) {
  95. 			// In case the namespace is not represented in the source directory
  96. 			// structure, add it to the virtual base path
  97. 			virBasePath += `${this._namespace}/`;
  98. 		}
  99. 		const testReader = resourceFactory.createReader({
  100. 			fsBasePath: fsPath.join(this.getRootPath(), this._testPath),
  101. 			virBasePath,
  102. 			name: `Runtime test-resources reader for library project ${this.getName()}`,
  103. 			project: this,
  104. 			excludes
  105. 		});
  106. 		return testReader;
  107. 	}
  109. 	/**
  110. 	 * Get a resource reader for the sources of the project (excluding any test resources)
  111. 	 * without a virtual base path.
  112. 	 * In the future the path structure can be flat or namespaced depending on the project
  113. 	 * setup
  114. 	 *
  115. 	 * @returns {@ui5/fs/ReaderCollection} Reader collection
  116. 	*/
  117. 	_getRawSourceReader() {
  118. 		return resourceFactory.createReader({
  119. 			fsBasePath: this.getSourcePath(),
  120. 			virBasePath: "/",
  121. 			name: `Raw source reader for library project ${this.getName()}`,
  122. 			project: this
  123. 		});
  124. 	}
  126. 	/* === Internals === */
  127. 	/**
  128. 	 * @private
  129. 	 * @param {object} config Configuration object
  130. 	*/
  131. 	async _configureAndValidatePaths(config) {
  132. 		await super._configureAndValidatePaths(config);
  134. 		if (config.resources && config.resources.configuration && config.resources.configuration.paths) {
  135. 			if (config.resources.configuration.paths.src) {
  136. 				this._srcPath = config.resources.configuration.paths.src;
  137. 			}
  138. 			if (config.resources.configuration.paths.test) {
  139. 				this._testPath = config.resources.configuration.paths.test;
  140. 			}
  141. 		}
  142. 		if (!(await this._dirExists("/" + this._srcPath))) {
  143. 			throw new Error(
  144. 				`Unable to find source directory '${this._srcPath}' in library project ${this.getName()}`);
  145. 		}
  146. 		this._testPathExists = await this._dirExists("/" + this._testPath);
  148. 		this._log.verbose(`Path mapping for library project ${this.getName()}:`);
  149. 		this._log.verbose(`  Physical root path: ${this.getRootPath()}`);
  150. 		this._log.verbose(`  Mapped to:`);
  151. 		this._log.verbose(`    /resources/ => ${this._srcPath}`);
  152. 		this._log.verbose(
  153. 			`    /test-resources/ => ${this._testPath}${this._testPathExists ? "" : " [does not exist]"}`);
  154. 	}
  156. 	/**
  157. 	 * @private
  158. 	 * @param {object} config Configuration object
  159. 	 * @param {object} buildDescription Cache metadata object
  160. 	*/
  161. 	async _parseConfiguration(config, buildDescription) {
  162. 		await super._parseConfiguration(config, buildDescription);
  164. 		if (buildDescription) {
  165. 			this._namespace = buildDescription.namespace;
  166. 			return;
  167. 		}
  169. 		this._namespace = await this._getNamespace();
  171. 		if (!config.metadata.copyright) {
  172. 			const copyright = await this._getCopyrightFromDotLibrary();
  173. 			if (copyright) {
  174. 				config.metadata.copyright = copyright;
  175. 			}
  176. 		}
  178. 		if (this.isFrameworkProject()) {
  179. 			// Only framework projects are allowed to provide preload-excludes in their .library file,
  180. 			// and only if it is not already defined in the ui5.yaml
  181. 			if (config.builder?.libraryPreload?.excludes) {
  182. 				this._log.verbose(
  183. 					`Using preload excludes for framework library ${this.getName()} from project configuration`);
  184. 			} else {
  185. 				this._log.verbose(
  186. 					`No preload excludes defined in project configuration of framework library ` +
  187. 					`${this.getName()}. Falling back to .library...`);
  188. 				const excludes = await this._getPreloadExcludesFromDotLibrary();
  189. 				if (excludes) {
  190. 					if (!config.builder) {
  191. 						config.builder = {};
  192. 					}
  193. 					if (!config.builder.libraryPreload) {
  194. 						config.builder.libraryPreload = {};
  195. 					}
  196. 					config.builder.libraryPreload.excludes = excludes;
  197. 				}
  198. 			}
  199. 		}
  200. 	}
  202. 	/**
  203. 	 * Determine library namespace by checking manifest.json with fallback to .library.
  204. 	 * Any maven placeholders are resolved from the projects pom.xml
  205. 	 *
  206. 	 * @returns {string} Namespace of the project
  207. 	 * @throws {Error} if namespace can not be determined
  208. 	 */
  209. 	async _getNamespace() {
  210. 		// Trigger both reads asynchronously
  211. 		const [{
  212. 			namespace: manifestNs,
  213. 			filePath: manifestPath
  214. 		}, {
  215. 			namespace: dotLibraryNs,
  216. 			filePath: dotLibraryPath
  217. 		}] = await Promise.all([
  218. 			this._getNamespaceFromManifest(),
  219. 			this._getNamespaceFromDotLibrary()
  220. 		]);
  222. 		let libraryNs;
  223. 		let namespacePath;
  224. 		if (manifestNs && dotLibraryNs) {
  225. 			// Both files present
  226. 			// => check whether they are on the same level
  227. 			const manifestDepth = manifestPath.split("/").length;
  228. 			const dotLibraryDepth = dotLibraryPath.split("/").length;
  230. 			if (manifestDepth < dotLibraryDepth) {
  231. 				// We see the .library file as the "leading" file of a library
  232. 				// Therefore, a manifest.json on a higher level is something we do not except
  233. 				throw new Error(`Failed to detect namespace for project ${this.getName()}: ` +
  234. 					`Found a manifest.json on a higher directory level than the .library file. ` +
  235. 					`It should be on the same or a lower level. ` +
  236. 					`Note that a manifest.json on a lower level will be ignored.\n` +
  237. 					`  manifest.json path: ${manifestPath}\n` +
  238. 					`  is higher than\n` +
  239. 					`  .library path: ${dotLibraryPath}`);
  240. 			}
  241. 			if (manifestDepth === dotLibraryDepth) {
  242. 				if (posixPath.dirname(manifestPath) !== posixPath.dirname(dotLibraryPath)) {
  243. 					// This just should not happen in your project
  244. 					throw new Error(`Failed to detect namespace for project ${this.getName()}: ` +
  245. 					`Found a manifest.json on the same directory level but in a different directory ` +
  246. 					`than the .library file. They should be in the same directory.\n` +
  247. 					`  manifest.json path: ${manifestPath}\n` +
  248. 					`  is different to\n` +
  249. 					`  .library path: ${dotLibraryPath}`);
  250. 				}
  251. 				// Typical scenario if both files are present
  252. 				this._log.verbose(
  253. 					`Found a manifest.json and a .library file on the same level for ` +
  254. 					`project ${this.getName()}.`);
  255. 				this._log.verbose(
  256. 					`Resolving namespace of project ${this.getName()} from manifest.json...`);
  257. 				libraryNs = manifestNs;
  258. 				namespacePath = posixPath.dirname(manifestPath);
  259. 			} else {
  260. 				// Typical scenario: Some nested component has a manifest.json but the library itself only
  261. 				// features a .library.  => Ignore the manifest.json
  262. 				this._log.verbose(
  263. 					`Ignoring manifest.json found on a lower level than the .library file of ` +
  264. 					`project ${this.getName()}.`);
  265. 				this._log.verbose(
  266. 					`Resolving namespace of project ${this.getName()} from .library...`);
  267. 				libraryNs = dotLibraryNs;
  268. 				namespacePath = posixPath.dirname(dotLibraryPath);
  269. 			}
  270. 		} else if (manifestNs) {
  271. 			// Only manifest available
  272. 			this._log.verbose(
  273. 				`Resolving namespace of project ${this.getName()} from manifest.json...`);
  274. 			libraryNs = manifestNs;
  275. 			namespacePath = posixPath.dirname(manifestPath);
  276. 		} else if (dotLibraryNs) {
  277. 			// Only .library available
  278. 			this._log.verbose(
  279. 				`Resolving namespace of project ${this.getName()} from .library...`);
  280. 			libraryNs = dotLibraryNs;
  281. 			namespacePath = posixPath.dirname(dotLibraryPath);
  282. 		} else {
  283. 			this._log.verbose(
  284. 				`Failed to resolve namespace of project ${this.getName()} from manifest.json ` +
  285. 				`or .library file. Falling back to library.js file path...`);
  286. 		}
  288. 		let namespace;
  289. 		if (libraryNs) {
  290. 			// Maven placeholders can only exist in manifest.json or .library configuration
  291. 			if (this._hasMavenPlaceholder(libraryNs)) {
  292. 				try {
  293. 					libraryNs = await this._resolveMavenPlaceholder(libraryNs);
  294. 				} catch (err) {
  295. 					throw new Error(
  296. 						`Failed to resolve namespace maven placeholder of project ` +
  297. 						`${this.getName()}: ${err.message}`);
  298. 				}
  299. 			}
  301. 			namespace = libraryNs.replace(/\./g, "/");
  302. 			if (namespacePath === "/") {
  303. 				this._log.verbose(`Detected flat library source structure for project ${this.getName()}`);
  304. 				this._isSourceNamespaced = false;
  305. 			} else {
  306. 				namespacePath = namespacePath.replace("/", ""); // remove leading slash
  307. 				if (namespacePath !== namespace) {
  308. 					throw new Error(
  309. 						`Detected namespace "${namespace}" does not match detected directory ` +
  310. 						`structure "${namespacePath}" for project ${this.getName()}`);
  311. 				}
  312. 			}
  313. 		} else {
  314. 			try {
  315. 				const libraryJsPath = await this._getLibraryJsPath();
  316. 				namespacePath = posixPath.dirname(libraryJsPath);
  317. 				namespace = namespacePath.replace("/", ""); // remove leading slash
  318. 				if (namespace === "") {
  319. 					throw new Error(`Found library.js file in root directory. ` +
  320. 						`Expected it to be in namespace directory.`);
  321. 				}
  322. 				this._log.verbose(
  323. 					`Deriving namespace for project ${this.getName()} from ` +
  324. 					`path of library.js file`);
  325. 			} catch (err) {
  326. 				this._log.verbose(
  327. 					`Namespace resolution from library.js file path failed for project ` +
  328. 					`${this.getName()}: ${err.message}`);
  329. 			}
  330. 		}
  332. 		if (!namespace) {
  333. 			throw new Error(`Failed to detect namespace or namespace is empty for ` +
  334. 				`project ${this.getName()}. Check verbose log for details.`);
  335. 		}
  337. 		this._log.verbose(
  338. 			`Namespace of project ${this.getName()} is ${namespace}`);
  339. 		return namespace;
  340. 	}
  342. 	async _getNamespaceFromManifest() {
  343. 		try {
  344. 			const {content: manifest, filePath} = await this._getManifest();
  345. 			// check for a proper sap.app/id in manifest.json to determine namespace
  346. 			if (manifest["sap.app"] && manifest["sap.app"].id) {
  347. 				const namespace = manifest["sap.app"].id;
  348. 				this._log.verbose(
  349. 					`Found namespace ${namespace} in manifest.json of project ${this.getName()} ` +
  350. 					`at ${filePath}`);
  351. 				return {
  352. 					namespace,
  353. 					filePath
  354. 				};
  355. 			} else {
  356. 				throw new Error(
  357. 					`No sap.app/id configuration found in manifest.json of project ${this.getName()} ` +
  358. 					`at ${filePath}`);
  359. 			}
  360. 		} catch (err) {
  361. 			this._log.verbose(
  362. 				`Namespace resolution from manifest.json failed for project ` +
  363. 				`${this.getName()}: ${err.message}`);
  364. 		}
  365. 		return {};
  366. 	}
  368. 	async _getNamespaceFromDotLibrary() {
  369. 		try {
  370. 			const {content: dotLibrary, filePath} = await this._getDotLibrary();
  371. 			const namespace = dotLibrary?.library?.name?._;
  372. 			if (namespace) {
  373. 				this._log.verbose(
  374. 					`Found namespace ${namespace} in .library file of project ${this.getName()} ` +
  375. 					`at ${filePath}`);
  376. 				return {
  377. 					namespace,
  378. 					filePath
  379. 				};
  380. 			} else {
  381. 				throw new Error(
  382. 					`No library name found in .library of project ${this.getName()} ` +
  383. 					`at ${filePath}`);
  384. 			}
  385. 		} catch (err) {
  386. 			this._log.verbose(
  387. 				`Namespace resolution from .library failed for project ` +
  388. 				`${this.getName()}: ${err.message}`);
  389. 		}
  390. 		return {};
  391. 	}
  393. 	/**
  394. 	 * Determines library copyright from given project configuration with fallback to .library.
  395. 	 *
  396. 	 * @returns {string|null} Copyright of the project
  397. 	 */
  398. 	async _getCopyrightFromDotLibrary() {
  399. 		try {
  400. 			// If no copyright replacement was provided by ui5.yaml,
  401. 			// check if the .library file has a valid copyright replacement
  402. 			const {content: dotLibrary, filePath} = await this._getDotLibrary();
  403. 			if (dotLibrary?.library?.copyright?._) {
  404. 				this._log.verbose(
  405. 					`Using copyright from ${filePath} for project ${this.getName()}...`);
  406. 				return dotLibrary.library.copyright._;
  407. 			} else {
  408. 				this._log.verbose(
  409. 					`No copyright configuration found in ${filePath} ` +
  410. 					`of project ${this.getName()}`);
  411. 				return null;
  412. 			}
  413. 		} catch (err) {
  414. 			this._log.verbose(
  415. 				`Copyright determination from .library failed for project ` +
  416. 				`${this.getName()}: ${err.message}`);
  417. 			return null;
  418. 		}
  419. 	}
  421. 	async _getPreloadExcludesFromDotLibrary() {
  422. 		const {content: dotLibrary, filePath} = await this._getDotLibrary();
  423. 		let excludes = dotLibrary?.library?.appData?.packaging?.["all-in-one"]?.exclude;
  424. 		if (excludes) {
  425. 			if (!Array.isArray(excludes)) {
  426. 				excludes = [excludes];
  427. 			}
  428. 			this._log.verbose(
  429. 				`Found ${excludes.length} preload excludes in .library file of ` +
  430. 				`project ${this.getName()} at ${filePath}`);
  431. 			return excludes.map((exclude) => {
  432. 				return exclude.$.name;
  433. 			});
  434. 		} else {
  435. 			this._log.verbose(
  436. 				`No preload excludes found in .library of project ${this.getName()} ` +
  437. 				`at ${filePath}`);
  438. 			return null;
  439. 		}
  440. 	}
  442. 	/**
  443. 	 * Reads the projects manifest.json
  444. 	 *
  445. 	 * @returns {Promise<object>} resolves with an object containing the <code>content</code> (as JSON) and
  446. 	 * 							<code>filePath</code> (as string) of the manifest.json file
  447. 	 */
  448. 	async _getManifest() {
  449. 		if (this._pManifest) {
  450. 			return this._pManifest;
  451. 		}
  452. 		return this._pManifest = this._getRawSourceReader().byGlob("**/manifest.json")
  453. 			.then(async (manifestResources) => {
  454. 				if (!manifestResources.length) {
  455. 					throw new Error(`Could not find manifest.json file for project ${this.getName()}`);
  456. 				}
  457. 				if (manifestResources.length > 1) {
  458. 					throw new Error(`Found multiple (${manifestResources.length}) manifest.json files ` +
  459. 						`for project ${this.getName()}`);
  460. 				}
  461. 				const resource = manifestResources[0];
  462. 				try {
  463. 					return {
  464. 						content: JSON.parse(await resource.getString()),
  465. 						filePath: resource.getPath()
  466. 					};
  467. 				} catch (err) {
  468. 					throw new Error(
  469. 						`Failed to read ${resource.getPath()} for project ${this.getName()}: ${err.message}`);
  470. 				}
  471. 			});
  472. 	}
  474. 	/**
  475. 	 * Reads the .library file
  476. 	 *
  477. 	 * @returns {Promise<object>} resolves with an object containing the <code>content</code> (as JSON) and
  478. 	 * 							<code>filePath</code> (as string) of the .library file
  479. 	 */
  480. 	async _getDotLibrary() {
  481. 		if (this._pDotLibrary) {
  482. 			return this._pDotLibrary;
  483. 		}
  484. 		return this._pDotLibrary = this._getRawSourceReader().byGlob("**/.library")
  485. 			.then(async (dotLibraryResources) => {
  486. 				if (!dotLibraryResources.length) {
  487. 					throw new Error(`Could not find .library file for project ${this.getName()}`);
  488. 				}
  489. 				if (dotLibraryResources.length > 1) {
  490. 					throw new Error(`Found multiple (${dotLibraryResources.length}) .library files ` +
  491. 						`for project ${this.getName()}`);
  492. 				}
  493. 				const resource = dotLibraryResources[0];
  494. 				const content = await resource.getString();
  496. 				try {
  497. 					const {
  498. 						default: xml2js
  499. 					} = await import("xml2js");
  500. 					const parser = new xml2js.Parser({
  501. 						explicitArray: false,
  502. 						explicitCharkey: true
  503. 					});
  504. 					const readXML = promisify(parser.parseString);
  505. 					return {
  506. 						content: await readXML(content),
  507. 						filePath: resource.getPath()
  508. 					};
  509. 				} catch (err) {
  510. 					throw new Error(
  511. 						`Failed to read ${resource.getPath()} for project ${this.getName()}: ${err.message}`);
  512. 				}
  513. 			});
  514. 	}
  516. 	/**
  517. 	 * Determines the path of the library.js file
  518. 	 *
  519. 	 * @returns {Promise<string>} resolves with an a string containing the file system path
  520. 	 *								of the library.js file
  521. 	 */
  522. 	async _getLibraryJsPath() {
  523. 		if (this._pLibraryJs) {
  524. 			return this._pLibraryJs;
  525. 		}
  526. 		return this._pLibraryJs = this._getRawSourceReader().byGlob("**/library.js")
  527. 			.then(async (libraryJsResources) => {
  528. 				if (!libraryJsResources.length) {
  529. 					throw new Error(`Could not find library.js file for project ${this.getName()}`);
  530. 				}
  531. 				if (libraryJsResources.length > 1) {
  532. 					throw new Error(`Found multiple (${libraryJsResources.length}) library.js files ` +
  533. 						`for project ${this.getName()}`);
  534. 				}
  535. 				// Content is not yet relevant, so don't read it
  536. 				return libraryJsResources[0].getPath();
  537. 			});
  538. 	}
  539. }
  541. export default Library;