project/lib/specifications/Specification.js

  1. import path from "node:path";
  2. import {getLogger} from "@ui5/logger";
  3. import {createReader} from "@ui5/fs/resourceFactory";
  4. import SpecificationVersion from "./SpecificationVersion.js";
  6. /**
  7.  * Abstract superclass for all projects and extensions
  8.  *
  9.  * @public
  10.  * @abstract
  11.  * @class
  12.  * @alias @ui5/project/specifications/Specification
  13.  * @hideconstructor
  14.  */
  15. class Specification {
  16. 	/**
  17. 	 * Create a Specification instance for the given parameters
  18. 	 *
  19. 	 * @param {object} parameters
  20. 	 * @param {string} parameters.id Unique ID
  21. 	 * @param {string} parameters.version Version
  22. 	 * @param {string} parameters.modulePath Absolute File System path to access resources
  23. 	 * @param {object} parameters.configuration
  24. 	 *   Type-dependent configuration object. Typically defined in a ui5.yaml
  25. 	 * @static
  26. 	 * @public
  27. 	 */
  28. 	static async create(parameters) {
  29. 		if (!parameters.configuration) {
  30. 			throw new Error(
  31. 				`Unable to create Specification instance: Missing configuration parameter`);
  32. 		}
  33. 		const {kind, type} = parameters.configuration;
  34. 		if (!["project", "extension"].includes(kind)) {
  35. 			throw new Error(`Unable to create Specification instance: Unknown kind '${kind}'`);
  36. 		}
  38. 		switch (type) {
  39. 		case "application": {
  40. 			return createAndInitializeSpec("types/Application.js", parameters);
  41. 		}
  42. 		case "library": {
  43. 			return createAndInitializeSpec("types/Library.js", parameters);
  44. 		}
  45. 		case "theme-library": {
  46. 			return createAndInitializeSpec("types/ThemeLibrary.js", parameters);
  47. 		}
  48. 		case "module": {
  49. 			return createAndInitializeSpec("types/Module.js", parameters);
  50. 		}
  51. 		case "task": {
  52. 			return createAndInitializeSpec("extensions/Task.js", parameters);
  53. 		}
  54. 		case "server-middleware": {
  55. 			return createAndInitializeSpec("extensions/ServerMiddleware.js", parameters);
  56. 		}
  57. 		case "project-shim": {
  58. 			return createAndInitializeSpec("extensions/ProjectShim.js", parameters);
  59. 		}
  60. 		default:
  61. 			throw new Error(
  62. 				`Unable to create Specification instance: Unknown specification type '${type}'`);
  63. 		}
  64. 	}
  66. 	constructor() {
  67. 		if (new.target === Specification) {
  68. 			throw new TypeError("Class 'Specification' is abstract. Please use one of the 'types' subclasses");
  69. 		}
  70. 		this._log = getLogger(`specifications:types:${this.constructor.name}`);
  71. 	}
  73. 	/**
  74. 	 * @param {object} parameters Specification parameters
  75. 	 * @param {string} parameters.id Unique ID
  76. 	 * @param {string} parameters.version Version
  77. 	 * @param {string} parameters.modulePath Absolute File System path to access resources
  78. 	 * @param {object} parameters.configuration Configuration object
  79. 	 */
  80. 	async init({id, version, modulePath, configuration}) {
  81. 		if (!id) {
  82. 			throw new Error(`Could not create Specification: Missing or empty parameter 'id'`);
  83. 		}
  84. 		if (!version) {
  85. 			throw new Error(`Could not create Specification: Missing or empty parameter 'version'`);
  86. 		}
  87. 		if (!modulePath) {
  88. 			throw new Error(`Could not create Specification: Missing or empty parameter 'modulePath'`);
  89. 		}
  90. 		if (!path.isAbsolute(modulePath)) {
  91. 			throw new Error(`Could not create Specification: Parameter 'modulePath' must contain an absolute path`);
  92. 		}
  93. 		if (!configuration) {
  94. 			throw new Error(`Could not create Specification: Missing or empty parameter 'configuration'`);
  95. 		}
  97. 		this._version = version;
  98. 		this._modulePath = modulePath;
  100. 		// The ID property is filled from the provider (e.g. package.json "name") and might differ between providers.
  101. 		// It is mainly used to detect framework libraries marked by @openui5 / @sapui5 scopes of npm package.
  102. 		// (see Project#isFrameworkProject)
  103. 		// In general, the configured name (metadata.name) should be used instead as the unique identifier of a project.
  104. 		this.__id = id;
  106. 		// Deep clone config to prevent changes by reference
  107. 		const config = JSON.parse(JSON.stringify(configuration));
  108. 		const {validate} = await import("../validation/validator.js");
  110. 		if (SpecificationVersion.major(config.specVersion) <= 1) {
  111. 			const originalSpecVersion = config.specVersion;
  112. 			this._log.verbose(`Detected legacy Specification Version ${config.specVersion}, defined for ` +
  113. 				`${config.kind} ${config.metadata.name}. ` +
  114. 				`Attempting to migrate the project to a supported specification version...`);
  115. 			this._migrateLegacyProject(config);
  116. 			try {
  117. 				await validate({
  118. 					config,
  119. 					project: {
  120. 						id
  121. 					}
  122. 				});
  123. 			} catch (err) {
  124. 				this._log.verbose(
  125. 					`Validation error after migration of ${config.kind} ${config.metadata.name}:`);
  126. 				this._log.verbose(err.message);
  127. 				throw new Error(
  128. 					`${config.kind} ${config.metadata.name} defines unsupported Specification Version ` +
  129. 					`${originalSpecVersion}. Please manually upgrade to 3.0 or higher. ` +
  130. 					`For details see https://sap.github.io/ui5-tooling/pages/Configuration/#specification-versions - ` +
  131. 					`An attempted migration to a supported specification version failed, ` +
  132. 					`likely due to unrecognized configuration. Check verbose log for details.`);
  133. 			}
  134. 		} else {
  135. 			await validate({
  136. 				config,
  137. 				project: {
  138. 					id
  139. 				}
  140. 			});
  141. 		}
  143. 		// Check whether the given configuration matches the class by guessing the type name from the class name
  144. 		if (config.type.replace("-", "") !== this.constructor.name.toLowerCase()) {
  145. 			throw new Error(
  146. 				`Configuration mismatch: Supplied configuration of type '${config.type}' does not match with ` +
  147. 				`specification class ${this.constructor.name}`);
  148. 		}
  150. 		this._name = config.metadata.name;
  151. 		this._kind = config.kind;
  152. 		this._type = config.type;
  153. 		this._specVersionString = config.specVersion;
  154. 		this._specVersion = new SpecificationVersion(this._specVersionString);
  155. 		this._config = config;
  157. 		return this;
  158. 	}
  160. 	/* === Attributes === */
  161. 	/**
  162. 	 * Gets the ID of this specification.
  163. 	 *
  164. 	 * <p><b>Note: </b>Only to be used for special occasions as it is specific to the provider that was used and does
  165. 	 * not necessarily represent something defined by the project.</p>
  166. 	 *
  167. 	 * For general purposes of a unique identifier use
  168. 	 * {@link @ui5/project/specifications/Specification#getName getName} instead.
  169. 	 *
  170. 	 * @public
  171. 	 * @returns {string} Specification ID
  172. 	 */
  173. 	getId() {
  174. 		return this.__id;
  175. 	}
  177. 	/**
  178. 	 * Gets the name of this specification. Represents a unique identifier.
  179. 	 *
  180. 	 * @public
  181. 	 * @returns {string} Specification name
  182. 	 */
  183. 	getName() {
  184. 		return this._name;
  185. 	}
  187. 	/**
  188. 	 * Gets the kind of this specification, for example <code>project</code> or <code>extension</code>
  189. 	 *
  190. 	 * @public
  191. 	 * @returns {string} Specification kind
  192. 	 */
  193. 	getKind() {
  194. 		return this._kind;
  195. 	}
  197. 	/**
  198. 	 * Gets the type of this specification,
  199. 	 * for example <code>application</code> or <code>library</code> in case of projects,
  200. 	 * and <code>task</code> or <code>server-middleware</code> in case of extensions
  201. 	 *
  202. 	 * @public
  203. 	 * @returns {string} Specification type
  204. 	 */
  205. 	getType() {
  206. 		return this._type;
  207. 	}
  209. 	/**
  210. 	 * Returns an instance of a helper class representing a Specification Version
  211. 	 *
  212. 	 * @public
  213. 	 * @returns {@ui5/project/specifications/SpecificationVersion}
  214. 	 */
  215. 	getSpecVersion() {
  216. 		return this._specVersion;
  217. 	}
  219. 	/**
  220. 	 * Gets the specification's generic version, as typically defined in a <code>package.json</code>
  221. 	 *
  222. 	 * @public
  223. 	 * @returns {string} Project version
  224. 	 */
  225. 	getVersion() {
  226. 		return this._version;
  227. 	}
  229. 	/**
  230. 	 * Gets the specification's file system path. This might not be POSIX-style on some platforms
  231. 	 *
  232. 	 * @public
  233. 	 * @returns {string} Project root path
  234. 	 */
  235. 	getRootPath() {
  236. 		return this._modulePath;
  237. 	}
  239. 	/* === Resource Access === */
  240. 	/**
  241. 	 * Gets a [ReaderCollection]{@link @ui5/fs/ReaderCollection} for the root directory of the specification.
  242. 	 * Resource readers always use POSIX-style
  243. 	 *
  244. 	 * @public
  245. 	 * @param {object} [parameters] Parameters
  246. 	 * @param {object} [parameters.useGitignore=true]
  247. 	 *   Whether to apply any excludes defined in an optional .gitignore in the root directory
  248. 	 * @returns {@ui5/fs/ReaderCollection} Reader collection
  249. 	*/
  250. 	getRootReader({useGitignore=true} = {}) {
  251. 		return createReader({
  252. 			fsBasePath: this.getRootPath(),
  253. 			virBasePath: "/",
  254. 			name: `Root reader for ${this.getType()} ${this.getKind()} ${this.getName()}`,
  255. 			useGitignore
  256. 		});
  257. 	}
  259. 	/* === Internals === */
  260. 	/* === Helper === */
  261. 	/**
  262. 	 * @private
  263. 	 * @param {string} dirPath Directory path, relative to the specification root
  264. 	*/
  265. 	async _dirExists(dirPath) {
  266. 		const resource = await this.getRootReader().byPath(dirPath, {nodir: false});
  267. 		if (resource && resource.getStatInfo().isDirectory()) {
  268. 			return true;
  269. 		}
  270. 		return false;
  271. 	}
  273. 	_migrateLegacyProject(config) {
  274. 		// Stick to 2.6 since 3.0 adds further restrictions (i.e. for the name) and enables
  275. 		// functionality for extensions that shouldn't be enabled if the specVersion is not
  276. 		// explicitly set to 3.x
  277. 		config.specVersion = "2.6";
  279. 		// propertiesFileSourceEncoding (relevant for applications and libraries) default
  280. 		// has been changed to UTF-8 with specVersion 2.0
  281. 		// Adding back the old default if no configuration is provided.
  282. 		if (config.kind === "project" && ["application", "library"].includes(config.type) &&
  283. 				!config.resources?.configuration?.propertiesFileSourceEncoding) {
  284. 			config.resources = config.resources || {};
  285. 			config.resources.configuration = config.resources.configuration || {};
  286. 			config.resources.configuration.propertiesFileSourceEncoding = "ISO-8859-1";
  287. 		}
  288. 	}
  289. }
  291. async function createAndInitializeSpec(moduleName, params) {
  292. 	const {default: Spec} = await import(`./${moduleName}`);
  293. 	return new Spec().init(params);
  294. }
  296. export default Specification;