Skip to content

Commit 3f98bad

Browse files
committed
🧪 Give each scenario document its own testing session
Replaces the incomplete root-testing composition — installTestingComponents() followed by Test.around({ testing: () => true }) — with one complete useTesting() session per document execution. The shortcut never activated. <Test> skipped, its body expanded inline, the assertions inside rendered their ordinary pass reports, and the session collected nothing: a document that tested nothing was indistinguishable from one that passed. Filed as #523 for the testing API itself; nothing here waits on it. The runner now keeps the tracker server, the journals and the provider middleware in one enclosing scope, and gives each execution a child scope holding exactly two things: one session and one document. The session's own outcome is the authority — a failed or zero-test suite settles Err(TestFailureError) — so a suite that discovered nothing cannot pass by having nothing to fail. A session admits one execute() call, so a document cannot run another document from inside a component. <WorkflowAttempt> is therefore gone. A scenario that stands on what an earlier run left stages those attempts through the fixture, before the document that asserts about them, and reads their outcomes back with <StagedAttempt>. A staged attempt is a previous run rather than a test, so it gets a child scope and its own provider installation, and no session. Two consequences of the enclosing fixture, both made explicit rather than implied: - <GitHubServer> reports the tracker and no longer clears it, because an attempt staged before the document is exactly the state some scenarios are about. A test that wants an empty tracker says <FreshTracker />. - useKeyRecorder() installed its handler inside a scoped() that closed on return, so it recorded nothing. It installs into the caller's scope now. <ServerRequests> reports the authorization scheme and whether the expected credential arrived, never the header. Handing a document the header put a credential in its own text and in the run's retained history — the one thing this contract says a history never holds, and the fixture must not be the exception that proves it. It also tripped a gate defect: an execution that renders a detected secret never settles, filed as #524. Evidence that the arrangement holds is in tests/scenarios/sessions: two documents share one tracker while receiving disjoint, non-empty result sets; a failing assertion fails its own document and leaves the next one passing; and a document with no tests settles Err.
1 parent c4646da commit 3f98bad

30 files changed

Lines changed: 2239 additions & 1495 deletions

‎packages/cli/src/deno-workflow.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import {
2727
import type { WorkflowExecutionTransitions } from "@executablemd/workflow/deno";
2828
import type { WorkflowRunDatabase } from "@executablemd/workflow";
2929
import type { WorkflowHost } from "./workflow.ts";
30+
import { gitHubIssuesConfiguration } from "./github-issues-config.ts";
3031

3132
/** Where a run lives when nothing says otherwise. */
3233
export const DEFAULT_RUN_STORAGE_ROOT: string = join(homedir(), ".xmd", "runs");
@@ -38,6 +39,10 @@ export function* useDenoWorkflowHost(): Operation<WorkflowHost> {
3839
const configured = yield* readEnv(RUN_STORAGE_ROOT_ENV);
3940
const root =
4041
configured === undefined || configured === "" ? DEFAULT_RUN_STORAGE_ROOT : configured;
42+
// Read once, at host construction, so an operator who wrote something this
43+
// host cannot use learns it before a document runs rather than in the middle
44+
// of one. Absent installs no issue provider at all.
45+
const gitHubIssues = yield* gitHubIssuesConfiguration();
4146
return {
4247
useRunHost(): Operation<WorkflowExecutionTransitions> {
4348
return useWorkflowRunHost({ root });
@@ -49,7 +54,9 @@ export function* useDenoWorkflowHost(): Operation<WorkflowHost> {
4954
return useWorkflowInputDelivery({ root });
5055
},
5156
attach<T>(database: WorkflowRunDatabase, operation: Operation<T>): Operation<T> {
52-
return withWorkflowWorkspace(database, operation);
57+
return withWorkflowWorkspace(database, operation, {
58+
...(gitHubIssues === undefined ? {} : { gitHubIssues }),
59+
});
5360
},
5461
};
5562
}
Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
/**
2+
* Where the production host learns which issue trackers it may reach.
3+
*
4+
* A tracker URL a document writes is composition data: it says where an issue
5+
* is wanted, not that this deployment allows it. What allows it is here, beside
6+
* the credential, and it is the operator's to state — so it is read from the
7+
* environment rather than from anything a run can influence.
8+
*
9+
* Absence installs nothing, and that is fail-closed by construction: with no
10+
* provider installed, `<Issue>` reaches `IssueApi`'s own base error and says
11+
* that nothing handles the destination. A deployment that wants issues says so.
12+
*
13+
* Malformed configuration is refused rather than narrowed to what parsed. An
14+
* operator who wrote a ceiling this host could not read has not authorized the
15+
* empty set — they have made a mistake, and running with fewer targets than
16+
* they wrote would hide it until the day it mattered.
17+
*/
18+
19+
import { env as readEnv } from "@executablemd/runtime";
20+
import type { Operation } from "effection";
21+
import { canonicalIssueTarget } from "@executablemd/workflow";
22+
import type { GitHubIssuesOptions } from "@executablemd/workflow/deno";
23+
24+
/** The variable that configures GitHub issue handling. */
25+
export const GITHUB_ISSUES_ENV = "XMD_WORKFLOW_GITHUB_ISSUES";
26+
27+
/** What an operator wrote there, once it is something this host can use. */
28+
export class GitHubIssuesConfigError extends Error {
29+
override name = "GitHubIssuesConfigError";
30+
31+
constructor(sentence: string) {
32+
super(
33+
`${GITHUB_ISSUES_ENV} is not usable: ${sentence} Expected JSON such as ` +
34+
`{"ceiling":["https://github.com/owner/repo"],"endpoint":"https://api.github.com"} — ` +
35+
"ceiling is required, endpoint is optional. Unset it to install no issue provider.",
36+
);
37+
}
38+
}
39+
40+
/**
41+
* The GitHub issue options this host is configured with, or none.
42+
*
43+
* Strict about shape and about the URLs it holds. A ceiling entry that is not
44+
* the canonical name of a container is refused here rather than at the first
45+
* request, because an operator reading a startup failure can fix it and a
46+
* document author reading a refusal mid-run cannot.
47+
*/
48+
export function* gitHubIssuesConfiguration(): Operation<GitHubIssuesOptions | undefined> {
49+
const written = yield* readEnv(GITHUB_ISSUES_ENV);
50+
if (written === undefined || written === "") {
51+
return undefined;
52+
}
53+
let parsed: unknown;
54+
try {
55+
parsed = JSON.parse(written);
56+
} catch {
57+
throw new GitHubIssuesConfigError("it is not JSON.");
58+
}
59+
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
60+
throw new GitHubIssuesConfigError("it is not a JSON object.");
61+
}
62+
for (const key of Object.keys(parsed)) {
63+
if (key !== "ceiling" && key !== "endpoint") {
64+
throw new GitHubIssuesConfigError(
65+
`it carries ${JSON.stringify(key)}, which is not a member.`,
66+
);
67+
}
68+
}
69+
const declared = Reflect.get(parsed, "ceiling");
70+
if (!Array.isArray(declared) || declared.length === 0) {
71+
throw new GitHubIssuesConfigError("its ceiling is not a non-empty array of container URLs.");
72+
}
73+
const ceiling: string[] = [];
74+
for (const entry of declared) {
75+
const canonical = canonicalIssueTarget(entry);
76+
if (canonical === undefined) {
77+
throw new GitHubIssuesConfigError(
78+
"one of its ceiling entries is not an http or https URL naming one container, free of " +
79+
"credentials, query and fragment.",
80+
);
81+
}
82+
ceiling.push(canonical);
83+
}
84+
const endpoint = Reflect.get(parsed, "endpoint");
85+
if (endpoint !== undefined && (typeof endpoint !== "string" || endpoint === "")) {
86+
throw new GitHubIssuesConfigError("its endpoint is not a URL.");
87+
}
88+
return Object.freeze({
89+
ceiling: Object.freeze(ceiling),
90+
...(typeof endpoint === "string" ? { endpoint } : {}),
91+
});
92+
}

‎packages/cli/tests/workflow-host.test.ts‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,12 @@ import { randomUUID } from "node:crypto";
2020
import { join } from "node:path";
2121
import { tmpdir } from "node:os";
2222
import { cliRuntime, runCli } from "@executablemd/test-support/launch";
23+
import { API } from "@executablemd/runtime";
24+
import {
25+
GITHUB_ISSUES_ENV,
26+
GitHubIssuesConfigError,
27+
gitHubIssuesConfiguration,
28+
} from "../src/github-issues-config.ts";
2329

2430
/** The one sentence a host without workflow support says. */
2531
const UNSUPPORTED =
@@ -131,3 +137,77 @@ describe("Tier WFH — workflow host boundary", () => {
131137
});
132138
});
133139
});
140+
141+
describe("Tier WFH — GitHub issue handling is host configuration", () => {
142+
/**
143+
* H1. Which trackers a run may reach is the operator's to state, so it is
144+
* read from the environment and from nowhere a document can influence.
145+
*
146+
* Absence installs no provider, and that is fail-closed by construction
147+
* rather than by a check: with nothing installed, `<Issue>` meets
148+
* `IssueApi`'s own base error. Malformed configuration fails here, where an
149+
* operator can fix it, rather than at the first request in the middle of a
150+
* run.
151+
*/
152+
function configured(value: string | undefined): Operation<unknown> {
153+
return scoped(function* () {
154+
yield* API.Env.around({
155+
// deno-lint-ignore require-yield
156+
*env([name]) {
157+
return name === GITHUB_ISSUES_ENV ? value : undefined;
158+
},
159+
});
160+
return yield* gitHubIssuesConfiguration();
161+
});
162+
}
163+
164+
it("installs nothing when nothing is configured", function* () {
165+
expect(yield* configured(undefined)).toBeUndefined();
166+
expect(yield* configured("")).toBeUndefined();
167+
});
168+
169+
it("reads a ceiling, and canonicalizes every entry", function* () {
170+
const options = yield* configured(
171+
JSON.stringify({ ceiling: ["https://github.com/octo/project/"] }),
172+
);
173+
expect(options).toEqual({ ceiling: ["https://github.com/octo/project"] });
174+
175+
const withEndpoint = yield* configured(
176+
JSON.stringify({
177+
ceiling: ["https://github.com/octo/project"],
178+
endpoint: "https://ghe.example.invalid/api/v3",
179+
}),
180+
);
181+
expect(withEndpoint).toEqual({
182+
ceiling: ["https://github.com/octo/project"],
183+
endpoint: "https://ghe.example.invalid/api/v3",
184+
});
185+
});
186+
187+
it("refuses configuration it cannot use rather than narrowing it", function* () {
188+
const refused = [
189+
"not json",
190+
"[]",
191+
'"a string"',
192+
JSON.stringify({}),
193+
JSON.stringify({ ceiling: [] }),
194+
JSON.stringify({ ceiling: "https://github.com/octo/project" }),
195+
JSON.stringify({ ceiling: ["not a url"] }),
196+
JSON.stringify({ ceiling: ["https://github.com/octo/project?tab=issues"] }),
197+
JSON.stringify({ ceiling: ["https://github.com/octo/project"], endpoint: 7 }),
198+
// An operator who wrote a member this host does not know has not
199+
// configured what they think they have.
200+
JSON.stringify({ ceiling: ["https://github.com/octo/project"], token: "…" }),
201+
];
202+
for (const value of refused) {
203+
let raised: unknown;
204+
try {
205+
yield* configured(value);
206+
} catch (error) {
207+
raised = error;
208+
}
209+
expect(raised).toBeInstanceOf(GitHubIssuesConfigError);
210+
expect(String(raised)).toContain(GITHUB_ISSUES_ENV);
211+
}
212+
});
213+
});

‎packages/workflow/mod.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,14 @@ export { admitPushEvidence } from "./src/composition/push-evidence.ts";
203203
export { useCompositionComponents } from "./src/composition/installation.ts";
204204

205205
export { ISSUE_API, IssueApi, NoIssueProvider } from "./src/issue/api.ts";
206-
export type { IssueInput, IssueResult, IssueUpsertOptions } from "./src/issue/api.ts";
206+
export type {
207+
IssueDetails,
208+
IssueInput,
209+
IssueOperation,
210+
IssueReadOptions,
211+
IssueReference,
212+
IssueUpsertOptions,
213+
} from "./src/issue/api.ts";
207214
export {
208215
ISSUE_TRACKER_CONTEXT,
209216
IssueTrackerContext,

0 commit comments

Comments
 (0)