@effected/github-actions 0.12.0 → 0.13.0

package/ActionOutputs.js

@@ -103,6 +103,44 @@ const delimiterFor = (value) => {
 };
 /** A name that would break the block structure it lives in. */
 const isUsableName = (name) => name !== "" && !/[\r\n]/.test(name);
+/**
+* The JSON text `setJson` publishes for `value`: encoded through `schema`,
+* then stringified. The one step of `setJson` that can fail, shared by the
+* real layer and both test doubles so that none of them can skip it.
+*/
+const encodeJson = (name, value, schema) => Schema.encodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => new OutputEncodeError({
+	name,
+	cause
+})), Effect.map((encoded) => JSON.stringify(encoded)));
+/**
+* One call an {@link ActionOutputs.recording} double observed.
+*
+* @remarks
+* `value` is always the string the runner would have seen: for `setJson` that
+* is the **encoded** JSON text, after the same schema encode the real layer
+* performs, so a test asserting on it reads exactly what a later step's
+* `steps.<id>.outputs.<name>` expression would. `name` is present for the
+* members that take one (`set`, `setJson`, `exportVariable`) and absent
+* otherwise.
+*
+* @public
+*/
+var RecordedOutput = class extends Schema.Class("RecordedOutput")({
+	/** Which {@link ActionOutputsShape} member was called. */
+	member: Schema.Literals([
+		"set",
+		"setJson",
+		"summary",
+		"exportVariable",
+		"addPath",
+		"setFailed",
+		"setSecret"
+	]),
+	/** The output or variable name, for the members that take one. */
+	name: Schema.optionalKey(Schema.String),
+	/** What was published — value, message, path, content or secret — as the runner would have read it. */
+	value: Schema.String
+}) {};
 const make = Effect.gen(function* () {
 	const env = yield* ActionEnvironment;
 	const fs = yield* FileSystem.FileSystem;
@@ -124,10 +162,7 @@ const make = Effect.gen(function* () {
 	const set = (name, value) => appendBlock("GITHUB_OUTPUT", name, value);
 	return {
 		set,
-		setJson: (name, value, schema) => Schema.encodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => new OutputEncodeError({
-			name,
-			cause
-		})), Effect.flatMap((encoded) => set(name, JSON.stringify(encoded)))),
+		setJson: (name, value, schema) => encodeJson(name, value, schema).pipe(Effect.flatMap((json) => set(name, json))),
 		summary: (content) => append("GITHUB_STEP_SUMMARY", content),
 		exportVariable: (name, value) => appendBlock("GITHUB_ENV", name, value),
 		addPath: (path) => append("GITHUB_PATH", `${path}\n`),
@@ -211,20 +246,90 @@ var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/git
 		setFailed: (message) => Console.error(message),
 		setSecret: () => Effect.void
 	});
-	/** A test double. Unstubbed members die rather than silently succeeding. */
-	static makeTest = (overrides = {}) => ({
-		set: () => Effect.sync(() => unimplemented("set")),
-		setJson: () => Effect.sync(() => unimplemented("setJson")),
-		summary: () => Effect.sync(() => unimplemented("summary")),
-		exportVariable: () => Effect.sync(() => unimplemented("exportVariable")),
-		addPath: () => Effect.sync(() => unimplemented("addPath")),
-		setFailed: () => Effect.sync(() => unimplemented("setFailed")),
-		setSecret: () => Effect.sync(() => unimplemented("setSecret")),
-		...overrides
-	});
+	/**
+	* A test double. Unstubbed members die rather than silently succeeding.
+	*
+	* @remarks
+	* **`setJson` always encodes first.** The value is encoded through its
+	* schema exactly as the real layer does — failing typed with
+	* {@link OutputEncodeError} — and only then is a supplied `setJson`
+	* override called, with the original `(name, value, schema)`. An override
+	* that accepts `schema` and ignores it therefore **cannot disable
+	* output-schema checking**: a value/schema drift is a typed failure under
+	* this double whether or not the override looks at the schema. Without an
+	* override, a valid value still dies unimplemented as every other unstubbed
+	* member does. Most tests want neither: reach for
+	* {@link ActionOutputs.recording} instead.
+	*/
+	static makeTest = (overrides = {}) => {
+		const setJson = overrides.setJson ?? (() => Effect.sync(() => unimplemented("setJson")));
+		return {
+			set: () => Effect.sync(() => unimplemented("set")),
+			summary: () => Effect.sync(() => unimplemented("summary")),
+			exportVariable: () => Effect.sync(() => unimplemented("exportVariable")),
+			addPath: () => Effect.sync(() => unimplemented("addPath")),
+			setFailed: () => Effect.sync(() => unimplemented("setFailed")),
+			setSecret: () => Effect.sync(() => unimplemented("setSecret")),
+			...overrides,
+			setJson: (name, value, schema) => encodeJson(name, value, schema).pipe(Effect.flatMap(() => setJson(name, value, schema)))
+		};
+	};
 	/** {@link ActionOutputs.makeTest} behind `Layer.succeed`. */
 	static layerTest = (overrides = {}) => Layer.succeed(ActionOutputs, ActionOutputs.makeTest(overrides));
+	/**
+	* A recording double: every member appends a {@link RecordedOutput} to a
+	* journal the test reads back, in call order.
+	*
+	* @remarks
+	* This is the double most tests of an action want — "what did it publish?"
+	* — shipped so that nobody hand-writes a `setJson` override that drops the
+	* schema encode (the trap `makeTest` now closes too). `setJson` encodes
+	* through its schema exactly as the real layer does, failing typed with
+	* {@link OutputEncodeError} and recording nothing on a drift, and records
+	* the **encoded JSON text** — what the runner would have read — not the
+	* decoded value. `set`, `exportVariable` and `setJson` refuse an unusable
+	* name with {@link InvalidOutputNameError}, as the real layer does, rather
+	* than recording it.
+	*
+	* `setSecret` records the secret's **plaintext** under
+	* `member: "setSecret"`. That is deliberate for a recording double: the
+	* journal never leaves the test, and a test asserting that a value *was*
+	* masked needs to see which one. Do not hand this journal to anything that
+	* logs.
+	*
+	* Each call returns a fresh, independent journal — there is no state shared
+	* between two `recording()` calls.
+	*/
+	static recording = () => {
+		const entries = [];
+		const record = (member, value, name) => Effect.sync(() => {
+			entries.push(RecordedOutput.make({
+				member,
+				value,
+				...name === void 0 ? {} : { name }
+			}));
+		});
+		const recordNamed = (member, file, name, value) => isUsableName(name) ? record(member, value, name) : Effect.fail(new InvalidOutputNameError({
+			file,
+			name
+		}));
+		return {
+			layer: Layer.succeed(ActionOutputs, {
+				set: (name, value) => recordNamed("set", "GITHUB_OUTPUT", name, value),
+				setJson: (name, value, schema) => isUsableName(name) ? encodeJson(name, value, schema).pipe(Effect.flatMap((json) => record("setJson", json, name))) : Effect.fail(new InvalidOutputNameError({
+					file: "GITHUB_OUTPUT",
+					name
+				})),
+				summary: (content) => record("summary", content),
+				exportVariable: (name, value) => recordNamed("exportVariable", "GITHUB_ENV", name, value),
+				addPath: (path) => record("addPath", path),
+				setFailed: (message) => record("setFailed", message),
+				setSecret: (value) => record("setSecret", value)
+			}),
+			entries: () => entries.slice()
+		};
+	};
 };
 
 //#endregion
-export { ActionOutputs, DetachedOutputError, InvalidOutputNameError, OutputEncodeError, RunnerFileUnavailableError, RunnerFileWriteError };
+export { ActionOutputs, DetachedOutputError, InvalidOutputNameError, OutputEncodeError, RecordedOutput, RunnerFileUnavailableError, RunnerFileWriteError };

package/index.d.ts

@@ -586,6 +586,46 @@ export declare class DetachedOutputError extends DetachedOutputError_base {
  * @public
  */
 type ActionOutputError = RunnerFileUnavailableError | RunnerFileWriteError | InvalidOutputNameError | OutputEncodeError | DetachedOutputError;
+declare const RecordedOutput_base: Schema.Class<RecordedOutput, Schema.Struct<{
+  /** Which {@link ActionOutputsShape} member was called. */
+  readonly member: Schema.Literals<readonly ["set", "setJson", "summary", "exportVariable", "addPath", "setFailed", "setSecret"]>;
+  /** The output or variable name, for the members that take one. */
+  readonly name: Schema.optionalKey<Schema.String>;
+  /** What was published — value, message, path, content or secret — as the runner would have read it. */
+  readonly value: Schema.String;
+}>, {}>;
+/**
+ * One call an {@link ActionOutputs.recording} double observed.
+ *
+ * @remarks
+ * `value` is always the string the runner would have seen: for `setJson` that
+ * is the **encoded** JSON text, after the same schema encode the real layer
+ * performs, so a test asserting on it reads exactly what a later step's
+ * `steps.<id>.outputs.<name>` expression would. `name` is present for the
+ * members that take one (`set`, `setJson`, `exportVariable`) and absent
+ * otherwise.
+ *
+ * @public
+ */
+export declare class RecordedOutput extends RecordedOutput_base {}
+/**
+ * The member names a {@link RecordedOutput} can carry.
+ *
+ * @public
+ */
+type RecordedOutputMember = RecordedOutput["member"];
+/**
+ * What {@link ActionOutputs.recording} returns: the layer to provide and the
+ * journal it fills.
+ *
+ * @public
+ */
+interface RecordingOutputs {
+  /** An {@link ActionOutputs} whose every member records into this journal. */
+  readonly layer: Layer.Layer<ActionOutputs>;
+  /** A snapshot of every recorded call so far, in call order. */
+  readonly entries: () => ReadonlyArray<RecordedOutput>;
+}
 /**
  * The {@link ActionOutputs} service shape.
  *
@@ -674,10 +714,49 @@ export declare class ActionOutputs extends ActionOutputs_base {
    *   channel to fail through.
    */
   static readonly layerDetached: Layer.Layer<ActionOutputs>;
-  /** A test double. Unstubbed members die rather than silently succeeding. */
+  /**
+   * A test double. Unstubbed members die rather than silently succeeding.
+   *
+   * @remarks
+   * **`setJson` always encodes first.** The value is encoded through its
+   * schema exactly as the real layer does — failing typed with
+   * {@link OutputEncodeError} — and only then is a supplied `setJson`
+   * override called, with the original `(name, value, schema)`. An override
+   * that accepts `schema` and ignores it therefore **cannot disable
+   * output-schema checking**: a value/schema drift is a typed failure under
+   * this double whether or not the override looks at the schema. Without an
+   * override, a valid value still dies unimplemented as every other unstubbed
+   * member does. Most tests want neither: reach for
+   * {@link ActionOutputs.recording} instead.
+   */
   static readonly makeTest: (overrides?: Partial<ActionOutputsShape>) => ActionOutputsShape;
   /** {@link ActionOutputs.makeTest} behind `Layer.succeed`. */
   static readonly layerTest: (overrides?: Partial<ActionOutputsShape>) => Layer.Layer<ActionOutputs>;
+  /**
+   * A recording double: every member appends a {@link RecordedOutput} to a
+   * journal the test reads back, in call order.
+   *
+   * @remarks
+   * This is the double most tests of an action want — "what did it publish?"
+   * — shipped so that nobody hand-writes a `setJson` override that drops the
+   * schema encode (the trap `makeTest` now closes too). `setJson` encodes
+   * through its schema exactly as the real layer does, failing typed with
+   * {@link OutputEncodeError} and recording nothing on a drift, and records
+   * the **encoded JSON text** — what the runner would have read — not the
+   * decoded value. `set`, `exportVariable` and `setJson` refuse an unusable
+   * name with {@link InvalidOutputNameError}, as the real layer does, rather
+   * than recording it.
+   *
+   * `setSecret` records the secret's **plaintext** under
+   * `member: "setSecret"`. That is deliberate for a recording double: the
+   * journal never leaves the test, and a test asserting that a value *was*
+   * masked needs to see which one. Do not hand this journal to anything that
+   * logs.
+   *
+   * Each call returns a fresh, independent journal — there is no state shared
+   * between two `recording()` calls.
+   */
+  static readonly recording: () => RecordingOutputs;
 }
 //#endregion
 //#region src/ActionState.d.ts
@@ -4791,5 +4870,5 @@ export declare class Secret {
   static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
 }
 //#endregion
-export type { ActionCacheShape, ActionEnvironmentShape, ActionLoggerShape, ActionOutputError, ActionOutputsShape, ActionRunOptions, ActionServices, ActionStateShape, AnnotationProperties, ArtifactItem, ArtifactRef, ArtifactShape, BlobEnvelopeError, BlobStoreShape, CacheKeyError, CheckDocumentOptions, CheckDocumentShape, CheckDocumentSink, CheckFlushOutcome, CheckRunConclusion, CheckRunProjection, ClientLayerOptions, DataBlobTransfer, DetachedProcessError, DetachedProcessOps, DetachedSpawnOptions, DownloadOptions, DownloadResult, DryRunShape, ExtractOptions, FileBlobTransfer, GitHubHeadingDepth, GitHubListOptions, GitHubRowSchema, GitHubSchemaTable, GitHubSchemaTableColumn, GitHubSchemaTableColumns, GitHubSchemaTableFormatRequiredKeys, GitHubSchemaTableFormattedColumn, GitHubSchemaTableOptions, ManagedDocumentSource, OidcTokenIssuerShape, PackageManagerInstallOptions, PackageManagerInstallerShape, PairsOptions, PathPrependEnv, PathPrependOptions, ProvisionFileOptions, ProvisionOptions, ProvisionedFile, ReadOptions, ReadinessOptions, S3Config, StoredBlob, ToolDownloadOptions, ToolInstallerShape, UploadOptions, UploadResult, WithBufferOptions, WithStepOptions };
+export type { ActionCacheShape, ActionEnvironmentShape, ActionLoggerShape, ActionOutputError, ActionOutputsShape, ActionRunOptions, ActionServices, ActionStateShape, AnnotationProperties, ArtifactItem, ArtifactRef, ArtifactShape, BlobEnvelopeError, BlobStoreShape, CacheKeyError, CheckDocumentOptions, CheckDocumentShape, CheckDocumentSink, CheckFlushOutcome, CheckRunConclusion, CheckRunProjection, ClientLayerOptions, DataBlobTransfer, DetachedProcessError, DetachedProcessOps, DetachedSpawnOptions, DownloadOptions, DownloadResult, DryRunShape, ExtractOptions, FileBlobTransfer, GitHubHeadingDepth, GitHubListOptions, GitHubRowSchema, GitHubSchemaTable, GitHubSchemaTableColumn, GitHubSchemaTableColumns, GitHubSchemaTableFormatRequiredKeys, GitHubSchemaTableFormattedColumn, GitHubSchemaTableOptions, ManagedDocumentSource, OidcTokenIssuerShape, PackageManagerInstallOptions, PackageManagerInstallerShape, PairsOptions, PathPrependEnv, PathPrependOptions, ProvisionFileOptions, ProvisionOptions, ProvisionedFile, ReadOptions, ReadinessOptions, RecordedOutputMember, RecordingOutputs, S3Config, StoredBlob, ToolDownloadOptions, ToolInstallerShape, UploadOptions, UploadResult, WithBufferOptions, WithStepOptions };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -2,7 +2,7 @@ import { ActionEnvironment, ActionEnvironmentError, GitHubContext, RunnerContext
 import { ActionInput } from "./ActionInput.js";
 import { WorkflowCommand } from "./WorkflowCommand.js";
 import { ActionLogger } from "./ActionLogger.js";
-import { ActionOutputs, DetachedOutputError, InvalidOutputNameError, OutputEncodeError, RunnerFileUnavailableError, RunnerFileWriteError } from "./ActionOutputs.js";
+import { ActionOutputs, DetachedOutputError, InvalidOutputNameError, OutputEncodeError, RecordedOutput, RunnerFileUnavailableError, RunnerFileWriteError } from "./ActionOutputs.js";
 import { ActionState, ActionStateError } from "./ActionState.js";
 import { Action, ActionRuntime, describeCause } from "./Action.js";
 import { BlobTransferError } from "./BlobTransfer.js";
@@ -27,4 +27,4 @@ import { GitHubToken, GitHubTokenError } from "./GitHubToken.js";
 import { ToolInstaller, ToolInstallerError } from "./ToolInstaller.js";
 import { AmbientPackageManager, CachedPackageManager, InstalledPackageManager, PackageManagerInstaller, PackageManagerInstallerError } from "./PackageManagerInstaller.js";
 
-export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, Artifact, ArtifactError, BlobEnvelope, BlobMetadataDecodeError, BlobMetadataEncodeError, BlobStore, BlobStoreError, BlobTransferError, CacheKey, CacheKeyBadPatternError, CacheKeyReadError, CachedPackageManager, CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport, CheckState, ChildEnv, DetachedLogUnavailableError, DetachedNotReadyError, DetachedOutputError, DetachedProcess, DetachedSignalFailedError, DetachedSpawnFailedError, DryRun, GitHubCacheBlobStore, GitHubContext, GitHubMarkdown, GitHubToken, GitHubTokenError, InstalledPackageManager, InvalidOutputNameError, InvalidPidError, ManagedDocument, ManagedDocumentError, NotABlobEnvelopeError, OidcClaims, OidcTokenError, OidcTokenIssuer, OutputEncodeError, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RunnerContext, RunnerFileUnavailableError, RunnerFileWriteError, Secret, ToolInstaller, ToolInstallerError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError, WorkflowCommand, describeCause, projectCheckState };
+export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, Artifact, ArtifactError, BlobEnvelope, BlobMetadataDecodeError, BlobMetadataEncodeError, BlobStore, BlobStoreError, BlobTransferError, CacheKey, CacheKeyBadPatternError, CacheKeyReadError, CachedPackageManager, CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport, CheckState, ChildEnv, DetachedLogUnavailableError, DetachedNotReadyError, DetachedOutputError, DetachedProcess, DetachedSignalFailedError, DetachedSpawnFailedError, DryRun, GitHubCacheBlobStore, GitHubContext, GitHubMarkdown, GitHubToken, GitHubTokenError, InstalledPackageManager, InvalidOutputNameError, InvalidPidError, ManagedDocument, ManagedDocumentError, NotABlobEnvelopeError, OidcClaims, OidcTokenError, OidcTokenIssuer, OutputEncodeError, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RecordedOutput, RunnerContext, RunnerFileUnavailableError, RunnerFileWriteError, Secret, ToolInstaller, ToolInstallerError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError, WorkflowCommand, describeCause, projectCheckState };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github-actions",
-	"version": "0.12.0",
+	"version": "0.13.0",
 	"private": false,
 	"description": "The GitHub Actions runtime: env, inputs, outputs, state, logging, cache, artifacts, blob storage, OIDC and the token bridge.",
 	"keywords": [
@@ -39,11 +39,11 @@
 	},
 	"dependencies": {
 		"@azure/storage-blob": "^12.33.0",
-		"@effected/github": "^0.10.0",
+		"@effected/github": "^0.10.1",
 		"@effected/glob": "^0.6.0",
 		"@effected/markdown": "^0.10.0",
 		"@effected/npm": "^0.14.0",
-		"@effected/sbom": "^0.6.0",
+		"@effected/sbom": "^0.6.1",
 		"@effected/templates": "^0.6.0"
 	},
 	"peerDependencies": {