builder/lib/types/AbstractBuilder.js

  2. /**
  3.  * Resource collections
  4.  *
  5.  * @public
  6.  * @typedef module:@ui5/builder.BuilderResourceCollections
  7.  * @property {module:@ui5/fs.DuplexCollection} workspace Workspace Resource
  8.  * @property {module:@ui5/fs.ReaderCollection} dependencies Workspace Resource
  9.  */
  11. /**
  12.  * Base class for the builder implementation of a project type
  13.  *
  14.  * @abstract
  15.  */
  16. class AbstractBuilder {
  17. 	/**
  18. 	 * Constructor
  19. 	 *
  20. 	 * @param {object} parameters
  21. 	 * @param {BuilderResourceCollections} parameters.resourceCollections Resource collections
  22. 	 * @param {object} parameters.project Project configuration
  23. 	 * @param {GroupLogger} parameters.parentLogger Logger to use
  24. 	 * @param {object} parameters.taskUtil
  25. 	 */
  26. 	constructor({resourceCollections, project, parentLogger, taskUtil}) {
  27. 		if (new.target === AbstractBuilder) {
  28. 			throw new TypeError("Class 'AbstractBuilder' is abstract");
  29. 		}
  31. 		this.project = project;
  33. 		this.log = parentLogger.createSubLogger(project.type + " " + project.metadata.name, 0.2);
  34. 		this.taskLog = this.log.createTaskLogger("🔨");
  36. 		this.tasks = {};
  37. 		this.taskExecutionOrder = [];
  38. 		this.addStandardTasks({
  39. 			resourceCollections,
  40. 			project,
  41. 			log: this.log,
  42. 			taskUtil
  43. 		});
  44. 		this.addCustomTasks({
  45. 			resourceCollections,
  46. 			project,
  47. 			taskUtil
  48. 		});
  49. 	}
  51. 	/**
  52. 	 * Adds all standard tasks to execute
  53. 	 *
  54. 	 * @abstract
  55. 	 * @protected
  56. 	 * @param {object} parameters
  57. 	 * @param {BuilderResourceCollections} parameters.resourceCollections Resource collections
  58. 	 * @param {object} parameters.taskUtil
  59. 	 * @param {object} parameters.project Project configuration
  60. 	 * @param {object} parameters.log <code>@ui5/logger</code> logger instance
  61. 	 */
  62. 	addStandardTasks({resourceCollections, project, log, taskUtil}) {
  63. 		throw new Error("Function 'addStandardTasks' is not implemented");
  64. 	}
  66. 	/**
  67. 	 * Adds custom tasks to execute
  68. 	 *
  69. 	 * @private
  70. 	 * @param {object} parameters
  71. 	 * @param {BuilderResourceCollections} parameters.resourceCollections Resource collections
  72. 	 * @param {object} parameters.taskUtil
  73. 	 * @param {object} parameters.project Project configuration
  74. 	 */
  75. 	addCustomTasks({resourceCollections, project, taskUtil}) {
  76. 		const projectCustomTasks = project.builder && project.builder.customTasks;
  77. 		if (!projectCustomTasks || projectCustomTasks.length === 0) {
  78. 			return; // No custom tasks defined
  79. 		}
  80. 		const taskRepository = require("../tasks/taskRepository");
  81. 		for (let i = 0; i < projectCustomTasks.length; i++) {
  82. 			const taskDef = projectCustomTasks[i];
  83. 			if (!taskDef.name) {
  84. 				throw new Error(`Missing name for custom task definition of project ${project.metadata.name} ` +
  85. 					`at index ${i}`);
  86. 			}
  87. 			if (taskDef.beforeTask && taskDef.afterTask) {
  88. 				throw new Error(`Custom task definition ${taskDef.name} of project ${project.metadata.name} ` +
  89. 					`defines both "beforeTask" and "afterTask" parameters. Only one must be defined.`);
  90. 			}
  91. 			if (this.taskExecutionOrder.length && !taskDef.beforeTask && !taskDef.afterTask) {
  92. 				// Iff there are tasks configured, beforeTask or afterTask must be given
  93. 				throw new Error(`Custom task definition ${taskDef.name} of project ${project.metadata.name} ` +
  94. 					`defines neither a "beforeTask" nor an "afterTask" parameter. One must be defined.`);
  95. 			}
  97. 			let newTaskName = taskDef.name;
  98. 			if (this.tasks[newTaskName]) {
  99. 				// Task is already known
  100. 				// => add a suffix to allow for multiple configurations of the same task
  101. 				let suffixCounter = 0;
  102. 				while (this.tasks[newTaskName]) {
  103. 					suffixCounter++; // Start at 1
  104. 					newTaskName = `${taskDef.name}--${suffixCounter}`;
  105. 				}
  106. 			}
  107. 			// Create custom task if not already done (task might be referenced multiple times, first one wins)
  108. 			const {specVersion, task} = taskRepository.getTask(taskDef.name);
  109. 			const execTask = function() {
  110. 				/* Custom Task Interface
  111. 					Parameters:
  112. 						{Object} parameters Parameters
  113. 						{module:@ui5/fs.DuplexCollection} parameters.workspace DuplexCollection to read and write files
  114. 						{module:@ui5/fs.AbstractReader} parameters.dependencies
  115. 							Reader or Collection to read dependency files
  116. 						{Object} parameters.taskUtil Specification Version dependent interface to a
  117. 							[TaskUtil]{@link module:@ui5/builder.tasks.TaskUtil} instance
  118. 						{Object} parameters.options Options
  119. 						{string} parameters.options.projectName Project name
  120. 						{string} [parameters.options.projectNamespace] Project namespace if available
  121. 						{string} [parameters.options.configuration] Task configuration if given in ui5.yaml
  122. 					Returns:
  123. 						{Promise<undefined>} Promise resolving with undefined once data has been written
  124. 				*/
  125. 				const params = {
  126. 					workspace: resourceCollections.workspace,
  127. 					dependencies: resourceCollections.dependencies,
  128. 					options: {
  129. 						projectName: project.metadata.name,
  130. 						projectNamespace: project.metadata.namespace,
  131. 						configuration: taskDef.configuration
  132. 					}
  133. 				};
  135. 				const taskUtilInterface = taskUtil.getInterface(specVersion);
  136. 				// Interface is undefined if specVersion does not support taskUtil
  137. 				if (taskUtilInterface) {
  138. 					params.taskUtil = taskUtilInterface;
  139. 				}
  140. 				return task(params);
  141. 			};
  143. 			this.tasks[newTaskName] = execTask;
  145. 			if (this.taskExecutionOrder.length) {
  146. 				// There is at least one task configured. Use before- and afterTask to add the custom task
  147. 				const refTaskName = taskDef.beforeTask || taskDef.afterTask;
  148. 				let refTaskIdx = this.taskExecutionOrder.indexOf(refTaskName);
  149. 				if (refTaskIdx === -1) {
  150. 					throw new Error(`Could not find task ${refTaskName}, referenced by custom task ${newTaskName}, ` +
  151. 						`to be scheduled for project ${project.metadata.name}`);
  152. 				}
  153. 				if (taskDef.afterTask) {
  154. 					// Insert after index of referenced task
  155. 					refTaskIdx++;
  156. 				}
  157. 				this.taskExecutionOrder.splice(refTaskIdx, 0, newTaskName);
  158. 			} else {
  159. 				// There is no task configured so far. Just add the custom task
  160. 				this.taskExecutionOrder.push(newTaskName);
  161. 			}
  162. 		}
  163. 	}
  165. 	/**
  166. 	 * Adds a executable task to the builder
  167. 	 *
  168. 	 * The order this function is being called defines the build order. FIFO.
  169. 	 *
  170. 	 * @param {string} taskName Name of the task which should be in the list availableTasks.
  171. 	 * @param {Function} taskFunction
  172. 	 */
  173. 	addTask(taskName, taskFunction) {
  174. 		if (this.tasks[taskName]) {
  175. 			throw new Error(`Failed to add duplicate task ${taskName} for project ${this.project.metadata.name}`);
  176. 		}
  177. 		if (this.taskExecutionOrder.includes(taskName)) {
  178. 			throw new Error(`Builder: Failed to add task ${taskName} for project ${this.project.metadata.name}. ` +
  179. 				`It has already been scheduled for execution.`);
  180. 		}
  181. 		this.tasks[taskName] = taskFunction;
  182. 		this.taskExecutionOrder.push(taskName);
  183. 	}
  185. 	/**
  186. 	 * Check whether a task is defined
  187. 	 *
  188. 	 * @private
  189. 	 * @param {string} taskName
  190. 	 * @returns {boolean}
  191. 	 */
  192. 	hasTask(taskName) {
  193. 		// TODO 3.0: Check whether this method is still required.
  194. 		// Only usage within #build seems to be unnecessary as all tasks are also added to the taskExecutionOrder
  195. 		return Object.prototype.hasOwnProperty.call(this.tasks, taskName);
  196. 	}
  198. 	/**
  199. 	 * Takes a list of tasks which should be executed from the available task list of the current builder
  200. 	 *
  201. 	 * @param {Array} tasksToRun List of tasks which should be executed
  202. 	 * @returns {Promise} Returns promise chain with tasks
  203. 	 */
  204. 	build(tasksToRun) {
  205. 		const allTasks = this.taskExecutionOrder.filter((taskName) => {
  206. 			// There might be a numeric suffix in case a custom task is configured multiple times.
  207. 			// The suffix needs to be removed in order to check against the list of tasks to run.
  208. 			//
  209. 			// Note: The 'tasksToRun' parameter only allows to specify the custom task name
  210. 			// (without suffix), so it executes either all or nothing.
  211. 			// It's currently not possible to just execute some occurrences of a custom task.
  212. 			// This would require a more robust contract to identify task executions
  213. 			// (e.g. via an 'id' that can be assigned to a specific execution in the configuration).
  214. 			const taskWithoutSuffixCounter = taskName.replace(/--\d+$/, "");
  215. 			return this.hasTask(taskName) && tasksToRun.includes(taskWithoutSuffixCounter);
  216. 		});
  218. 		this.taskLog.addWork(allTasks.length);
  220. 		return allTasks.reduce((taskChain, taskName) => {
  221. 			const taskFunction = this.tasks[taskName];
  223. 			if (typeof taskFunction === "function") {
  224. 				taskChain = taskChain.then(this.wrapTask(taskName, taskFunction));
  225. 			}
  227. 			return taskChain;
  228. 		}, Promise.resolve());
  229. 	}
  231. 	/**
  232. 	 * Adds progress related functionality to task function.
  233. 	 *
  234. 	 * @private
  235. 	 * @param {string} taskName Name of the task
  236. 	 * @param {Function} taskFunction Function which executed the task
  237. 	 * @returns {Function} Wrapped task function
  238. 	 */
  239. 	wrapTask(taskName, taskFunction) {
  240. 		return () => {
  241. 			this.taskLog.startWork(`Running task ${taskName}...`);
  242. 			return taskFunction().then(() => this.taskLog.completeWork(1));
  243. 		};
  244. 	}
  246. 	/**
  247. 	 * Appends the list of 'excludes' to the list of 'patterns'. To harmonize both lists, the 'excludes'
  248. 	 * are negated and the 'patternPrefix' is added to make them absolute.
  249. 	 *
  250. 	 * @private
  251. 	 * @param {string[]} patterns
  252. 	 *   List of absolute default patterns.
  253. 	 * @param {string[]} excludes
  254. 	 *   List of relative patterns to be excluded. Excludes with a leading "!" are meant to be re-included.
  255. 	 * @param {string} patternPrefix
  256. 	 *   Prefix to be added to the excludes to make them absolute. The prefix must have a leading and a
  257. 	 *   trailing "/".
  258. 	 */
  259. 	enhancePatternWithExcludes(patterns, excludes, patternPrefix) {
  260. 		excludes.forEach((exclude) => {
  261. 			if (exclude.startsWith("!")) {
  262. 				patterns.push(`${patternPrefix}${exclude.slice(1)}`);
  263. 			} else {
  264. 				patterns.push(`!${patternPrefix}${exclude}`);
  265. 			}
  266. 		});
  267. 	}
  268. }
  270. module.exports = AbstractBuilder;