@effected/github-actions 0.27.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/ActionInput.js CHANGED
@@ -18,6 +18,8 @@ import { Config, ConfigProvider, Context, Effect, Schema, SchemaIssue } from "ef
18
18
  * @internal
19
19
  */
20
20
  const inputVariable = (name) => `INPUT_${name.replaceAll(" ", "_").toUpperCase()}`;
21
+ /** The prefix every runner input variable carries. */
22
+ const INPUT_PREFIX = "INPUT_";
21
23
  /**
22
24
  * A validation failure for an input that is present but unusable.
23
25
  *
@@ -428,6 +430,72 @@ var ActionInput = class ActionInput {
428
430
  return ConfigProvider.layer(ActionInput.provider(env));
429
431
  }
430
432
  /**
433
+ * {@link ActionInput.provider} over `env`, journaling every input the
434
+ * program reads.
435
+ *
436
+ * @remarks
437
+ * The test-side half of the manifest sync check: run the code under
438
+ * `layer`, read `names`, and hand them to `ActionManifest.diff` as the
439
+ * inputs the code actually reads. Values resolve exactly as under
440
+ * `ActionInput.provider(env)` — the recorder wraps that provider's lookup
441
+ * and changes nothing about what it answers — so the recording run can use
442
+ * the runner-shaped environment `ActionManifest.runnerInputs` builds.
443
+ *
444
+ * A read is journaled when its lookup runs, not when a `Config` is merely
445
+ * described, and whether or not the input has a value: an unsupplied input
446
+ * the code falls back from is still an input the code reads.
447
+ *
448
+ * What counts as an input read is a lookup of an `INPUT_` variable, which
449
+ * is what every accessor on this class performs. A **bare**
450
+ * `Config.String("dry-run")` is not journaled: from inside the provider it
451
+ * is indistinguishable from an ordinary environment read, and journaling
452
+ * every flat name would report `GITHUB_REPOSITORY` as an undeclared input.
453
+ * Reading inputs through the accessors is the rule anyway.
454
+ *
455
+ * Names come back in the runner-variable form, lowercased, so a declared
456
+ * `My Input` reads as `my_input`. `ActionManifest.diff` matches inputs by
457
+ * runner variable, under which the two are the same input.
458
+ *
459
+ * Each call journals into its own fresh set; bind the result once per test.
460
+ *
461
+ * @example
462
+ * ```ts
463
+ * import { assert, it } from "@effect/vitest";
464
+ * import { ActionInput, ActionManifest } from "@effected/github-actions";
465
+ * import { Effect } from "effect";
466
+ *
467
+ * declare const manifest: ActionManifest;
468
+ * declare const readInputs: Effect.Effect<unknown, unknown>;
469
+ *
470
+ * it.effect("the code reads exactly what action.yml declares", () =>
471
+ * Effect.gen(function* () {
472
+ * const recording = ActionInput.recording(ActionManifest.runnerInputs(manifest));
473
+ * yield* readInputs.pipe(Effect.provide(recording.layer));
474
+ * const diff = ActionManifest.diff(manifest, { inputs: yield* recording.names });
475
+ * assert.isTrue(diff.inSync, JSON.stringify(diff));
476
+ * }),
477
+ * );
478
+ * ```
479
+ *
480
+ * @param env - The environment the provider serves, as for
481
+ * {@link ActionInput.provider}. Defaults to an empty record, never
482
+ * `process.env`: a recorder is a test instrument.
483
+ */
484
+ static recording(env = {}) {
485
+ const inner = ActionInput.provider(env);
486
+ const seen = /* @__PURE__ */ new Set();
487
+ const provider = ConfigProvider.make((path) => Effect.suspend(() => {
488
+ const variable = path.join("_").replaceAll(" ", "_").toUpperCase();
489
+ if (variable.startsWith(INPUT_PREFIX) && variable.length > 6) seen.add(variable.slice(6).toLowerCase());
490
+ return inner.load(path);
491
+ }));
492
+ return {
493
+ provider,
494
+ layer: ConfigProvider.layer(provider),
495
+ names: Effect.sync(() => [...seen])
496
+ };
497
+ }
498
+ /**
431
499
  * Inputs-first resolution layered over an existing provider.
432
500
  *
433
501
  * @remarks
@@ -0,0 +1,450 @@
1
+ import { inputVariable } from "./ActionInput.js";
2
+ import { Effect, FileSystem, Result, Schema, SchemaTransformation } from "effect";
3
+ import { Yaml } from "@effected/yaml";
4
+
5
+ // src/ActionManifest.ts
6
+ /**
7
+ * A resolved YAML scalar as text: `null` (a bare `key:`, `~`) is `""`, a
8
+ * non-finite number takes YAML's own spelling, and anything else is
9
+ * `String(value)`.
10
+ */
11
+ const scalarText = (value) => {
12
+ if (value === null) return "";
13
+ if (typeof value === "number" && !Number.isFinite(value)) return Number.isNaN(value) ? ".nan" : value > 0 ? ".inf" : "-.inf";
14
+ return String(value);
15
+ };
16
+ /**
17
+ * A YAML scalar read as the text the runner publishes.
18
+ *
19
+ * @remarks
20
+ * YAML types an unquoted `default: false` as a boolean, `default: 3` as a
21
+ * number and a bare `default:` as null, but the runner hands every value to
22
+ * the action as text. Accepting every scalar and stringifying keeps a
23
+ * manifest author's quoting choice from changing what a test believes the
24
+ * runner sends, and keeps a manifest that published actions really carry
25
+ * from failing to decode.
26
+ *
27
+ * A bare value or `~` reads as `""`, which is what the runner publishes for
28
+ * it. `.inf`, `-.inf` and `.nan` read as those spellings. Any other number is
29
+ * stringified by JavaScript (`String(value)`), so one whose YAML spelling is
30
+ * not its canonical form (`1.0`, `0x10`, `.Inf`) reads as `"1"`, `"16"` or
31
+ * `".inf"` here — quote such a value in `action.yml` to pin its exact text.
32
+ */
33
+ const ScalarText = Schema.Union([
34
+ Schema.String,
35
+ Schema.Number,
36
+ Schema.BigInt,
37
+ Schema.Boolean,
38
+ Schema.Null
39
+ ]).pipe(Schema.decodeTo(Schema.String, SchemaTransformation.transform({
40
+ decode: scalarText,
41
+ encode: (text) => text
42
+ })));
43
+ /**
44
+ * A YAML boolean, or the strings `"true"` and `"false"`, which published
45
+ * manifests quote as often as not.
46
+ */
47
+ const LenientBoolean = Schema.Union([Schema.Boolean, Schema.Literals(["true", "false"])]).pipe(Schema.decodeTo(Schema.Boolean, SchemaTransformation.transform({
48
+ decode: (value) => value === true || value === "true",
49
+ encode: (value) => value
50
+ })));
51
+ /**
52
+ * One input an `action.yml` declares under `inputs:`.
53
+ *
54
+ * @remarks
55
+ * `default` is the text the runner publishes when a workflow omits the input;
56
+ * when the manifest declares none, the runner publishes `""` instead — see
57
+ * {@link ActionManifest.runnerInputs}. A `default` written as a workflow
58
+ * expression (`${{ github.token }}`) is evaluated by the runner, so here it is
59
+ * the unevaluated text: supply the evaluated value explicitly in a test.
60
+ *
61
+ * `required` is documentation only — the runner does not enforce it — and
62
+ * `description` is optional here because the runner does not require it
63
+ * either, even though the metadata reference lists it.
64
+ *
65
+ * @public
66
+ */
67
+ var ActionManifestInput = class extends Schema.Class("ActionManifestInput")({
68
+ /** What the input is for. */
69
+ description: Schema.optionalKey(Schema.String),
70
+ /**
71
+ * Whether the manifest marks the input required (not enforced by the
72
+ * runner); the quoted strings `"true"` and `"false"` decode as booleans.
73
+ */
74
+ required: Schema.optionalKey(LenientBoolean),
75
+ /**
76
+ * The text published when a workflow omits the input, stringified from any
77
+ * YAML scalar; a bare `default:` reads as `""`.
78
+ */
79
+ default: Schema.optionalKey(ScalarText),
80
+ /** Set when the input is deprecated; the runner warns with this text when a workflow supplies it. */
81
+ deprecationMessage: Schema.optionalKey(Schema.String)
82
+ }) {};
83
+ /**
84
+ * One output an `action.yml` declares under `outputs:`.
85
+ *
86
+ * @remarks
87
+ * `value` is the expression a composite action maps the output from; a
88
+ * JavaScript or Docker action writes its outputs at runtime and declares none.
89
+ *
90
+ * @public
91
+ */
92
+ var ActionManifestOutput = class extends Schema.Class("ActionManifestOutput")({
93
+ /** What the output carries. */
94
+ description: Schema.optionalKey(Schema.String),
95
+ /** The expression a composite action maps the output from. */
96
+ value: Schema.optionalKey(Schema.String)
97
+ }) {};
98
+ /**
99
+ * The `runs:` block of a JavaScript action — `using: node24` and its kin.
100
+ *
101
+ * @remarks
102
+ * `using` is any `node<major>` string rather than a closed list, so a manifest
103
+ * written for a runtime newer than this package still decodes. The YAML keys
104
+ * `pre-if` and `post-if` decode to `preIf` and `postIf`.
105
+ *
106
+ * @public
107
+ */
108
+ var ActionManifestNodeRuns = class extends Schema.Class("ActionManifestNodeRuns")({
109
+ /** The Node runtime, such as `node24`. */
110
+ using: Schema.String.check(Schema.isPattern(/^node\d+$/)),
111
+ /** The entry point the `main` phase runs. */
112
+ main: Schema.String,
113
+ /** The entry point the `pre` phase runs, before any step of the job. */
114
+ pre: Schema.optionalKey(Schema.String),
115
+ /** The entry point the `post` phase runs, after every step of the job. */
116
+ post: Schema.optionalKey(Schema.String),
117
+ /** The condition gating the `pre` phase (`pre-if` in YAML). */
118
+ preIf: Schema.optionalKey(Schema.String),
119
+ /** The condition gating the `post` phase (`post-if` in YAML). */
120
+ postIf: Schema.optionalKey(Schema.String)
121
+ }) {};
122
+ /**
123
+ * The `runs:` block of a composite action.
124
+ *
125
+ * @remarks
126
+ * `steps` stays loosely typed — each step is a mapping — because describing
127
+ * the workflow-step grammar is out of this construct's scope.
128
+ *
129
+ * @public
130
+ */
131
+ var ActionManifestCompositeRuns = class extends Schema.Class("ActionManifestCompositeRuns")({
132
+ /** Always `composite`. */
133
+ using: Schema.Literal("composite"),
134
+ /** The steps the action runs, each an unvalidated mapping. */
135
+ steps: Schema.Array(Schema.Record(Schema.String, Schema.Unknown))
136
+ }) {};
137
+ /**
138
+ * The `runs:` block of a Docker container action.
139
+ *
140
+ * @remarks
141
+ * The YAML keys `pre-entrypoint`, `post-entrypoint`, `pre-if` and `post-if`
142
+ * decode to camelCase. `args` entries and `env` values are stringified from
143
+ * any YAML scalar, as the runner passes them to the container as text.
144
+ *
145
+ * @public
146
+ */
147
+ var ActionManifestDockerRuns = class extends Schema.Class("ActionManifestDockerRuns")({
148
+ /** Always `docker`. */
149
+ using: Schema.Literal("docker"),
150
+ /** A `Dockerfile` path or a `docker://` image reference. */
151
+ image: Schema.String,
152
+ /** Arguments passed to the container, each stringified from any YAML scalar. */
153
+ args: Schema.optionalKey(Schema.Array(ScalarText)),
154
+ /** Environment variables set in the container. */
155
+ env: Schema.optionalKey(Schema.Record(Schema.String, ScalarText)),
156
+ /** Overrides the image's `ENTRYPOINT`. */
157
+ entrypoint: Schema.optionalKey(Schema.String),
158
+ /** The entry point run before the `main` phase (`pre-entrypoint` in YAML). */
159
+ preEntrypoint: Schema.optionalKey(Schema.String),
160
+ /** The entry point run after the job's steps (`post-entrypoint` in YAML). */
161
+ postEntrypoint: Schema.optionalKey(Schema.String),
162
+ /** The condition gating the `pre` phase (`pre-if` in YAML). */
163
+ preIf: Schema.optionalKey(Schema.String),
164
+ /** The condition gating the `post` phase (`post-if` in YAML). */
165
+ postIf: Schema.optionalKey(Schema.String)
166
+ }) {};
167
+ /** The `runs:` union, with each shape's hyphenated YAML keys renamed. */
168
+ const Runs = Schema.Union([
169
+ ActionManifestNodeRuns.pipe(Schema.encodeKeys({
170
+ preIf: "pre-if",
171
+ postIf: "post-if"
172
+ })),
173
+ ActionManifestCompositeRuns,
174
+ ActionManifestDockerRuns.pipe(Schema.encodeKeys({
175
+ preEntrypoint: "pre-entrypoint",
176
+ postEntrypoint: "post-entrypoint",
177
+ preIf: "pre-if",
178
+ postIf: "post-if"
179
+ }))
180
+ ]);
181
+ /**
182
+ * The `branding:` block a Marketplace listing reads.
183
+ *
184
+ * @public
185
+ */
186
+ var ActionManifestBranding = class extends Schema.Class("ActionManifestBranding")({
187
+ /** A Feather icon name. */
188
+ icon: Schema.optionalKey(Schema.String),
189
+ /** The badge background colour. */
190
+ color: Schema.optionalKey(Schema.String)
191
+ }) {};
192
+ /**
193
+ * Raised when an `action.yml` cannot be read from the filesystem.
194
+ *
195
+ * @public
196
+ */
197
+ var ActionManifestReadError = class extends Schema.TaggedError()("ActionManifestReadError", {
198
+ /** The path that was being read. */
199
+ path: Schema.String,
200
+ /** The underlying failure, preserved structurally. */
201
+ cause: Schema.Defect()
202
+ }) {
203
+ get message() {
204
+ return `Could not read the action manifest at "${this.path}"`;
205
+ }
206
+ };
207
+ /**
208
+ * Raised when an `action.yml` is not valid YAML, or is YAML that does not
209
+ * have the shape of an action manifest.
210
+ *
211
+ * @remarks
212
+ * One class for both, because the two share every field and no caller
213
+ * recovers from one but not the other: either way the manifest is broken.
214
+ * `detail` is the rendered parse or schema failure and `cause` the structured
215
+ * original.
216
+ *
217
+ * @public
218
+ */
219
+ var ActionManifestDecodeError = class extends Schema.TaggedError()("ActionManifestDecodeError", {
220
+ /** The rendered parse or schema failure. */
221
+ detail: Schema.String,
222
+ /** The `YamlParseError` or `SchemaError` behind it. */
223
+ cause: Schema.Defect()
224
+ }) {
225
+ get message() {
226
+ return `Not a valid action manifest: ${this.detail}`;
227
+ }
228
+ };
229
+ /**
230
+ * Where an action's code and its `action.yml` disagree.
231
+ *
232
+ * @remarks
233
+ * Every list is in declaration or usage order, with duplicates removed. An
234
+ * empty diff — {@link ActionManifestDiff.inSync} — means the code reads every
235
+ * declared input, declares every input it reads, and the same for outputs.
236
+ *
237
+ * @public
238
+ */
239
+ var ActionManifestDiff = class extends Schema.Class("ActionManifestDiff")({
240
+ /** Declared in `action.yml`, never read by the code. */
241
+ unreadInputs: Schema.Array(Schema.String),
242
+ /** Read by the code, not declared in `action.yml` — on a runner it arrives absent. */
243
+ undeclaredInputs: Schema.Array(Schema.String),
244
+ /** Declared in `action.yml`, never written by the code. */
245
+ unwrittenOutputs: Schema.Array(Schema.String),
246
+ /** Written by the code, not declared in `action.yml`. */
247
+ undeclaredOutputs: Schema.Array(Schema.String)
248
+ }) {
249
+ /** True when the code and the manifest agree on every name. */
250
+ get inSync() {
251
+ return this.unreadInputs.length === 0 && this.undeclaredInputs.length === 0 && this.unwrittenOutputs.length === 0 && this.undeclaredOutputs.length === 0;
252
+ }
253
+ };
254
+ /** The names in `names` whose key is absent from `keys`, deduplicated, in order. */
255
+ const missingFrom = (names, keys, key) => {
256
+ const seen = /* @__PURE__ */ new Set();
257
+ const missing = [];
258
+ for (const name of names) {
259
+ const k = key(name);
260
+ if (!seen.has(k) && !keys.has(k)) missing.push(name);
261
+ seen.add(k);
262
+ }
263
+ return missing;
264
+ };
265
+ /** The identity key, for outputs. */
266
+ const verbatim = (name) => name;
267
+ /**
268
+ * A decoded `action.yml`: the action's metadata, its declared inputs and
269
+ * outputs, and the `runs:` block naming how it executes.
270
+ *
271
+ * @remarks
272
+ * `action.yml` is the single source of truth for an action's input names and
273
+ * defaults, and the code mirrors both. This construct makes the mirror
274
+ * testable: {@link ActionManifest.runnerInputs} builds the input environment a
275
+ * real runner builds from the manifest, and {@link ActionManifest.diff} reports
276
+ * where the code's reads and writes disagree with what the manifest declares.
277
+ *
278
+ * `inputs` and `outputs` are keyed by name, in declaration order. Keys this
279
+ * construct does not describe are ignored, so a manifest carrying a newer
280
+ * metadata key still decodes.
281
+ *
282
+ * @example
283
+ * ```ts
284
+ * import { ActionInput, ActionManifest } from "@effected/github-actions";
285
+ * import { Effect } from "effect";
286
+ *
287
+ * const program = Effect.gen(function* () {
288
+ * const manifest = yield* ActionManifest.read("action.yml");
289
+ * // Every declared input present, with its manifest default or "".
290
+ * const layer = ActionInput.layer(ActionManifest.runnerInputs(manifest, { "dry-run": "true" }));
291
+ * return layer;
292
+ * });
293
+ * ```
294
+ *
295
+ * @public
296
+ */
297
+ var ActionManifest = class ActionManifest extends Schema.Class("ActionManifest")({
298
+ /** The action's display name. */
299
+ name: Schema.String,
300
+ /** What the action does. */
301
+ description: Schema.optionalKey(Schema.String),
302
+ /** Who wrote the action. */
303
+ author: Schema.optionalKey(Schema.String),
304
+ /** The declared inputs, keyed by name. */
305
+ inputs: Schema.optionalKey(Schema.Record(Schema.String, ActionManifestInput)),
306
+ /** The declared outputs, keyed by name. */
307
+ outputs: Schema.optionalKey(Schema.Record(Schema.String, ActionManifestOutput)),
308
+ /** How the action executes. */
309
+ runs: Runs,
310
+ /** The Marketplace badge. */
311
+ branding: Schema.optionalKey(ActionManifestBranding)
312
+ }) {
313
+ /**
314
+ * Decode `action.yml` text, synchronously.
315
+ *
316
+ * @remarks
317
+ * Fails with {@link ActionManifestDecodeError} when the text is not YAML or
318
+ * not an action manifest. This is the form for a test that wants the
319
+ * manifest without an effect; {@link ActionManifest.decode} is the same
320
+ * decode as an `Effect`.
321
+ */
322
+ static decodeResult(source) {
323
+ return Result.flatMap(Result.mapError(Yaml.parseResult(source), (cause) => new ActionManifestDecodeError({
324
+ detail: cause.message,
325
+ cause
326
+ })), (value) => Result.mapError(decodeManifest(value), (cause) => new ActionManifestDecodeError({
327
+ detail: cause.message,
328
+ cause
329
+ })));
330
+ }
331
+ /**
332
+ * Decode `action.yml` text.
333
+ *
334
+ * @remarks
335
+ * Fails with {@link ActionManifestDecodeError} when the text is not YAML or
336
+ * not an action manifest.
337
+ */
338
+ static decode = (source) => Effect.fromResult(ActionManifest.decodeResult(source));
339
+ /**
340
+ * Read and decode the `action.yml` at `path`.
341
+ *
342
+ * @remarks
343
+ * Reads through `FileSystem` in `R`, so a test provides `@effected/memfs`
344
+ * and production the platform filesystem. A read failure is
345
+ * {@link ActionManifestReadError}, carrying the path; a malformed manifest is
346
+ * {@link ActionManifestDecodeError}.
347
+ */
348
+ static read = Effect.fn("ActionManifest.read")(function* (path) {
349
+ const source = yield* (yield* FileSystem.FileSystem).readFileString(path).pipe(Effect.mapError((cause) => new ActionManifestReadError({
350
+ path,
351
+ cause
352
+ })));
353
+ return yield* ActionManifest.decode(source);
354
+ });
355
+ /**
356
+ * The input environment a real runner builds for this manifest.
357
+ *
358
+ * @remarks
359
+ * The runner publishes a variable for **every** declared input: the value
360
+ * the workflow supplied under `with:`, else the manifest `default`, else
361
+ * `""`. So "absent" is a state production never produces, and a test built
362
+ * on an empty `ActionInput.layer({})` exercises the code's
363
+ * `Config.withDefault` fallbacks rather than the manifest defaults a real
364
+ * run decodes. This record is the runner-shaped baseline instead.
365
+ *
366
+ * Keys are runner variables — `INPUT_` plus the name uppercased with spaces
367
+ * turned to underscores and every other character, dashes included, kept
368
+ * (`write-summary` → `INPUT_WRITE-SUMMARY`) — derived through
369
+ * `ActionInput.variable`, the same function every accessor reads through.
370
+ * So the record feeds `ActionInput.layer`, spreads into
371
+ * `ActionEnvironment.layerTest`'s overrides, or becomes a spawned
372
+ * process's environment unchanged.
373
+ *
374
+ * `supplied` is the workflow's `with:` block, keyed by input name, and is
375
+ * matched to the declared inputs **by runner variable**, the way
376
+ * {@link ActionManifest.diff} matches: `write summary`, `write_summary` and
377
+ * `WRITE_SUMMARY` all supply the input declared as `write_summary`. A
378
+ * supplied value wins even when it is `""`, as on a runner.
379
+ *
380
+ * A supplied name the manifest does not declare is **passed through** as
381
+ * one more `INPUT_` variable, because the runner publishes it too — it only
382
+ * warns. This never throws. To catch a typo in a test, compare the names
383
+ * with {@link ActionManifest.diff}, which reports an undeclared read; a
384
+ * typoed supplied name otherwise leaves the declared input on its default.
385
+ *
386
+ * **Composite actions receive no `INPUT_` environment.** The runner
387
+ * publishes these variables to node and docker actions only; a composite
388
+ * action reads its inputs through `inputs.<name>` expressions in its steps.
389
+ * This builder is for node and docker actions, and for a composite test
390
+ * that drives the inputs into its steps explicitly.
391
+ *
392
+ * @param manifest - The decoded manifest.
393
+ * @param supplied - The workflow's `with:` values, keyed by input name.
394
+ * @returns The runner's `INPUT_*` variables: one per declared input, then
395
+ * one per supplied name the manifest does not declare.
396
+ */
397
+ static runnerInputs(manifest, supplied = {}) {
398
+ const byVariable = /* @__PURE__ */ new Map();
399
+ for (const [name, value] of Object.entries(supplied)) byVariable.set(inputVariable(name), value);
400
+ const env = {};
401
+ for (const [name, input] of Object.entries(manifest.inputs ?? {})) {
402
+ const variable = inputVariable(name);
403
+ env[variable] = byVariable.get(variable) ?? input.default ?? "";
404
+ byVariable.delete(variable);
405
+ }
406
+ for (const [variable, value] of byVariable) env[variable] = value;
407
+ return env;
408
+ }
409
+ /**
410
+ * Compare the names an action's code reads and writes against the names
411
+ * its manifest declares.
412
+ *
413
+ * @remarks
414
+ * Inputs are matched the way the runner connects them — by runner
415
+ * variable — so `write summary` in code and `write_summary` in the
416
+ * manifest are the same input, and so are names differing only in case.
417
+ * Outputs are matched verbatim. Omitting `usage.outputs` skips the output
418
+ * comparison, leaving both output lists empty; omitting `usage.inputs`
419
+ * compares against no reads, so every declared input reports unread.
420
+ *
421
+ * @example
422
+ * ```ts
423
+ * import { assert, it } from "@effect/vitest";
424
+ * import { ActionManifest } from "@effected/github-actions";
425
+ *
426
+ * declare const manifest: ActionManifest;
427
+ *
428
+ * it("action.yml and the code agree", () => {
429
+ * const diff = ActionManifest.diff(manifest, { inputs: ["name", "dry-run"], outputs: ["greeting"] });
430
+ * assert.isTrue(diff.inSync, JSON.stringify(diff));
431
+ * });
432
+ * ```
433
+ */
434
+ static diff(manifest, usage) {
435
+ const declaredInputs = Object.keys(manifest.inputs ?? {});
436
+ const readInputs = [...usage.inputs ?? []];
437
+ const declaredOutputs = usage.outputs !== void 0 ? Object.keys(manifest.outputs ?? {}) : [];
438
+ const writtenOutputs = [...usage.outputs ?? []];
439
+ return new ActionManifestDiff({
440
+ unreadInputs: missingFrom(declaredInputs, new Set(readInputs.map(inputVariable)), inputVariable),
441
+ undeclaredInputs: missingFrom(readInputs, new Set(declaredInputs.map(inputVariable)), inputVariable),
442
+ unwrittenOutputs: missingFrom(declaredOutputs, new Set(writtenOutputs), verbatim),
443
+ undeclaredOutputs: missingFrom(writtenOutputs, new Set(declaredOutputs), verbatim)
444
+ });
445
+ }
446
+ };
447
+ /** The manifest decoder, derived once. */
448
+ const decodeManifest = Schema.decodeUnknownResult(ActionManifest);
449
+
450
+ export { ActionManifest, ActionManifestBranding, ActionManifestCompositeRuns, ActionManifestDecodeError, ActionManifestDiff, ActionManifestDockerRuns, ActionManifestInput, ActionManifestNodeRuns, ActionManifestOutput, ActionManifestReadError };
package/README.md CHANGED
@@ -293,7 +293,8 @@ const TestOutputs = ActionOutputs.layerTest({
293
293
  ## Features
294
294
 
295
295
  - `Action.run` / `ActionRuntime.layer` — the entry point and default runtime: environment, logger, outputs, state, the Node platform and an `HttpClient`.
296
- - `ActionInput` — typed input accessors (`string`, `boolean`, `integer`, `redacted`, `lines`, `list`, `pairs`, `schema`) sharing one absence rule, plus the `INPUT_`-aware `ConfigProvider` `Action.run` installs by default. `pairs` always rejects an empty key (`=value`, whose damage lands far from the typo) and takes `requireValue` to reject an empty value too.
296
+ - `ActionInput` — typed input accessors (`string`, `boolean`, `integer`, `redacted`, `lines`, `list`, `pairs`, `schema`) sharing one absence rule, plus the `INPUT_`-aware `ConfigProvider` `Action.run` installs by default. `pairs` always rejects an empty key (`=value`, whose damage lands far from the typo) and takes `requireValue` to reject an empty value too. `ActionInput.recording(env)` journals which inputs a program reads, for `ActionManifest.diff`.
297
+ - `ActionManifest` — `action.yml` decoded (`read`, `decode`, `decodeResult`): inputs with defaults, outputs, branding and the node, composite or docker `runs` block. `runnerInputs` builds the input environment a real runner builds for a node or docker action (every declared input under its `INPUT_` variable, with the supplied value, its manifest default or `""`, plus any undeclared supplied name passed through as the runner does) as the baseline for input tests, and `diff` reports inputs and outputs the code and the manifest disagree on.
297
298
  - `ActionOutputs` — step outputs, JSON outputs, the job summary, exported variables, `PATH` additions, failure annotations and log masking.
298
299
  - `ActionState` / `ActionEnvironment` — persisted `pre`/`main`/`post` state, and the fiber-local `GITHUB_*`/`RUNNER_*` context read once from `process.env`.
299
300
  - `ActionLogger` — collapsible groups (nesting-aware: the runner cannot nest groups, so a group opened inside another writes a `▸ <name>` header line instead of a second group command), buffered step transcripts (`withBuffer({ onSuccess: "discard" })` drops a green step's transcript entirely, while a failure, defect or interruption still flushes it), `withStep(name, effect, options?)` for the same buffering plus one summary line on success and a `❌ <name>` header above the transcript on failure, `::notice::` annotations, and the `Logger` that renders every `Effect.log*` as a workflow command.
package/index.d.ts CHANGED
@@ -1593,6 +1593,24 @@ export declare class ActionCache extends ActionCache_base {
1593
1593
  /** {@link ActionCache.makeTest} behind `Layer.succeed`. */
1594
1594
  static readonly layerTest: (overrides?: Partial<ActionCacheShape>) => Layer.Layer<ActionCache>;
1595
1595
  }
1596
+ /**
1597
+ * A provider that journals which inputs a program reads — see
1598
+ * {@link ActionInput.recording}.
1599
+ *
1600
+ * @public
1601
+ */
1602
+ interface ActionInputRecording {
1603
+ /** The recording provider, for composing by hand. */
1604
+ readonly provider: ConfigProvider.ConfigProvider;
1605
+ /** {@link ActionInputRecording.provider} installed as a layer. */
1606
+ readonly layer: Layer.Layer<never>;
1607
+ /**
1608
+ * The input names read so far, in first-read order, without duplicates —
1609
+ * each the runner variable with its `INPUT_` prefix dropped and lowercased
1610
+ * (`INPUT_WRITE-SUMMARY` reads as `write-summary`).
1611
+ */
1612
+ readonly names: Effect.Effect<ReadonlyArray<string>>;
1613
+ }
1596
1614
  /**
1597
1615
  * Options for {@link ActionInput.pairs}.
1598
1616
  *
@@ -1909,6 +1927,59 @@ export declare class ActionInput {
1909
1927
  * a `const` rather than calling it at each composition site.
1910
1928
  */
1911
1929
  static layer(env?: Readonly<Record<string, string | undefined>>): Layer.Layer<never>;
1930
+ /**
1931
+ * {@link ActionInput.provider} over `env`, journaling every input the
1932
+ * program reads.
1933
+ *
1934
+ * @remarks
1935
+ * The test-side half of the manifest sync check: run the code under
1936
+ * `layer`, read `names`, and hand them to `ActionManifest.diff` as the
1937
+ * inputs the code actually reads. Values resolve exactly as under
1938
+ * `ActionInput.provider(env)` — the recorder wraps that provider's lookup
1939
+ * and changes nothing about what it answers — so the recording run can use
1940
+ * the runner-shaped environment `ActionManifest.runnerInputs` builds.
1941
+ *
1942
+ * A read is journaled when its lookup runs, not when a `Config` is merely
1943
+ * described, and whether or not the input has a value: an unsupplied input
1944
+ * the code falls back from is still an input the code reads.
1945
+ *
1946
+ * What counts as an input read is a lookup of an `INPUT_` variable, which
1947
+ * is what every accessor on this class performs. A **bare**
1948
+ * `Config.String("dry-run")` is not journaled: from inside the provider it
1949
+ * is indistinguishable from an ordinary environment read, and journaling
1950
+ * every flat name would report `GITHUB_REPOSITORY` as an undeclared input.
1951
+ * Reading inputs through the accessors is the rule anyway.
1952
+ *
1953
+ * Names come back in the runner-variable form, lowercased, so a declared
1954
+ * `My Input` reads as `my_input`. `ActionManifest.diff` matches inputs by
1955
+ * runner variable, under which the two are the same input.
1956
+ *
1957
+ * Each call journals into its own fresh set; bind the result once per test.
1958
+ *
1959
+ * @example
1960
+ * ```ts
1961
+ * import { assert, it } from "@effect/vitest";
1962
+ * import { ActionInput, ActionManifest } from "@effected/github-actions";
1963
+ * import { Effect } from "effect";
1964
+ *
1965
+ * declare const manifest: ActionManifest;
1966
+ * declare const readInputs: Effect.Effect<unknown, unknown>;
1967
+ *
1968
+ * it.effect("the code reads exactly what action.yml declares", () =>
1969
+ * Effect.gen(function* () {
1970
+ * const recording = ActionInput.recording(ActionManifest.runnerInputs(manifest));
1971
+ * yield* readInputs.pipe(Effect.provide(recording.layer));
1972
+ * const diff = ActionManifest.diff(manifest, { inputs: yield* recording.names });
1973
+ * assert.isTrue(diff.inSync, JSON.stringify(diff));
1974
+ * }),
1975
+ * );
1976
+ * ```
1977
+ *
1978
+ * @param env - The environment the provider serves, as for
1979
+ * {@link ActionInput.provider}. Defaults to an empty record, never
1980
+ * `process.env`: a recorder is a test instrument.
1981
+ */
1982
+ static recording(env?: Readonly<Record<string, string | undefined>>): ActionInputRecording;
1912
1983
  /**
1913
1984
  * Inputs-first resolution layered over an existing provider.
1914
1985
  *
@@ -1985,6 +2056,374 @@ export declare class ActionInput {
1985
2056
  */
1986
2057
  static readonly layerDefault: Layer.Layer<never>;
1987
2058
  }
2059
+ declare const ActionManifestInput_base: Schema.Class<ActionManifestInput, Schema.Struct<{
2060
+ /** What the input is for. */
2061
+ readonly description: Schema.optionalKey<Schema.String>;
2062
+ /**
2063
+ * Whether the manifest marks the input required (not enforced by the
2064
+ * runner); the quoted strings `"true"` and `"false"` decode as booleans.
2065
+ */
2066
+ readonly required: Schema.optionalKey<Schema.decodeTo<Schema.Boolean, Schema.Union<readonly [Schema.Boolean, Schema.Literals<readonly ["true", "false"]>]>, never, never>>;
2067
+ /**
2068
+ * The text published when a workflow omits the input, stringified from any
2069
+ * YAML scalar; a bare `default:` reads as `""`.
2070
+ */
2071
+ readonly default: Schema.optionalKey<Schema.decodeTo<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.BigInt, Schema.Boolean, Schema.Null]>, never, never>>;
2072
+ /** Set when the input is deprecated; the runner warns with this text when a workflow supplies it. */
2073
+ readonly deprecationMessage: Schema.optionalKey<Schema.String>;
2074
+ }>, {}>;
2075
+ /**
2076
+ * One input an `action.yml` declares under `inputs:`.
2077
+ *
2078
+ * @remarks
2079
+ * `default` is the text the runner publishes when a workflow omits the input;
2080
+ * when the manifest declares none, the runner publishes `""` instead — see
2081
+ * {@link ActionManifest.runnerInputs}. A `default` written as a workflow
2082
+ * expression (`${{ github.token }}`) is evaluated by the runner, so here it is
2083
+ * the unevaluated text: supply the evaluated value explicitly in a test.
2084
+ *
2085
+ * `required` is documentation only — the runner does not enforce it — and
2086
+ * `description` is optional here because the runner does not require it
2087
+ * either, even though the metadata reference lists it.
2088
+ *
2089
+ * @public
2090
+ */
2091
+ export declare class ActionManifestInput extends ActionManifestInput_base {}
2092
+ declare const ActionManifestOutput_base: Schema.Class<ActionManifestOutput, Schema.Struct<{
2093
+ /** What the output carries. */
2094
+ readonly description: Schema.optionalKey<Schema.String>;
2095
+ /** The expression a composite action maps the output from. */
2096
+ readonly value: Schema.optionalKey<Schema.String>;
2097
+ }>, {}>;
2098
+ /**
2099
+ * One output an `action.yml` declares under `outputs:`.
2100
+ *
2101
+ * @remarks
2102
+ * `value` is the expression a composite action maps the output from; a
2103
+ * JavaScript or Docker action writes its outputs at runtime and declares none.
2104
+ *
2105
+ * @public
2106
+ */
2107
+ export declare class ActionManifestOutput extends ActionManifestOutput_base {}
2108
+ declare const ActionManifestNodeRuns_base: Schema.Class<ActionManifestNodeRuns, Schema.Struct<{
2109
+ /** The Node runtime, such as `node24`. */
2110
+ readonly using: Schema.String;
2111
+ /** The entry point the `main` phase runs. */
2112
+ readonly main: Schema.String;
2113
+ /** The entry point the `pre` phase runs, before any step of the job. */
2114
+ readonly pre: Schema.optionalKey<Schema.String>;
2115
+ /** The entry point the `post` phase runs, after every step of the job. */
2116
+ readonly post: Schema.optionalKey<Schema.String>;
2117
+ /** The condition gating the `pre` phase (`pre-if` in YAML). */
2118
+ readonly preIf: Schema.optionalKey<Schema.String>;
2119
+ /** The condition gating the `post` phase (`post-if` in YAML). */
2120
+ readonly postIf: Schema.optionalKey<Schema.String>;
2121
+ }>, {}>;
2122
+ /**
2123
+ * The `runs:` block of a JavaScript action — `using: node24` and its kin.
2124
+ *
2125
+ * @remarks
2126
+ * `using` is any `node<major>` string rather than a closed list, so a manifest
2127
+ * written for a runtime newer than this package still decodes. The YAML keys
2128
+ * `pre-if` and `post-if` decode to `preIf` and `postIf`.
2129
+ *
2130
+ * @public
2131
+ */
2132
+ export declare class ActionManifestNodeRuns extends ActionManifestNodeRuns_base {}
2133
+ declare const ActionManifestCompositeRuns_base: Schema.Class<ActionManifestCompositeRuns, Schema.Struct<{
2134
+ /** Always `composite`. */
2135
+ readonly using: Schema.Literal<"composite">;
2136
+ /** The steps the action runs, each an unvalidated mapping. */
2137
+ readonly steps: Schema.$Array<Schema.$Record<Schema.String, Schema.Unknown>>;
2138
+ }>, {}>;
2139
+ /**
2140
+ * The `runs:` block of a composite action.
2141
+ *
2142
+ * @remarks
2143
+ * `steps` stays loosely typed — each step is a mapping — because describing
2144
+ * the workflow-step grammar is out of this construct's scope.
2145
+ *
2146
+ * @public
2147
+ */
2148
+ export declare class ActionManifestCompositeRuns extends ActionManifestCompositeRuns_base {}
2149
+ declare const ActionManifestDockerRuns_base: Schema.Class<ActionManifestDockerRuns, Schema.Struct<{
2150
+ /** Always `docker`. */
2151
+ readonly using: Schema.Literal<"docker">;
2152
+ /** A `Dockerfile` path or a `docker://` image reference. */
2153
+ readonly image: Schema.String;
2154
+ /** Arguments passed to the container, each stringified from any YAML scalar. */
2155
+ readonly args: Schema.optionalKey<Schema.$Array<Schema.decodeTo<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.BigInt, Schema.Boolean, Schema.Null]>, never, never>>>;
2156
+ /** Environment variables set in the container. */
2157
+ readonly env: Schema.optionalKey<Schema.$Record<Schema.String, Schema.decodeTo<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.BigInt, Schema.Boolean, Schema.Null]>, never, never>>>;
2158
+ /** Overrides the image's `ENTRYPOINT`. */
2159
+ readonly entrypoint: Schema.optionalKey<Schema.String>;
2160
+ /** The entry point run before the `main` phase (`pre-entrypoint` in YAML). */
2161
+ readonly preEntrypoint: Schema.optionalKey<Schema.String>;
2162
+ /** The entry point run after the job's steps (`post-entrypoint` in YAML). */
2163
+ readonly postEntrypoint: Schema.optionalKey<Schema.String>;
2164
+ /** The condition gating the `pre` phase (`pre-if` in YAML). */
2165
+ readonly preIf: Schema.optionalKey<Schema.String>;
2166
+ /** The condition gating the `post` phase (`post-if` in YAML). */
2167
+ readonly postIf: Schema.optionalKey<Schema.String>;
2168
+ }>, {}>;
2169
+ /**
2170
+ * The `runs:` block of a Docker container action.
2171
+ *
2172
+ * @remarks
2173
+ * The YAML keys `pre-entrypoint`, `post-entrypoint`, `pre-if` and `post-if`
2174
+ * decode to camelCase. `args` entries and `env` values are stringified from
2175
+ * any YAML scalar, as the runner passes them to the container as text.
2176
+ *
2177
+ * @public
2178
+ */
2179
+ export declare class ActionManifestDockerRuns extends ActionManifestDockerRuns_base {}
2180
+ /**
2181
+ * The three `runs:` shapes an `action.yml` can declare.
2182
+ *
2183
+ * @public
2184
+ */
2185
+ type ActionManifestRuns = ActionManifestNodeRuns | ActionManifestCompositeRuns | ActionManifestDockerRuns;
2186
+ declare const ActionManifestBranding_base: Schema.Class<ActionManifestBranding, Schema.Struct<{
2187
+ /** A Feather icon name. */
2188
+ readonly icon: Schema.optionalKey<Schema.String>;
2189
+ /** The badge background colour. */
2190
+ readonly color: Schema.optionalKey<Schema.String>;
2191
+ }>, {}>;
2192
+ /**
2193
+ * The `branding:` block a Marketplace listing reads.
2194
+ *
2195
+ * @public
2196
+ */
2197
+ export declare class ActionManifestBranding extends ActionManifestBranding_base {}
2198
+ declare const ActionManifestReadError_base: Schema.Class<ActionManifestReadError, Schema.TaggedStruct<"ActionManifestReadError", {
2199
+ /** The path that was being read. */
2200
+ readonly path: Schema.String;
2201
+ /** The underlying failure, preserved structurally. */
2202
+ readonly cause: Schema.Defect;
2203
+ }>, import("effect/Cause").YieldableError>;
2204
+ /**
2205
+ * Raised when an `action.yml` cannot be read from the filesystem.
2206
+ *
2207
+ * @public
2208
+ */
2209
+ export declare class ActionManifestReadError extends ActionManifestReadError_base {
2210
+ get message(): string;
2211
+ }
2212
+ declare const ActionManifestDecodeError_base: Schema.Class<ActionManifestDecodeError, Schema.TaggedStruct<"ActionManifestDecodeError", {
2213
+ /** The rendered parse or schema failure. */
2214
+ readonly detail: Schema.String;
2215
+ /** The `YamlParseError` or `SchemaError` behind it. */
2216
+ readonly cause: Schema.Defect;
2217
+ }>, import("effect/Cause").YieldableError>;
2218
+ /**
2219
+ * Raised when an `action.yml` is not valid YAML, or is YAML that does not
2220
+ * have the shape of an action manifest.
2221
+ *
2222
+ * @remarks
2223
+ * One class for both, because the two share every field and no caller
2224
+ * recovers from one but not the other: either way the manifest is broken.
2225
+ * `detail` is the rendered parse or schema failure and `cause` the structured
2226
+ * original.
2227
+ *
2228
+ * @public
2229
+ */
2230
+ export declare class ActionManifestDecodeError extends ActionManifestDecodeError_base {
2231
+ get message(): string;
2232
+ }
2233
+ /**
2234
+ * Anything that can go wrong loading an `action.yml`.
2235
+ *
2236
+ * @public
2237
+ */
2238
+ type ActionManifestError = ActionManifestReadError | ActionManifestDecodeError;
2239
+ /**
2240
+ * The names an action's code reads and writes, for {@link ActionManifest.diff}.
2241
+ *
2242
+ * @public
2243
+ */
2244
+ interface ActionManifestUsage {
2245
+ /** The input names the code reads, spelled as in `action.yml`. */
2246
+ readonly inputs?: Iterable<string>;
2247
+ /** The output names the code writes. Omit to skip the output comparison. */
2248
+ readonly outputs?: Iterable<string>;
2249
+ }
2250
+ declare const ActionManifestDiff_base: Schema.Class<ActionManifestDiff, Schema.Struct<{
2251
+ /** Declared in `action.yml`, never read by the code. */
2252
+ readonly unreadInputs: Schema.$Array<Schema.String>;
2253
+ /** Read by the code, not declared in `action.yml` — on a runner it arrives absent. */
2254
+ readonly undeclaredInputs: Schema.$Array<Schema.String>;
2255
+ /** Declared in `action.yml`, never written by the code. */
2256
+ readonly unwrittenOutputs: Schema.$Array<Schema.String>;
2257
+ /** Written by the code, not declared in `action.yml`. */
2258
+ readonly undeclaredOutputs: Schema.$Array<Schema.String>;
2259
+ }>, {}>;
2260
+ /**
2261
+ * Where an action's code and its `action.yml` disagree.
2262
+ *
2263
+ * @remarks
2264
+ * Every list is in declaration or usage order, with duplicates removed. An
2265
+ * empty diff — {@link ActionManifestDiff.inSync} — means the code reads every
2266
+ * declared input, declares every input it reads, and the same for outputs.
2267
+ *
2268
+ * @public
2269
+ */
2270
+ export declare class ActionManifestDiff extends ActionManifestDiff_base {
2271
+ /** True when the code and the manifest agree on every name. */
2272
+ get inSync(): boolean;
2273
+ }
2274
+ declare const ActionManifest_base: Schema.Class<ActionManifest, Schema.Struct<{
2275
+ /** The action's display name. */
2276
+ readonly name: Schema.String;
2277
+ /** What the action does. */
2278
+ readonly description: Schema.optionalKey<Schema.String>;
2279
+ /** Who wrote the action. */
2280
+ readonly author: Schema.optionalKey<Schema.String>;
2281
+ /** The declared inputs, keyed by name. */
2282
+ readonly inputs: Schema.optionalKey<Schema.$Record<Schema.String, typeof ActionManifestInput>>;
2283
+ /** The declared outputs, keyed by name. */
2284
+ readonly outputs: Schema.optionalKey<Schema.$Record<Schema.String, typeof ActionManifestOutput>>;
2285
+ /** How the action executes. */
2286
+ readonly runs: Schema.Union<readonly [Schema.encodeKeys<typeof ActionManifestNodeRuns, {
2287
+ readonly preIf: "pre-if";
2288
+ readonly postIf: "post-if";
2289
+ }>, typeof ActionManifestCompositeRuns, Schema.encodeKeys<typeof ActionManifestDockerRuns, {
2290
+ readonly preEntrypoint: "pre-entrypoint";
2291
+ readonly postEntrypoint: "post-entrypoint";
2292
+ readonly preIf: "pre-if";
2293
+ readonly postIf: "post-if";
2294
+ }>]>;
2295
+ /** The Marketplace badge. */
2296
+ readonly branding: Schema.optionalKey<typeof ActionManifestBranding>;
2297
+ }>, {}>;
2298
+ /**
2299
+ * A decoded `action.yml`: the action's metadata, its declared inputs and
2300
+ * outputs, and the `runs:` block naming how it executes.
2301
+ *
2302
+ * @remarks
2303
+ * `action.yml` is the single source of truth for an action's input names and
2304
+ * defaults, and the code mirrors both. This construct makes the mirror
2305
+ * testable: {@link ActionManifest.runnerInputs} builds the input environment a
2306
+ * real runner builds from the manifest, and {@link ActionManifest.diff} reports
2307
+ * where the code's reads and writes disagree with what the manifest declares.
2308
+ *
2309
+ * `inputs` and `outputs` are keyed by name, in declaration order. Keys this
2310
+ * construct does not describe are ignored, so a manifest carrying a newer
2311
+ * metadata key still decodes.
2312
+ *
2313
+ * @example
2314
+ * ```ts
2315
+ * import { ActionInput, ActionManifest } from "@effected/github-actions";
2316
+ * import { Effect } from "effect";
2317
+ *
2318
+ * const program = Effect.gen(function* () {
2319
+ * const manifest = yield* ActionManifest.read("action.yml");
2320
+ * // Every declared input present, with its manifest default or "".
2321
+ * const layer = ActionInput.layer(ActionManifest.runnerInputs(manifest, { "dry-run": "true" }));
2322
+ * return layer;
2323
+ * });
2324
+ * ```
2325
+ *
2326
+ * @public
2327
+ */
2328
+ export declare class ActionManifest extends ActionManifest_base {
2329
+ /**
2330
+ * Decode `action.yml` text, synchronously.
2331
+ *
2332
+ * @remarks
2333
+ * Fails with {@link ActionManifestDecodeError} when the text is not YAML or
2334
+ * not an action manifest. This is the form for a test that wants the
2335
+ * manifest without an effect; {@link ActionManifest.decode} is the same
2336
+ * decode as an `Effect`.
2337
+ */
2338
+ static decodeResult(source: string): Result.Result<ActionManifest, ActionManifestDecodeError>;
2339
+ /**
2340
+ * Decode `action.yml` text.
2341
+ *
2342
+ * @remarks
2343
+ * Fails with {@link ActionManifestDecodeError} when the text is not YAML or
2344
+ * not an action manifest.
2345
+ */
2346
+ static readonly decode: (source: string) => Effect.Effect<ActionManifest, ActionManifestDecodeError>;
2347
+ /**
2348
+ * Read and decode the `action.yml` at `path`.
2349
+ *
2350
+ * @remarks
2351
+ * Reads through `FileSystem` in `R`, so a test provides `@effected/memfs`
2352
+ * and production the platform filesystem. A read failure is
2353
+ * {@link ActionManifestReadError}, carrying the path; a malformed manifest is
2354
+ * {@link ActionManifestDecodeError}.
2355
+ */
2356
+ static readonly read: (path: string) => Effect.Effect<ActionManifest, ActionManifestDecodeError | ActionManifestReadError, FileSystem.FileSystem>;
2357
+ /**
2358
+ * The input environment a real runner builds for this manifest.
2359
+ *
2360
+ * @remarks
2361
+ * The runner publishes a variable for **every** declared input: the value
2362
+ * the workflow supplied under `with:`, else the manifest `default`, else
2363
+ * `""`. So "absent" is a state production never produces, and a test built
2364
+ * on an empty `ActionInput.layer({})` exercises the code's
2365
+ * `Config.withDefault` fallbacks rather than the manifest defaults a real
2366
+ * run decodes. This record is the runner-shaped baseline instead.
2367
+ *
2368
+ * Keys are runner variables — `INPUT_` plus the name uppercased with spaces
2369
+ * turned to underscores and every other character, dashes included, kept
2370
+ * (`write-summary` → `INPUT_WRITE-SUMMARY`) — derived through
2371
+ * `ActionInput.variable`, the same function every accessor reads through.
2372
+ * So the record feeds `ActionInput.layer`, spreads into
2373
+ * `ActionEnvironment.layerTest`'s overrides, or becomes a spawned
2374
+ * process's environment unchanged.
2375
+ *
2376
+ * `supplied` is the workflow's `with:` block, keyed by input name, and is
2377
+ * matched to the declared inputs **by runner variable**, the way
2378
+ * {@link ActionManifest.diff} matches: `write summary`, `write_summary` and
2379
+ * `WRITE_SUMMARY` all supply the input declared as `write_summary`. A
2380
+ * supplied value wins even when it is `""`, as on a runner.
2381
+ *
2382
+ * A supplied name the manifest does not declare is **passed through** as
2383
+ * one more `INPUT_` variable, because the runner publishes it too — it only
2384
+ * warns. This never throws. To catch a typo in a test, compare the names
2385
+ * with {@link ActionManifest.diff}, which reports an undeclared read; a
2386
+ * typoed supplied name otherwise leaves the declared input on its default.
2387
+ *
2388
+ * **Composite actions receive no `INPUT_` environment.** The runner
2389
+ * publishes these variables to node and docker actions only; a composite
2390
+ * action reads its inputs through `inputs.<name>` expressions in its steps.
2391
+ * This builder is for node and docker actions, and for a composite test
2392
+ * that drives the inputs into its steps explicitly.
2393
+ *
2394
+ * @param manifest - The decoded manifest.
2395
+ * @param supplied - The workflow's `with:` values, keyed by input name.
2396
+ * @returns The runner's `INPUT_*` variables: one per declared input, then
2397
+ * one per supplied name the manifest does not declare.
2398
+ */
2399
+ static runnerInputs(manifest: ActionManifest, supplied?: Readonly<Record<string, string>>): Record<string, string>;
2400
+ /**
2401
+ * Compare the names an action's code reads and writes against the names
2402
+ * its manifest declares.
2403
+ *
2404
+ * @remarks
2405
+ * Inputs are matched the way the runner connects them — by runner
2406
+ * variable — so `write summary` in code and `write_summary` in the
2407
+ * manifest are the same input, and so are names differing only in case.
2408
+ * Outputs are matched verbatim. Omitting `usage.outputs` skips the output
2409
+ * comparison, leaving both output lists empty; omitting `usage.inputs`
2410
+ * compares against no reads, so every declared input reports unread.
2411
+ *
2412
+ * @example
2413
+ * ```ts
2414
+ * import { assert, it } from "@effect/vitest";
2415
+ * import { ActionManifest } from "@effected/github-actions";
2416
+ *
2417
+ * declare const manifest: ActionManifest;
2418
+ *
2419
+ * it("action.yml and the code agree", () => {
2420
+ * const diff = ActionManifest.diff(manifest, { inputs: ["name", "dry-run"], outputs: ["greeting"] });
2421
+ * assert.isTrue(diff.inSync, JSON.stringify(diff));
2422
+ * });
2423
+ * ```
2424
+ */
2425
+ static diff(manifest: ActionManifest, usage: ActionManifestUsage): ActionManifestDiff;
2426
+ }
1988
2427
  declare const OidcTokenError_base: Schema.Class<OidcTokenError, Schema.TaggedStruct<"OidcTokenError", {
1989
2428
  /**
1990
2429
  * `unavailable` — the runner did not publish the token-service variables,
@@ -5265,5 +5704,5 @@ export declare class Secret {
5265
5704
  */
5266
5705
  static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
5267
5706
  }
5268
- export { type ActionCacheShape, type ActionEnvironmentShape, type ActionLoggerShape, type ActionOutputError, type ActionOutputsShape, type ActionRunOptions, type ActionServices, type ActionStateShape, type AnnotationProperties, type ArtifactItem, type ArtifactRef, type ArtifactShape, type BlobEnvelopeError, type BlobStoreShape, type CacheKeyError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, type CheckFlushOutcome, type CheckRunConclusion, type CheckRunProjection, type ClientLayerOptions, type DataBlobTransfer, type DetachedProcessError, type DetachedProcessOps, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, type DryRunShape, type ExtractOptions, type FileBlobTransfer, type GitHubHeadingDepth, type GitHubListOptions, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, type ManagedDocumentSource, type OidcTokenIssuerShape, type PackageManagerInstallOptions, type PackageManagerInstallerShape, type PairsOptions, type PathPrependEnv, type PathPrependOptions, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, type RecordedOutputMember, type RecordingOidcTokenIssuer, type RecordingOutputs, type S3Config, type StoredBlob, type ToolDownloadOptions, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, type WithStepOptions, WorkflowCommand };
5707
+ export { type ActionCacheShape, type ActionEnvironmentShape, type ActionInputRecording, type ActionLoggerShape, type ActionManifestError, type ActionManifestRuns, type ActionManifestUsage, type ActionOutputError, type ActionOutputsShape, type ActionRunOptions, type ActionServices, type ActionStateShape, type AnnotationProperties, type ArtifactItem, type ArtifactRef, type ArtifactShape, type BlobEnvelopeError, type BlobStoreShape, type CacheKeyError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, type CheckFlushOutcome, type CheckRunConclusion, type CheckRunProjection, type ClientLayerOptions, type DataBlobTransfer, type DetachedProcessError, type DetachedProcessOps, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, type DryRunShape, type ExtractOptions, type FileBlobTransfer, type GitHubHeadingDepth, type GitHubListOptions, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, type ManagedDocumentSource, type OidcTokenIssuerShape, type PackageManagerInstallOptions, type PackageManagerInstallerShape, type PairsOptions, type PathPrependEnv, type PathPrependOptions, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, type RecordedOutputMember, type RecordingOidcTokenIssuer, type RecordingOutputs, type S3Config, type StoredBlob, type ToolDownloadOptions, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, type WithStepOptions, WorkflowCommand };
5269
5708
  //# sourceMappingURL=index.d.ts.map
package/index.js CHANGED
@@ -6,6 +6,7 @@ import { ActionState, ActionStateError } from "./ActionState.js";
6
6
  import { Action, ActionRuntime, describeCause } from "./Action.js";
7
7
  import { BlobTransferError } from "./BlobTransfer.js";
8
8
  import { ActionCache, ActionCacheError } from "./ActionCache.js";
9
+ import { ActionManifest, ActionManifestBranding, ActionManifestCompositeRuns, ActionManifestDecodeError, ActionManifestDiff, ActionManifestDockerRuns, ActionManifestInput, ActionManifestNodeRuns, ActionManifestOutput, ActionManifestReadError } from "./ActionManifest.js";
9
10
  import { Secret } from "./Secret.js";
10
11
  import { OidcTokenError, OidcTokenIssuer } from "./OidcTokenIssuer.js";
11
12
  import { ActionsIdentityToken } from "./ActionsIdentityToken.js";
@@ -28,4 +29,4 @@ import { ToolInstaller, ToolInstallerError } from "./ToolInstaller.js";
28
29
  import { AmbientPackageManager, CachedPackageManager, InstalledPackageManager, PackageManagerInstaller, PackageManagerInstallerError } from "./PackageManagerInstaller.js";
29
30
  import { WorkflowCommand } from "@effected/github-commands";
30
31
 
31
- export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, ActionsRegistryCredential, 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, OidcTokenError, OidcTokenIssuer, OutputEncodeError, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RecordedOutput, RunnerContext, RunnerFileUnavailableError, RunnerFileWriteError, Secret, ToolInstaller, ToolInstallerError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError, WorkflowCommand, describeCause, projectCheckState };
32
+ export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionManifest, ActionManifestBranding, ActionManifestCompositeRuns, ActionManifestDecodeError, ActionManifestDiff, ActionManifestDockerRuns, ActionManifestInput, ActionManifestNodeRuns, ActionManifestOutput, ActionManifestReadError, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, ActionsRegistryCredential, 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, OidcTokenError, OidcTokenIssuer, OutputEncodeError, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RecordedOutput, RunnerContext, RunnerFileUnavailableError, RunnerFileWriteError, Secret, ToolInstaller, ToolInstallerError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError, WorkflowCommand, describeCause, projectCheckState };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effected/github-actions",
3
- "version": "0.27.0",
3
+ "version": "0.28.0",
4
4
  "private": false,
5
5
  "description": "The GitHub Actions runtime: env, inputs, outputs, state, logging, cache, artifacts, blob storage, OIDC and the token bridge.",
6
6
  "keywords": [
@@ -39,18 +39,19 @@
39
39
  },
40
40
  "dependencies": {
41
41
  "@azure/storage-blob": "^12.33.0",
42
- "@effected/crypto": "^0.1.1",
43
- "@effected/github": "^0.24.0",
42
+ "@effected/crypto": "^0.2.0",
43
+ "@effected/github": "^0.25.0",
44
44
  "@effected/github-commands": "^0.6.2",
45
45
  "@effected/glob": "^0.14.0",
46
46
  "@effected/jwt": "^0.6.0",
47
- "@effected/markdown": "^0.22.0",
48
- "@effected/npm": "^0.26.1",
47
+ "@effected/markdown": "^0.23.0",
48
+ "@effected/npm": "^0.26.2",
49
49
  "@effected/oidc": "^0.1.2",
50
50
  "@effected/sbom": "^0.16.0",
51
- "@effected/semver": "^0.17.0",
51
+ "@effected/semver": "^0.18.0",
52
52
  "@effected/templates": "^0.14.1",
53
- "@effected/walker": "^0.19.0"
53
+ "@effected/walker": "^0.20.0",
54
+ "@effected/yaml": "^0.25.1"
54
55
  },
55
56
  "peerDependencies": {
56
57
  "@effect/platform-node": "^4.0.0",