@effected/github-actions 0.1.0

package/WorkflowCommand.js

@@ -0,0 +1,100 @@
+//#region src/WorkflowCommand.ts
+/**
+* Escape a command's message.
+*
+* @remarks
+* The percent sign is replaced **first**, and the order is load-bearing: doing
+* it last would re-escape the `%` of an escape sequence this function just
+* produced, turning `%0A` into `%250A`.
+*/
+const escapeMessage = (value) => value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+/**
+* Escape a property value.
+*
+* @remarks
+* Everything a message escapes, plus `:` and `,` — the two characters that
+* delimit the property list and terminate it. An unescaped one truncates the
+* command or lets a value be read as a new property.
+*/
+const escapeProperty = (value) => escapeMessage(value).replaceAll(":", "%3A").replaceAll(",", "%2C");
+/**
+* The GitHub Actions workflow-command wire protocol: `::name key=value::message`.
+*
+* @remarks
+* **Pure.** This module renders strings and nothing else — it performs no IO
+* and holds no service — which is what makes the escaping rules testable
+* without a runner, and what lets a non-Actions consumer reuse the protocol.
+* Writing a rendered command to stdout is {@link ActionOutputs}'s job.
+*
+* The escaping is the whole point of the module. A message carrying a raw
+* newline does not merely render oddly: the runner reads the text after it as
+* a **new command**, so an unescaped log line is a command-injection vector.
+*
+* @example
+* ```ts
+* import { WorkflowCommand } from "@effected/github-actions";
+*
+* WorkflowCommand.error("build failed", { file: "src/main.ts", startLine: 12 });
+* // "::error file=src/main.ts,line=12::build failed"
+* ```
+*
+* @public
+*/
+var WorkflowCommand = class WorkflowCommand {
+	constructor() {}
+	/**
+	* Render an arbitrary command. The primitive every other member uses.
+	*
+	* @remarks
+	* The property type is written out structurally rather than as the module's
+	* `CommandProperties` alias: an internal named type on a `@public` signature
+	* fails the API Extractor gate, and neither an `@internal` tag nor a second
+	* alias helps — only inlining does.
+	*/
+	static render(name, properties, message) {
+		const rendered = Object.entries(properties).filter((entry) => entry[1] !== void 0).map(([key, value]) => `${key}=${escapeProperty(String(value))}`).join(",");
+		return `${rendered === "" ? `::${name}::` : `::${name} ${rendered}::`}${escapeMessage(message)}`;
+	}
+	/** `::debug::` — shown only when `ACTIONS_STEP_DEBUG` is enabled. */
+	static debug(message) {
+		return WorkflowCommand.render("debug", {}, message);
+	}
+	/** `::notice::` with optional source annotation. */
+	static notice(message, properties = {}) {
+		return WorkflowCommand.render("notice", WorkflowCommand.annotation(properties), message);
+	}
+	/** `::warning::` with optional source annotation. */
+	static warning(message, properties = {}) {
+		return WorkflowCommand.render("warning", WorkflowCommand.annotation(properties), message);
+	}
+	/** `::error::` with optional source annotation. */
+	static error(message, properties = {}) {
+		return WorkflowCommand.render("error", WorkflowCommand.annotation(properties), message);
+	}
+	/** `::group::` — opens a collapsible section in the runner log. */
+	static group(name) {
+		return WorkflowCommand.render("group", {}, name);
+	}
+	/** `::endgroup::` — closes the innermost open group. */
+	static endGroup() {
+		return WorkflowCommand.render("endgroup", {}, "");
+	}
+	/** `::add-mask::` — registers a value for redaction in the runner log. */
+	static addMask(value) {
+		return WorkflowCommand.render("add-mask", {}, value);
+	}
+	/** Map readable annotation fields onto GitHub's abbreviated wire names. */
+	static annotation(properties) {
+		return {
+			title: properties.title,
+			file: properties.file,
+			line: properties.startLine,
+			endLine: properties.endLine,
+			col: properties.startColumn,
+			endColumn: properties.endColumn
+		};
+	}
+};
+
+//#endregion
+export { WorkflowCommand };