From 3ccb7bdcd9d12eecc62fbd2d45a8a06e53d4a82e Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 13:22:11 -0500 Subject: [PATCH 01/78] test: attribute failure journals to declaring cases --- packages/cli/src/test-diagnostics.ts | 28 +- packages/cli/tests/repl-execution.test.ts | 204 +++++++------ .../core/tests/streaming-emission.test.ts | 149 +++++++--- .../tests/session-configuration.test.ts | 270 +++++++++--------- packages/test-support/failure-journal.ts | 47 +++ .../testing/tests/execution-harness.test.ts | 88 ++++-- 6 files changed, 494 insertions(+), 292 deletions(-) create mode 100644 packages/test-support/failure-journal.ts diff --git a/packages/cli/src/test-diagnostics.ts b/packages/cli/src/test-diagnostics.ts index d02b71af3..9762e194a 100644 --- a/packages/cli/src/test-diagnostics.ts +++ b/packages/cli/src/test-diagnostics.ts @@ -44,6 +44,13 @@ const DEFAULT_TEST_ARTIFACTS = join(".xmd", "test-artifacts"); const PREFIX = "[xmd test]"; +/** The repository test declaration that owns an automatic journal. */ +export interface JournalCase { + readonly owner: string; + readonly name: string; + readonly suite?: string; +} + /** This command's diagnostics, shared by its root documents and their children. */ export interface TestDiagnostics { /** @@ -95,7 +102,11 @@ function* artifactDirectory(working: string): Operation { * diagnostics drains what was accepted before it returns — on success, failure * and cancellation alike — and nothing is written after that. */ -export function useTestDiagnostics(sink: DeliverySink): Operation { +export function useTestDiagnostics( + sink: DeliverySink, + testCase?: JournalCase, +): Operation { + const attribution = testCase === undefined ? undefined : { ...testCase }; return resource(function* (provide) { const working = yield* cwd(); const directory = yield* artifactDirectory(working); @@ -127,10 +138,11 @@ export function useTestDiagnostics(sink: DeliverySink): Operation observe(owner, shown, (line) => emit(`${context}${line}`)), @@ -138,6 +150,12 @@ export function useTestDiagnostics(sink: DeliverySink): Operation { const REFERENCE_PATH = join(REFERENCE_DIRECTORY, "entry.md"); +const OWNER = "packages/cli/tests/repl-execution.test.ts"; +const SUBMIT_SUITE = "REPL execution: submitting one entry"; + function captureReferenceEntry( + name: string, body: (holder: ReplExecution) => Operation, sink: DeliverySink = process.stderr, ): Operation { - return scoped(function* () { - const diagnostics = yield* useTestDiagnostics(sink); - const journal = diagnostics.execution("root", REFERENCE_PATH).journal(() => false); - yield* withFailureJournal( - { - ...journal, - *save(events) { - const partition = partitionEntrySegments(events); - if (!partition.ok) { - throw partition.error; - } - if (partition.value.length > 1) { - throw new Error("reference execution holds more than one admitted entry"); - } - const [entry] = partition.value; - if (entry !== undefined) { - yield* journal.save(entry.events); - } - }, + return captureTestJournal( + { owner: OWNER, suite: SUBMIT_SUITE, name }, + REFERENCE_PATH, + (stream) => body({ id: "kf39sla2", stream }), + { + sink, + selectEvents(events) { + const partition = partitionEntrySegments(events); + if (!partition.ok) { + throw partition.error; + } + if (partition.value.length > 1) { + throw new Error("reference execution holds more than one admitted entry"); + } + return partition.value[0]?.events ?? []; }, - (stream) => body({ id: "kf39sla2", stream }), - ); - }); + }, + ); } function admitReferenceEntry( + name: string, check?: (holder: ReplExecution) => Operation, sink?: DeliverySink, ): Operation { - return captureReferenceEntry(function* (holder) { - const source = yield* referenceSource(); - const session = opened(yield* submitReplEntry({ ...options(holder), source })); + return captureReferenceEntry( + name, + function* (holder) { + const source = yield* referenceSource(); + const session = opened(yield* submitReplEntry({ ...options(holder), source })); - const question = yield* nextQuestion(session); - expect(question.message).toContain("Approve Ship the REPL?"); - // The whole form the schema reads as, member for member: every field the - // drawer draws, with its annotations, its required marker and the values it - // accepts. - expect(question.form).toEqual({ - title: undefined, - description: undefined, - condition: undefined, - fields: [ - { - name: "decision", - title: undefined, - description: undefined, - choices: ["approve", "decline"], - minLength: undefined, - required: true, - }, - ], - }); - expect(session.model.entries[0]?.scope.elicitations).toEqual([]); + const question = yield* nextQuestion(session); + expect(question.message).toContain("Approve Ship the REPL?"); + // The whole form the schema reads as, member for member: every field the + // drawer draws, with its annotations, its required marker and the values it + // accepts. + expect(question.form).toEqual({ + title: undefined, + description: undefined, + condition: undefined, + fields: [ + { + name: "decision", + title: undefined, + description: undefined, + choices: ["approve", "decline"], + minLength: undefined, + required: true, + }, + ], + }); + expect(session.model.entries[0]?.scope.elicitations).toEqual([]); - expect(question.submit({ decision: "approve" }).kind).toBe("answered"); - yield* session.join(); + expect(question.submit({ decision: "approve" }).kind).toBe("answered"); + yield* session.join(); - const entry = session.model.entries[0]?.scope; - if (entry === undefined) { - throw new Error("the entry was admitted"); - } - expect(entry.source).toBe(source); - expect(entry.bindings.map((binding) => binding.name)).toContain("plan"); - expect(entry.scopes.map((scope) => scope.key)).toEqual(["Checklist-1", "generated-1"]); - expect(entry.elicitations[0].answer).toEqual({ decision: "approve" }); - expect(session.model.settled).toBe(true); - expect(session.model.terminal?.output).toContain("Decision: approve"); - expect(session.overlay.output).toBe(session.model.terminal?.output); - if (check !== undefined) { - yield* check(holder); - } - }, sink); + const entry = session.model.entries[0]?.scope; + if (entry === undefined) { + throw new Error("the entry was admitted"); + } + expect(entry.source).toBe(source); + expect(entry.bindings.map((binding) => binding.name)).toContain("plan"); + expect(entry.scopes.map((scope) => scope.key)).toEqual(["Checklist-1", "generated-1"]); + expect(entry.elicitations[0].answer).toEqual({ decision: "approve" }); + expect(session.model.settled).toBe(true); + expect(session.model.terminal?.output).toContain("Decision: approve"); + expect(session.overlay.output).toBe(session.model.terminal?.output); + if (check !== undefined) { + yield* check(holder); + } + }, + sink, + ); } -describe("REPL execution: submitting one entry", () => { +describe(SUBMIT_SUITE, () => { beforeAll(() => useTempFileCompiler()); - it("X1: admits the exact source, binds, generates, asks, and settles", () => - admitReferenceEntry()); + const admission = "X1: admits the exact source, binds, generates, asks, and settles"; + it(admission, () => admitReferenceEntry(admission)); - it("X1: the overlay reports its output as the document prints it", () => - captureReferenceEntry(function* (holder) { + const overlay = "X1: the overlay reports its output as the document prints it"; + it(overlay, () => + captureReferenceEntry(overlay, function* (holder) { const source = yield* referenceSource(); const session = opened(yield* submitReplEntry({ ...options(holder), source })); @@ -354,9 +358,11 @@ describe("REPL execution: submitting one entry", () => { question.submit({ decision: "approve" }); yield* session.join(); - })); + }), + ); - it("saves the joined reference entry only when its case fails after admission", function* () { + const witness = "saves the joined reference entry only when its case fails after admission"; + it(witness, function* () { const directory = yield* useTempDirectory("xmd-repl-entry-journal-"); const failed = join(directory, "failed"); const passed = join(directory, "passed"); @@ -386,19 +392,23 @@ describe("REPL execution: submitting one entry", () => { try { yield* atArtifactRoot( failed, - admitReferenceEntry(function* (holder) { - recorded = yield* readAll(holder); - try { - expect( - recorded.some( - (event) => event.type === "yield" && event.description.name === ROOT_IMPORT, - ), - ).toBe(false); - } catch (error) { - assertionFailure = error; - throw error; - } - }, sink), + admitReferenceEntry( + witness, + function* (holder) { + recorded = yield* readAll(holder); + try { + expect( + recorded.some( + (event) => event.type === "yield" && event.description.name === ROOT_IMPORT, + ), + ).toBe(false); + } catch (error) { + assertionFailure = error; + throw error; + } + }, + sink, + ), ); } catch (error) { caught = error; @@ -417,14 +427,22 @@ describe("REPL execution: submitting one entry", () => { const invocations = yield* readdir(failed); expect(invocations).toHaveLength(1); const invocation = join(failed, invocations[0]); - expect(yield* readdir(invocation)).toEqual(["root-1.jsonl"]); + expect((yield* readdir(invocation)).sort()).toEqual(["root-1.case.json", "root-1.jsonl"]); + expect(JSON.parse(yield* readTextFile(join(invocation, "root-1.case.json")))).toEqual({ + owner: OWNER, + suite: SUBMIT_SUITE, + name: witness, + kind: "root", + ordinal: 1, + source: "packages/cli/tests/fixtures/repl/entry.md", + }); const journal = join(invocation, "root-1.jsonl"); expect(yield* readRecords(journal)).toEqual(entry.events); expect(lines).toHaveLength(1); expect(lines[0]).toContain(`journal saved: ${journal} (root 1 `); expect(lines[0]).toContain("packages/cli/tests/fixtures/repl/entry.md)"); - yield* atArtifactRoot(passed, admitReferenceEntry(undefined, sink)); + yield* atArtifactRoot(passed, admitReferenceEntry(witness, undefined, sink)); expect(yield* exists(passed)).toBe(false); const beforeAdmission = new Error("pre-admission failure"); @@ -432,10 +450,14 @@ describe("REPL execution: submitting one entry", () => { try { yield* atArtifactRoot( empty, - captureReferenceEntry(function* (holder) { - expect(yield* readAll(holder)).toEqual([]); - throw beforeAdmission; - }, sink), + captureReferenceEntry( + witness, + function* (holder) { + expect(yield* readAll(holder)).toEqual([]); + throw beforeAdmission; + }, + sink, + ), ); } catch (error) { emptyFailure = error; diff --git a/packages/core/tests/streaming-emission.test.ts b/packages/core/tests/streaming-emission.test.ts index c5bc48267..826e4fc9b 100644 --- a/packages/core/tests/streaming-emission.test.ts +++ b/packages/core/tests/streaming-emission.test.ts @@ -6,16 +6,15 @@ */ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { withFailureJournal } from "@executablemd/testing"; import { API } from "@executablemd/runtime"; import { useTempDirectory } from "@executablemd/test-support/temp"; -import { exists, readdir } from "@effectionx/fs"; -import { scoped } from "effection"; +import { exists, readdir, readTextFile } from "@effectionx/fs"; +import { ensure, scoped, spawn, suspend, withResolvers } from "effection"; import type { Operation } from "effection"; import { join } from "node:path"; import process from "node:process"; import { Writable } from "node:stream"; -import { useTestDiagnostics } from "../../cli/src/test-diagnostics.ts"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import type { DeliverySink } from "../../cli/src/stdout-delivery.ts"; import { readRecords } from "../../cli/src/repl/journal-records.ts"; import { forEach } from "@effectionx/stream-helpers"; @@ -45,52 +44,63 @@ describe("Tier BC — Block ID counter", () => { const SIMPLE = "packages/core/tests/fixtures/streaming/simple.md"; const MULTI = "packages/core/tests/fixtures/streaming/multi-segment.md"; +const OWNER = "packages/core/tests/streaming-emission.test.ts"; +const SUITE = "Tier SE — Streaming emission"; + function runStreamingCase( + name: string, path: string, check: (chunks: string[], fullOutput: string) => void, sink: DeliverySink = process.stderr, ): Operation { - return scoped(function* () { - const diagnostics = yield* useTestDiagnostics(sink); - yield* withFailureJournal( - diagnostics.execution("root", path).journal(() => false), - function* (stream) { - const chunks: string[] = []; - const fullOutput = yield* scoped(function* () { - const execution = yield* execute({ path, stream }); - const output = yield* forEach(function* (chunk: string) { - chunks.push(chunk); - }, execution.output); - yield* execution; - return output; - }); - check(chunks, fullOutput); - }, - ); - }); + return captureTestJournal( + { owner: OWNER, suite: SUITE, name }, + path, + function* (stream) { + const chunks: string[] = []; + const fullOutput = yield* scoped(function* () { + const execution = yield* execute({ path, stream }); + const output = yield* forEach(function* (chunk: string) { + chunks.push(chunk); + }, execution.output); + yield* execution; + return output; + }); + check(chunks, fullOutput); + }, + { sink }, + ); } -describe("Tier SE — Streaming emission", () => { - it("SE1: segments emitted in document order via stream", () => - runStreamingCase(MULTI, (chunks, fullOutput) => { +describe(SUITE, () => { + const segments = "SE1: segments emitted in document order via stream"; + it(segments, () => + runStreamingCase(segments, MULTI, (chunks, fullOutput) => { expect(chunks.length).toBeGreaterThan(0); expect(fullOutput).toBe(chunks.join("")); - })); + }), + ); - it("SE10: no empty strings in output chunks", () => - runStreamingCase(SIMPLE, (chunks) => { + const nonempty = "SE10: no empty strings in output chunks"; + it(nonempty, () => + runStreamingCase(nonempty, SIMPLE, (chunks) => { for (const chunk of chunks) { expect(chunk.length).toBeGreaterThan(0); } - })); + }), + ); - it("SE9: output() inside durable workflow reaches stream consumer", () => - runStreamingCase(SIMPLE, (chunks) => { + const output = "SE9: output() inside durable workflow reaches stream consumer"; + it(output, () => + runStreamingCase(output, SIMPLE, (chunks) => { expect(chunks.length).toBeGreaterThan(0); expect(chunks.join("")).toContain("Hello"); - })); + }), + ); - it("saves the settled streaming journal only after a failing assertion", function* () { + const witness = + "saves a journal after an assertion fails and leaves a passing execution unwritten"; + it(witness, function* () { const directory = yield* useTempDirectory("xmd-streaming-journal-"); const failed = join(directory, "failed"); const passed = join(directory, "passed"); @@ -110,6 +120,7 @@ describe("Tier SE — Streaming emission", () => { }, }); yield* runStreamingCase( + witness, SIMPLE, function (chunks) { expect(chunks.join("")).toContain("Hello"); @@ -137,7 +148,20 @@ describe("Tier SE — Streaming emission", () => { const invocations = yield* readdir(failed); expect(invocations).toHaveLength(1); const directoryWithJournal = join(failed, invocations[0]); - expect(yield* readdir(directoryWithJournal)).toEqual(["root-1.jsonl"]); + expect((yield* readdir(directoryWithJournal)).sort()).toEqual([ + "root-1.case.json", + "root-1.jsonl", + ]); + expect(JSON.parse(yield* readTextFile(join(directoryWithJournal, "root-1.case.json")))).toEqual( + { + owner: OWNER, + suite: SUITE, + name: witness, + kind: "root", + ordinal: 1, + source: SIMPLE, + }, + ); const journal = join(directoryWithJournal, "root-1.jsonl"); expect(lines).toEqual([ `[xmd test] journal saved: ${journal} (root 1 ${SIMPLE}) @@ -150,4 +174,61 @@ describe("Tier SE — Streaming emission", () => { expect(yield* exists(passed)).toBe(false); expect(lines).toHaveLength(1); }); + const cancelled = "saves the streaming journal after cancellation joins teardown"; + it(cancelled, function* () { + const artifacts = join( + yield* useTempDirectory("xmd-streaming-cancellation-"), + ".xmd", + "test-artifacts", + ); + yield* API.Env.around({ + *env([name], next) { + return name === "XMD_TEST_ARTIFACTS" ? artifacts : yield* next(name); + }, + }); + const { resolve, operation } = withResolvers(); + const order: string[] = []; + const sink = new Writable({ + write(chunk, _encoding, done) { + order.push(String(chunk)); + done(); + }, + }); + const task = yield* spawn(() => + captureTestJournal( + { owner: OWNER, suite: SUITE, name: cancelled }, + SIMPLE, + function* (stream) { + const execution = yield* execute({ path: SIMPLE, stream }); + yield* forEach(function* (chunk: string) { + expect(chunk.length).toBeGreaterThan(0); + }, execution.output); + yield* execution; + yield* ensure(() => { + order.push("teardown"); + }); + resolve(); + yield* suspend(); + }, + { sink }, + ), + ); + yield* operation; + yield* task.halt(); + expect(order[0]).toBe("teardown"); + const invocations = yield* readdir(artifacts); + expect(invocations).toHaveLength(1); + const directory = join(artifacts, invocations[0]); + expect(JSON.parse(yield* readTextFile(join(directory, "root-1.case.json")))).toEqual({ + owner: OWNER, + suite: SUITE, + name: cancelled, + kind: "root", + ordinal: 1, + source: SIMPLE, + }); + const file = join(directory, "root-1.jsonl"); + expect(order[1]).toContain(file); + expect((yield* readRecords(file)).at(-1)).toMatchObject({ type: "close", coroutineId: "root" }); + }); }); diff --git a/packages/test-agent/tests/session-configuration.test.ts b/packages/test-agent/tests/session-configuration.test.ts index 93176d6e2..745b70a3a 100644 --- a/packages/test-agent/tests/session-configuration.test.ts +++ b/packages/test-agent/tests/session-configuration.test.ts @@ -9,7 +9,7 @@ import { agentIdentityComponents, installAgentComponents } from "@executablemd/a import { parseDurableEvent } from "@executablemd/durable-streams"; import type { InMemoryStream } from "@executablemd/durable-streams"; import { API } from "@executablemd/runtime"; -import { useTesting, withFailureJournal } from "@executablemd/testing"; +import { useTesting } from "@executablemd/testing"; import type { TestResult } from "@executablemd/testing"; import { exists, readdir, readTextFile, writeTextFile } from "@effectionx/fs"; import { Err, Ok, scoped } from "effection"; @@ -17,7 +17,7 @@ import type { Operation, Result } from "effection"; import * as path from "node:path"; import process from "node:process"; import { Writable } from "node:stream"; -import { useTestDiagnostics } from "../../cli/src/test-diagnostics.ts"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import type { DeliverySink } from "../../cli/src/stdout-delivery.ts"; import { installTestAgentComponents } from "../src/components.ts"; import { NativeSessionObserver } from "../src/controller.ts"; @@ -26,18 +26,16 @@ import { useCommand } from "./command.ts"; const DOC = path.resolve("packages/test-agent/src/SessionConfiguration.replay.md"); +const OWNER = "packages/test-agent/tests/session-configuration.test.ts"; +const SUITE = "Session configuration through TestAgent"; + function captureConfiguration( + name: string, doc: string, body: (stream: InMemoryStream) => Operation, sink: DeliverySink = process.stderr, ): Operation { - return scoped(function* () { - const diagnostics = yield* useTestDiagnostics(sink); - yield* withFailureJournal( - diagnostics.execution("root", doc).journal(() => false), - body, - ); - }); + return captureTestJournal({ owner: OWNER, suite: SUITE, name }, doc, body, { sink }); } /** A native session report stamped with milliseconds since the run began. */ @@ -130,141 +128,151 @@ function configurationSucceeded(run: { } } -describe( - "Session configuration through TestAgent", - { sanitizeOps: false, sanitizeResources: false }, - () => { - it("refuses unknown, unsupported and unavailable Session selections before consuming the first stage", function* () { - const doc = path.resolve("packages/test-agent/src/SessionConfiguration.refusals.md"); - yield* captureConfiguration(doc, function* (stream) { - const run = yield* runConfiguration(stream, cliBase(), doc); - configurationSucceeded(run); - expect(run.results.map((entry) => entry.status)).toEqual(["pass", "pass"]); - expect(new Set(run.sessions.map((report) => report.nativeSessionId)).size).toBe(2); - }); +describe(SUITE, { sanitizeOps: false, sanitizeResources: false }, () => { + const refusals = + "refuses unknown, unsupported and unavailable Session selections before consuming the first stage"; + it(refusals, function* () { + const doc = path.resolve("packages/test-agent/src/SessionConfiguration.refusals.md"); + yield* captureConfiguration(refusals, doc, function* (stream) { + const run = yield* runConfiguration(stream, cliBase(), doc); + configurationSucceeded(run); + expect(run.results.map((entry) => entry.status)).toEqual(["pass", "pass"]); + expect(new Set(run.sessions.map((report) => report.nativeSessionId)).size).toBe(2); }); + }); - it("retains named native identity, isolates Tests, and replays without a worker", function* () { - yield* captureConfiguration(DOC, function* (stream) { - const live = yield* runConfiguration(stream, cliBase(), DOC); - configurationSucceeded(live); - expect(live.results.map((entry) => entry.status)).toEqual(["pass", "pass"]); - const configuredReports = live.sessions.filter( - (report) => report.scenarioId === live.sessions[0]?.scenarioId, - ); - const independentReports = live.sessions.filter( - (report) => report.scenarioId !== live.sessions[0]?.scenarioId, - ); - expect(configuredReports.length).toBeGreaterThan(1); - expect(independentReports.length).toBe(1); - expect(new Set(configuredReports.map((report) => report.nativeSessionId)).size).toBe(1); - expect(independentReports[0]?.nativeSessionId).not.toBe( - configuredReports[0]?.nativeSessionId, - ); - const events = JSON.stringify(yield* stream.readAll()); - expect(events).toContain('"configuration":{"model":"fixture-review","effort":"deep"}'); - const appended = stream.appendCount; - const replay = yield* runConfiguration( - stream, - ["/nonexistent/xmd-configuration-must-not-spawn"], - DOC, - ); - configurationSucceeded(replay); - expect(replay.results.map((entry) => entry.status)).toEqual( - live.results.map((entry) => entry.status), - ); - expect(replay.sessions).toEqual([]); - expect(replay.output).toBe(live.output); - expect(stream.appendCount).toBe(appended); - }); + const replay = "retains named native identity, isolates Tests, and replays without a worker"; + it(replay, function* () { + yield* captureConfiguration(replay, DOC, function* (stream) { + const live = yield* runConfiguration(stream, cliBase(), DOC); + configurationSucceeded(live); + expect(live.results.map((entry) => entry.status)).toEqual(["pass", "pass"]); + const configuredReports = live.sessions.filter( + (report) => report.scenarioId === live.sessions[0]?.scenarioId, + ); + const independentReports = live.sessions.filter( + (report) => report.scenarioId !== live.sessions[0]?.scenarioId, + ); + expect(configuredReports.length).toBeGreaterThan(1); + expect(independentReports.length).toBe(1); + expect(new Set(configuredReports.map((report) => report.nativeSessionId)).size).toBe(1); + expect(independentReports[0]?.nativeSessionId).not.toBe( + configuredReports[0]?.nativeSessionId, + ); + const events = JSON.stringify(yield* stream.readAll()); + expect(events).toContain('"configuration":{"model":"fixture-review","effort":"deep"}'); + const appended = stream.appendCount; + const replay = yield* runConfiguration( + stream, + ["/nonexistent/xmd-configuration-must-not-spawn"], + DOC, + ); + configurationSucceeded(replay); + expect(replay.results.map((entry) => entry.status)).toEqual( + live.results.map((entry) => entry.status), + ); + expect(replay.sessions).toEqual([]); + expect(replay.output).toBe(live.output); + expect(stream.appendCount).toBe(appended); }); + }); - it("saves a journal after an assertion fails and leaves a passing execution unwritten", function* () { - const directory = yield* useTempDirectory("xmd-session-configuration-"); - const doc = path.join(directory, "journal-witness.md"); - const marker = "Configuration journal witness"; - yield* writeTextFile( - doc, - ` + const witness = + "saves a journal after an assertion fails and leaves a passing execution unwritten"; + it(witness, function* () { + const directory = yield* useTempDirectory("xmd-session-configuration-"); + const doc = path.join(directory, "journal-witness.md"); + const marker = "Configuration journal witness"; + yield* writeTextFile( + doc, + ` ${marker} `, - ); - const failureRoot = path.join(directory, "failed"); - const successRoot = path.join(directory, "passed"); - const failure = new Error("post-settlement assertion failed"); - - function* runWitness( - artifacts: string, - assert: () => void, - ): Operation<{ outcome: Result; stderr: string }> { - return yield* scoped(function* () { - let stderr = ""; - const sink = new Writable({ - write(chunk, _encoding, callback) { - stderr += String(chunk); - callback(); - }, - }); - yield* API.Env.around({ - *env([name], next) { - return name === "XMD_TEST_ARTIFACTS" ? artifacts : yield* next(name); - }, - }); + ); + const failureRoot = path.join(directory, "failed"); + const successRoot = path.join(directory, "passed"); + const failure = new Error("post-settlement assertion failed"); - try { - yield* captureConfiguration( - doc, - function* (stream) { - const run = yield* runConfiguration(stream, [], doc); - configurationSucceeded(run); - expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); - expect(stream.appendCount).toBeGreaterThan(0); - assert(); - }, - sink, - ); - } catch (error) { - if (!(error instanceof Error)) { - throw error; - } - return { outcome: Err(error), stderr }; - } - return { outcome: Ok(), stderr }; + function* runWitness( + artifacts: string, + assert: () => void, + ): Operation<{ outcome: Result; stderr: string }> { + return yield* scoped(function* () { + let stderr = ""; + const sink = new Writable({ + write(chunk, _encoding, callback) { + stderr += String(chunk); + callback(); + }, + }); + yield* API.Env.around({ + *env([name], next) { + return name === "XMD_TEST_ARTIFACTS" ? artifacts : yield* next(name); + }, }); - } - const failed = yield* runWitness(failureRoot, () => { - throw failure; - }); - expect(failed.outcome.ok ? undefined : failed.outcome.error).toBe(failure); - const invocations = yield* readdir(failureRoot); - expect(invocations.length).toBe(1); - const invocation = path.join(failureRoot, invocations[0]); - expect(yield* readdir(invocation)).toEqual(["root-1.jsonl"]); - const journal = path.join(invocation, "root-1.jsonl"); - expect(failed.stderr).toBe(`[xmd test] journal saved: ${journal} (root 1 ${doc}) -`); - const jsonl = yield* readTextFile(journal); - const events = jsonl - .trimEnd() - .split("\n") - .map((line) => { - const event = parseDurableEvent(line); - if (!event.ok) { - throw event.error; + try { + yield* captureConfiguration( + witness, + doc, + function* (stream) { + const run = yield* runConfiguration(stream, [], doc); + configurationSucceeded(run); + expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); + expect(stream.appendCount).toBeGreaterThan(0); + assert(); + }, + sink, + ); + } catch (error) { + if (!(error instanceof Error)) { + throw error; } - return event.value; - }); - expect(JSON.stringify(events)).toContain(marker); + return { outcome: Err(error), stderr }; + } + return { outcome: Ok(), stderr }; + }); + } - expect(yield* runWitness(successRoot, () => undefined)).toEqual({ - outcome: Ok(), - stderr: "", + const failed = yield* runWitness(failureRoot, () => { + throw failure; + }); + expect(failed.outcome.ok ? undefined : failed.outcome.error).toBe(failure); + const invocations = yield* readdir(failureRoot); + expect(invocations.length).toBe(1); + const invocation = path.join(failureRoot, invocations[0]); + expect((yield* readdir(invocation)).sort()).toEqual(["root-1.case.json", "root-1.jsonl"]); + expect(JSON.parse(yield* readTextFile(path.join(invocation, "root-1.case.json")))).toEqual({ + owner: OWNER, + suite: SUITE, + name: witness, + kind: "root", + ordinal: 1, + source: doc, + }); + const journal = path.join(invocation, "root-1.jsonl"); + expect(failed.stderr).toBe(`[xmd test] journal saved: ${journal} (root 1 ${doc}) +`); + const jsonl = yield* readTextFile(journal); + const events = jsonl + .trimEnd() + .split("\n") + .map((line) => { + const event = parseDurableEvent(line); + if (!event.ok) { + throw event.error; + } + return event.value; }); - expect(yield* exists(successRoot)).toBe(false); + expect(JSON.stringify(events)).toContain(marker); + + expect(yield* runWitness(successRoot, () => undefined)).toEqual({ + outcome: Ok(), + stderr: "", }); - }, -); + expect(yield* exists(successRoot)).toBe(false); + }); +}); diff --git a/packages/test-support/failure-journal.ts b/packages/test-support/failure-journal.ts new file mode 100644 index 000000000..e66e4d84f --- /dev/null +++ b/packages/test-support/failure-journal.ts @@ -0,0 +1,47 @@ +import { scoped } from "effection"; +import type { Operation } from "effection"; +import type { DurableEvent, InMemoryStream } from "@executablemd/durable-streams"; +import { withFailureJournal } from "@executablemd/testing"; +import process from "node:process"; +import { useTestDiagnostics } from "../cli/src/test-diagnostics.ts"; +import type { JournalCase, TestDiagnostics } from "../cli/src/test-diagnostics.ts"; +import type { DeliverySink } from "../cli/src/stdout-delivery.ts"; + +/** + * Protect a repository test's fresh guarded execution and its assertions. + * Pass the outer case's declared name and repository-relative file as the + * label. A saved journal has a sibling .case.json with that label and the + * execution's kind, ordinal and displayed source. The JSONL carries the + * original durable records. + * + * A host with detached children passes its diagnostics to their journal + * factory. An owner whose stream holds more than the admitted execution can + * select the owned events for persistence after teardown. + */ +export function captureTestJournal( + testCase: JournalCase, + source: string, + body: (stream: InMemoryStream, diagnostics: TestDiagnostics) => Operation, + options: { + sink?: DeliverySink; + failed?: (value: T) => boolean; + selectEvents?: (events: readonly DurableEvent[]) => readonly DurableEvent[]; + } = {}, +): Operation { + return scoped(function* () { + const diagnostics = yield* useTestDiagnostics(options.sink ?? process.stderr, testCase); + const journal = diagnostics.execution("root", source).journal(options.failed ?? (() => false)); + return yield* withFailureJournal( + { + ...journal, + *save(events) { + const selected = options.selectEvents?.(events) ?? events; + if (selected.length > 0) { + yield* journal.save(selected); + } + }, + }, + (stream) => body(stream, diagnostics), + ); + }); +} diff --git a/packages/testing/tests/execution-harness.test.ts b/packages/testing/tests/execution-harness.test.ts index c9ca9af57..2f159900b 100644 --- a/packages/testing/tests/execution-harness.test.ts +++ b/packages/testing/tests/execution-harness.test.ts @@ -15,15 +15,14 @@ import type { Operation, Result } from "effection"; import { forEach } from "@effectionx/stream-helpers"; import { InMemoryStream } from "@executablemd/durable-streams"; import { API } from "@executablemd/runtime"; -import { readdir } from "@effectionx/fs"; +import { readdir, readTextFile } from "@effectionx/fs"; import { useTempDirectory } from "@executablemd/test-support/temp"; import { join } from "node:path"; import process from "node:process"; import { Writable } from "node:stream"; -import { useTestDiagnostics } from "../../cli/src/test-diagnostics.ts"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import type { DeliverySink } from "../../cli/src/stdout-delivery.ts"; import { readRecords } from "../../cli/src/repl/journal-records.ts"; -import { withFailureJournal } from "../src/failure-journal.ts"; import { useStubFs } from "@executablemd/runtime/test"; import { Component, @@ -103,30 +102,33 @@ function* runHarness( }); } +const OWNER = "packages/testing/tests/execution-harness.test.ts"; +const RUN_SUITE = ''; + function captureHarness( + name: string, files: Record, check: (run: HarnessRun) => void, sink: DeliverySink = process.stderr, onTeardown?: StubHostOptions["onTeardown"], ): Operation { - return scoped(function* () { - const diagnostics = yield* useTestDiagnostics(sink); - yield* withFailureJournal( - diagnostics.execution("root", "README.md").journal(() => false), - function* (stream) { - check( - yield* runHarness(files, { - stream, - childJournal: (source) => - diagnostics - .execution("child", source) - .journal(({ outcome }) => outcome.kind === "settled" && !outcome.result.ok), - ...(onTeardown === undefined ? {} : { onTeardown }), - }), - ); - }, - ); - }); + return captureTestJournal( + { owner: OWNER, suite: RUN_SUITE, name }, + "README.md", + function* (stream, diagnostics) { + check( + yield* runHarness(files, { + stream, + childJournal: (source) => + diagnostics + .execution("child", source) + .journal(({ outcome }) => outcome.kind === "settled" && !outcome.result.ok), + ...(onTeardown === undefined ? {} : { onTeardown }), + }), + ); + }, + { sink }, + ); } /** What ended a run that produced no test result. */ @@ -160,9 +162,11 @@ const CHILD_WITH_PROPS = doc( "hello {props.who}", ); -describe('', () => { - it("runs a referenced document as a root, with root props and text return", function* () { +describe(RUN_SUITE, () => { + const referenced = "runs a referenced document as a root, with root props and text return"; + it(referenced, function* () { yield* captureHarness( + referenced, { "README.md": doc( '', @@ -184,7 +188,9 @@ describe('', () => { ); }); - it("attributes bound child failures and post-run root failures to joined, separate executions", function* () { + const witnessCase = + "attributes bound child failures and post-run root failures to joined, separate executions"; + it(witnessCase, function* () { const artifacts = join(yield* useTempDirectory("xmd-nested-journals-"), "journals"); yield* API.Env.around({ *env([name], next) { @@ -204,6 +210,7 @@ describe('', () => { let caught: unknown; try { yield* captureHarness( + witnessCase, { "README.md": doc( '', @@ -238,11 +245,22 @@ describe('', () => { expect(order[0]).toBe("child teardown"); const invocations = yield* readdir(artifacts); - const invocation = invocations.find((name) => - order[1]?.includes(join(artifacts, name, "child-1.jsonl")), - ); + const attribution = { owner: OWNER, suite: RUN_SUITE, name: witnessCase, ordinal: 1 }; + const childCase = { ...attribution, kind: "child", source: target }; + let invocation: string | undefined; + for (const candidate of invocations) { + const file = join(artifacts, candidate, "child-1.case.json"); + if ((yield* readdir(join(artifacts, candidate))).includes("child-1.case.json")) { + const metadata = JSON.parse(yield* readTextFile(file)); + if (metadata.source === target) { + expect(metadata).toEqual(childCase); + invocation = candidate; + break; + } + } + } if (invocation === undefined) { - throw new Error(`no child artifact for ${target}: ${order.join("")}`); + throw new Error(`no child artifact for ${target}`); } const directory = join(artifacts, invocation); const child = join(directory, "child-1.jsonl"); @@ -258,13 +276,20 @@ describe('', () => { : []), ]); expect((yield* readdir(directory)).sort()).toEqual( - failRoot ? ["child-1.jsonl", "root-1.jsonl"] : ["child-1.jsonl"], + failRoot + ? ["child-1.case.json", "child-1.jsonl", "root-1.case.json", "root-1.jsonl"] + : ["child-1.case.json", "child-1.jsonl"], ); const childEvents = yield* readRecords(child); const isExec = (event: (typeof childEvents)[number]) => event.type === "yield" && event.description.type === "exec"; expect(childEvents.some(isExec)).toBe(true); if (failRoot) { + expect(JSON.parse(yield* readTextFile(join(directory, "root-1.case.json")))).toEqual({ + ...attribution, + kind: "root", + source: "README.md", + }); const rootEvents = yield* readRecords(root); expect(rootEvents.some(isExec)).toBe(false); expect(rootEvents.at(-1)).toMatchObject({ type: "close", coroutineId: "root" }); @@ -312,7 +337,8 @@ describe('', () => { expect(only(run).status).toBe("pass"); }); - it("runs inline source under the identity, with no authored file", function* () { + const inline = "runs inline source under the identity, with no authored file"; + it(inline, function* () { const files = { "README.md": "" }; files["README.md"] = doc( '', @@ -323,7 +349,7 @@ describe('', () => { "", "", ); - yield* captureHarness(files, (run) => { + yield* captureHarness(inline, files, (run) => { expect(only(run).status).toBe("pass"); // The identity the child reports is the inline one, and the harness named // no file for it to have come from. That production takes the same path is From 41946db77aa997a364eefc0815259d022bb341e5 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 13:30:27 -0500 Subject: [PATCH 02/78] test: capture failure journals for Testing document cases --- packages/testing/tests/assert-throws.test.ts | 141 +++++----- packages/testing/tests/assertions.test.ts | 263 ++++++++++-------- .../testing/tests/boundary-contract.test.ts | 177 ++++++------ packages/testing/tests/helpers.ts | 23 ++ packages/testing/tests/test-component.test.ts | 250 +++++++++-------- .../testing/tests/testing-boundary.test.ts | 45 +-- packages/testing/tests/testing-mode.test.ts | 251 +++++++++-------- packages/testing/tests/use-testing.test.ts | 67 ++++- 8 files changed, 693 insertions(+), 524 deletions(-) diff --git a/packages/testing/tests/assert-throws.test.ts b/packages/testing/tests/assert-throws.test.ts index 33a66e24c..ebe44fc56 100644 --- a/packages/testing/tests/assert-throws.test.ts +++ b/packages/testing/tests/assert-throws.test.ts @@ -1,11 +1,13 @@ -import { describe, it } from "@executablemd/test-support/bdd"; +import { describe } from "@executablemd/test-support/bdd"; import { scoped } from "effection"; import { expect } from "@executablemd/test-support/expect"; import { AssertionError } from "node:assert/strict"; import { Component } from "@executablemd/core"; import type { ComponentElement } from "@executablemd/core"; import { createTestHandlers } from "../src/handlers.ts"; -import { failureOf, runDoc } from "./helpers.ts"; +import { documentCases, failureOf } from "./helpers.ts"; + +const documentCase = documentCases("packages/testing/tests/assert-throws.test.ts"); const STRICT = [ "---", @@ -28,43 +30,43 @@ function inTest(body: string): Record { } describe("", () => { - it("passes when the body raises an error matching a substring", function* () { - const run = yield* runDoc( + documentCase("passes when the body raises an error matching a substring", function* (runFresh) { + const run = yield* runFresh( inTest(''), ); expect(run.completion.ok).toBe(true); expect(run.results[0]?.status).toBe("pass"); }); - it("passes when the body raises an error matching a RegExp", function* () { - const run = yield* runDoc( + documentCase("passes when the body raises an error matching a RegExp", function* (runFresh) { + const run = yield* runFresh( inTest(''), ); expect(run.results[0]?.status).toBe("pass"); }); - it("fails when the body raises no error", function* () { - const run = yield* runDoc( + documentCase("fails when the body raises no error", function* (runFresh) { + const run = yield* runFresh( inTest(''), ); expect(run.results[0]?.status).toBe("fail"); }); - it("fails when the raised error does not match", function* () { - const run = yield* runDoc( + documentCase("fails when the raised error does not match", function* (runFresh) { + const run = yield* runFresh( inTest(''), ); expect(run.results[0]?.status).toBe("fail"); }); - it("rejects a missing message prop", function* () { - const run = yield* runDoc(inTest('')); + documentCase("rejects a missing message prop", function* (runFresh) { + const run = yield* runFresh(inTest('')); expect(run.results[0]?.status).toBe("fail"); expect(run.output).toContain('requires a "message"'); }); - it("rejects an unknown prop", function* () { - const run = yield* runDoc( + documentCase("rejects an unknown prop", function* (runFresh) { + const run = yield* runFresh( inTest(''), ); expect(run.results[0]?.status).toBe("fail"); @@ -74,8 +76,8 @@ describe("", () => { expect(run.results[0]?.error?.message).toContain("must NOT have additional properties"); }); - it("rejects an expression-valued as", function* () { - const run = yield* runDoc( + documentCase("rejects an expression-valued as", function* (runFresh) { + const run = yield* runFresh( inTest(''), ); expect(run.results[0]?.status).toBe("fail"); @@ -83,24 +85,24 @@ describe("", () => { expect(run.results[0]?.error?.message).toContain("must be a string literal"); }); - it("rejects an invalid as identifier", function* () { - const run = yield* runDoc( + documentCase("rejects an invalid as identifier", function* (runFresh) { + const run = yield* runFresh( inTest(''), ); expect(run.results[0]?.status).toBe("fail"); expect(run.output).toContain("identifier"); }); - it("rejects a message that evaluates to an unsupported type", function* () { - const run = yield* runDoc( + documentCase("rejects a message that evaluates to an unsupported type", function* (runFresh) { + const run = yield* runFresh( inTest(''), ); expect(run.results[0]?.status).toBe("fail"); expect(run.results[0]?.error?.message).toContain("string or a RegExp"); }); - it("binds the complete caught error (incl. cause) via as", function* () { - const run = yield* runDoc( + documentCase("binds the complete caught error (incl. cause) via as", function* (runFresh) { + const run = yield* runFresh( inTest( [ '', @@ -112,35 +114,41 @@ describe("", () => { expect(run.results.every((r) => r.status === "pass")).toBe(true); }); - it("re-propagates a non-raise throw (a failing assertion in the body)", function* () { - const run = yield* runDoc( - inTest( - '', - ), - ); - expect(run.results[0]?.status).toBe("fail"); - expect(run.results[0]?.error).toMatchObject({ - kind: "assertion", - actual: "1", - expected: "2", - }); - expect(run.output).toContain("**AssertEquals** failed"); - expect(run.output).not.toContain("**AssertThrows** failed"); - }); - - it("stops expanding body children after the first raised error, rendering nothing", function* () { - const run = yield* runDoc({ - "Strict.md": STRICT, - "README.md": - 'SHOULD-NOT-APPEAR\n', - }); - expect(run.completion.ok).toBe(true); - expect(run.output).not.toContain("SHOULD-NOT-APPEAR"); - expect(run.output).not.toContain("must be number"); - }); - - it("swallows silently outside a during regular execution", function* () { - const run = yield* runDoc({ + documentCase( + "re-propagates a non-raise throw (a failing assertion in the body)", + function* (runFresh) { + const run = yield* runFresh( + inTest( + '', + ), + ); + expect(run.results[0]?.status).toBe("fail"); + expect(run.results[0]?.error).toMatchObject({ + kind: "assertion", + actual: "1", + expected: "2", + }); + expect(run.output).toContain("**AssertEquals** failed"); + expect(run.output).not.toContain("**AssertThrows** failed"); + }, + ); + + documentCase( + "stops expanding body children after the first raised error, rendering nothing", + function* (runFresh) { + const run = yield* runFresh({ + "Strict.md": STRICT, + "README.md": + 'SHOULD-NOT-APPEAR\n', + }); + expect(run.completion.ok).toBe(true); + expect(run.output).not.toContain("SHOULD-NOT-APPEAR"); + expect(run.output).not.toContain("must be number"); + }, + ); + + documentCase("swallows silently outside a during regular execution", function* (runFresh) { + const run = yield* runFresh({ "Strict.md": STRICT, "README.md": 'before\n\nafter\n', @@ -155,8 +163,8 @@ describe("", () => { // to bind, and no other channel preserves a durable rendered segment — so a // passing renders nothing, even with --verbose. Failure // behavior is unchanged, which the cases above pin. - it("emits no pass diagnostic, even with verbose", function* () { - const run = yield* runDoc( + documentCase("emits no pass diagnostic, even with verbose", function* (runFresh) { + const run = yield* runFresh( { "Strict.md": STRICT, "README.md": '\n', @@ -167,16 +175,19 @@ describe("", () => { expect(run.output).not.toContain("**AssertThrows** passed"); }); - it("aborts the document outside a when no error is raised, with a visible diagnostic", function* () { - const run = yield* runDoc( - { - "Strict.md": STRICT, - "README.md": 'before\n\nnever\n', - }, - { verbose: true }, - ); - expect(failureOf(run)).toBeInstanceOf(AssertionError); - expect(run.output).toContain("**AssertThrows** failed"); - expect(run.output).not.toContain("never"); - }); + documentCase( + "aborts the document outside a when no error is raised, with a visible diagnostic", + function* (runFresh) { + const run = yield* runFresh( + { + "Strict.md": STRICT, + "README.md": 'before\n\nnever\n', + }, + { verbose: true }, + ); + expect(failureOf(run)).toBeInstanceOf(AssertionError); + expect(run.output).toContain("**AssertThrows** failed"); + expect(run.output).not.toContain("never"); + }, + ); }); diff --git a/packages/testing/tests/assertions.test.ts b/packages/testing/tests/assertions.test.ts index 692a8e19b..36df03a15 100644 --- a/packages/testing/tests/assertions.test.ts +++ b/packages/testing/tests/assertions.test.ts @@ -3,12 +3,14 @@ import { Component, useTempFileCompiler } from "@executablemd/core"; import { expect } from "@executablemd/test-support/expect"; import { AssertionError } from "node:assert/strict"; import { TestFailureError } from "../src/test-api.ts"; -import { failureOf, runDoc } from "./helpers.ts"; +import { documentCases, failureOf } from "./helpers.ts"; + +const documentCase = documentCases("packages/testing/tests/assertions.test.ts"); describe("assertion components", () => { beforeAll(() => useTempFileCompiler()); - it("passing assertions in testing mode emit diagnostics", function* () { - const run = yield* runDoc( + documentCase("passing assertions in testing mode emit diagnostics", function* (runFresh) { + const run = yield* runFresh( { "README.md": '\n', @@ -20,7 +22,7 @@ describe("assertion components", () => { expect(run.results).toEqual([{ status: "pass", name: "eq", location: "README.md:1:10" }]); }); - it("a validation diagnostic is observed once and rendered once", function* () { + documentCase("a validation diagnostic is observed once and rendered once", function* (runFresh) { const observed: string[] = []; yield* Component.around({ *raise([error], next) { @@ -30,7 +32,7 @@ describe("assertion components", () => { }); // Written in a region that prints: rendering the diagnostic once is half of // what this pins, and reading it needs the document to render it. - const run = yield* runDoc({ + const run = yield* runFresh({ "README.md": "\n\n\n", }); @@ -42,18 +44,21 @@ describe("assertion components", () => { expect(run.output.match(/must NOT have additional properties/g)).toHaveLength(1); }); - it("assertions outside a test pass silently during regular execution", function* () { - const run = yield* runDoc({ - "README.md": "before\n\nafter\n", - }); - expect(run.completion.ok).toBe(true); - expect(run.output).not.toContain("AssertEquals"); - expect(run.output).toContain("before"); - expect(run.output).toContain("after"); - }); + documentCase( + "assertions outside a test pass silently during regular execution", + function* (runFresh) { + const run = yield* runFresh({ + "README.md": "before\n\nafter\n", + }); + expect(run.completion.ok).toBe(true); + expect(run.output).not.toContain("AssertEquals"); + expect(run.output).toContain("before"); + expect(run.output).toContain("after"); + }, + ); - it("assertions outside a test emit diagnostics with verbose", function* () { - const run = yield* runDoc( + documentCase("assertions outside a test emit diagnostics with verbose", function* (runFresh) { + const run = yield* runFresh( { "README.md": "\n" }, { verbose: true }, ); @@ -61,8 +66,8 @@ describe("assertion components", () => { expect(run.output).toContain("**AssertEquals** passed"); }); - it("a failed assertion outside a test aborts the document", function* () { - const run = yield* runDoc({ + documentCase("a failed assertion outside a test aborts the document", function* (runFresh) { + const run = yield* runFresh({ "README.md": "before\n\nnever\n", }); const error = failureOf(run); @@ -72,17 +77,20 @@ describe("assertion components", () => { expect(run.output).not.toContain("AssertEquals"); }); - it("a failed assertion outside a test keeps its diagnostic with verbose", function* () { - const run = yield* runDoc( - { "README.md": "before\n\nnever\n" }, - { verbose: true }, - ); - expect(failureOf(run)).toBeInstanceOf(AssertionError); - expect(run.output).toContain("**AssertEquals** failed"); - expect(run.output).toContain("before"); - }); + documentCase( + "a failed assertion outside a test keeps its diagnostic with verbose", + function* (runFresh) { + const run = yield* runFresh( + { "README.md": "before\n\nnever\n" }, + { verbose: true }, + ); + expect(failureOf(run)).toBeInstanceOf(AssertionError); + expect(run.output).toContain("**AssertEquals** failed"); + expect(run.output).toContain("before"); + }, + ); - it("expected children behave like trimming", function* () { + documentCase("expected children behave like trimming", function* (runFresh) { const doc = [ "", '', @@ -94,45 +102,45 @@ describe("assertion components", () => { "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.completion.ok).toBe(true); expect(run.results.map((r) => r.status)).toEqual(["pass"]); }); - it("rejects both expected prop and expected children", function* () { + documentCase("rejects both expected prop and expected children", function* (runFresh) { const doc = "1\n"; - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(failureOf(run)).toBeInstanceOf(TestFailureError); expect(run.results[0]?.status).toBe("fail"); expect(run.results[0]?.error?.kind).toBe("error"); expect(run.results[0]?.error?.message).toContain("not both"); }); - it("rejects expected children on unary and numeric assertions", function* () { + documentCase("rejects expected children on unary and numeric assertions", function* (runFresh) { const doc = "x\n"; - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results[0]?.error?.message).toContain("expected children"); }); - it("match assertions require a real RegExp", function* () { + documentCase("match assertions require a real RegExp", function* (runFresh) { const doc = '\n'; - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results[0]?.status).toBe("fail"); expect(run.results[0]?.error?.message).toContain("RegExp"); }); - it("match assertions accept a RegExp expression", function* () { + documentCase("match assertions accept a RegExp expression", function* (runFresh) { const doc = '\n'; - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.completion.ok).toBe(true); expect(run.results[0]?.status).toBe("pass"); }); - it("unknown props are rejected per kind", function* () { + documentCase("unknown props are rejected per kind", function* (runFresh) { const doc = "\n"; - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); // `actual` is a capture for the binary kinds but not for unary-truthy, so // never declares it and the schema rejects it like any other // undeclared prop. @@ -140,13 +148,13 @@ describe("assertion components", () => { expect(run.results[0]?.error?.message).toContain("must NOT have additional properties"); }); - it("missing required props are rejected", function* () { + documentCase("missing required props are rejected", function* (runFresh) { const doc = "\n"; - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results[0]?.error?.message).toContain('"expected"'); }); - it("assertion expressions see live bindings from eval blocks", function* () { + documentCase("assertion expressions see live bindings from eval blocks", function* (runFresh) { const doc = [ "", "```js eval", @@ -156,28 +164,31 @@ describe("assertion components", () => { "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.completion.ok).toBe(true); expect(run.results[0]?.status).toBe("pass"); }); - it("assertion expressions see caller bindings through projection", function* () { - const doc = [ - "```js eval", - 'const fromCaller = "outer-value";', - "```", - "", - '', - "", - "", - ].join("\n"); - const wrap = "projected: \n"; - const run = yield* runDoc({ "README.md": doc, "components/Wrap.md": wrap }); - expect(run.completion.ok).toBe(true); - expect(run.results[0]?.status).toBe("pass"); - }); + documentCase( + "assertion expressions see caller bindings through projection", + function* (runFresh) { + const doc = [ + "```js eval", + 'const fromCaller = "outer-value";', + "```", + "", + '', + "", + "", + ].join("\n"); + const wrap = "projected: \n"; + const run = yield* runFresh({ "README.md": doc, "components/Wrap.md": wrap }); + expect(run.completion.ok).toBe(true); + expect(run.results[0]?.status).toBe("pass"); + }, + ); - it("formatter-visible toJSON/toString cannot change the outcome", function* () { + documentCase("formatter-visible toJSON/toString cannot change the outcome", function* (runFresh) { const doc = [ "", "```js eval", @@ -187,13 +198,13 @@ describe("assertion components", () => { "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.completion.ok).toBe(true); expect(run.results[0]?.status).toBe("pass"); expect(run.output).toContain("unformattable"); }); - it("a non-string msg is rejected by type check, never formatted", function* () { + documentCase("a non-string msg is rejected by type check, never formatted", function* (runFresh) { // If msg were formatted before the assertion, the hostile toJSON or // toString would throw and replace the validation outcome. const doc = [ @@ -202,7 +213,7 @@ describe("assertion components", () => { "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(failureOf(run)).toBeInstanceOf(TestFailureError); expect(run.results[0]?.status).toBe("fail"); expect(run.results[0]?.error?.kind).toBe("error"); @@ -211,42 +222,48 @@ describe("assertion components", () => { expect(run.results[0]?.error?.message).not.toContain("hostile-string"); }); - it("a throwing getter read at format time cannot change the outcome", function* () { - const doc = [ - "", - "", - "", - "", - ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); - expect(run.completion.ok).toBe(true); - expect(run.results[0]?.status).toBe("pass"); - expect(run.output).toContain("[object Object]"); - }); + documentCase( + "a throwing getter read at format time cannot change the outcome", + function* (runFresh) { + const doc = [ + "", + "", + "", + "", + ].join("\n"); + const run = yield* runFresh({ "README.md": doc }); + expect(run.completion.ok).toBe(true); + expect(run.results[0]?.status).toBe("pass"); + expect(run.output).toContain("[object Object]"); + }, + ); // §5b: `as` and `slot` are the engine's, consumed before validation, so an // assertion accepts them like any other component rather than rejecting them // from a hand-written allowed-list. - it("accepts `as` on a value assertion, binding its diagnostic text", function* () { - const doc = [ - "", - '', - '', - '', - "", - "", - "", - ].join("\n"); + documentCase( + "accepts `as` on a value assertion, binding its diagnostic text", + function* (runFresh) { + const doc = [ + "", + '', + '', + '', + "", + "", + "", + ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); - expect(run.results[0]?.status).toBe("pass"); - }); + expect(run.results[0]?.status).toBe("pass"); + }, + ); // A registration is a default, so a repository file of the same name wins. // The local component declares a props schema: a markdown component without // one accepts no props at all, and would be rejected before it could answer. - it("a repository AssertEquals overrides the registered default", function* () { + documentCase("a repository AssertEquals overrides the registered default", function* (runFresh) { const local = [ "---", "props:", @@ -260,7 +277,7 @@ describe("assertion components", () => { "", ].join("\n"); - const run = yield* runDoc({ + const run = yield* runFresh({ "README.md": [ "", '', @@ -277,41 +294,49 @@ describe("assertion components", () => { // Parity with the handler this replaced: an operand that throws is reported // by the assertion that owns it, not as the invocation's own failure. - it("reports an operand expression that throws as its own diagnostic", function* () { - const doc = [ - "", - '', - ' { throw new Error("operand exploded"); })()} expected={1} />', - "", - "", - "", - ].join("\n"); + documentCase( + "reports an operand expression that throws as its own diagnostic", + function* (runFresh) { + const doc = [ + "", + '', + ' { throw new Error("operand exploded"); })()} expected={1} />', + "", + "", + "", + ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); - expect(run.results[0]?.status).toBe("fail"); - expect(run.results[0]?.error?.message).toContain('failed to evaluate the "actual" expression'); - expect(run.results[0]?.error?.message).toContain("operand exploded"); - }); + expect(run.results[0]?.status).toBe("fail"); + expect(run.results[0]?.error?.message).toContain( + 'failed to evaluate the "actual" expression', + ); + expect(run.results[0]?.error?.message).toContain("operand exploded"); + }, + ); // `undefined` cannot survive the JSON gate, so before captures this could not // be written at all — the engine rejected the prop before the assertion ran. - it(" fails on undefined rather than rejecting the prop", function* () { - const doc = [ - "", - '', - "", - "", - "", - "", - ].join("\n"); + documentCase( + " fails on undefined rather than rejecting the prop", + function* (runFresh) { + const doc = [ + "", + '', + "", + "", + "", + "", + ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); - // The assertion's own comparison failed — not the engine refusing the prop, - // which is what happened before `actual` became a capture. - expect(run.results[0]?.status).toBe("fail"); - expect(run.results[0]?.error?.kind).toBe("assertion"); - expect(run.results[0]?.error?.message).not.toContain("non-serializable"); - }); + // The assertion's own comparison failed — not the engine refusing the prop, + // which is what happened before `actual` became a capture. + expect(run.results[0]?.status).toBe("fail"); + expect(run.results[0]?.error?.kind).toBe("assertion"); + expect(run.results[0]?.error?.message).not.toContain("non-serializable"); + }, + ); }); diff --git a/packages/testing/tests/boundary-contract.test.ts b/packages/testing/tests/boundary-contract.test.ts index 789c406ea..b06ad186f 100644 --- a/packages/testing/tests/boundary-contract.test.ts +++ b/packages/testing/tests/boundary-contract.test.ts @@ -7,7 +7,9 @@ import { describe, it, beforeAll } from "@executablemd/test-support/bdd"; import { useTempFileCompiler } from "@executablemd/core"; import { expect } from "@executablemd/test-support/expect"; -import { runDoc } from "./helpers.ts"; +import { documentCases } from "./helpers.ts"; + +const documentCase = documentCases("packages/testing/tests/boundary-contract.test.ts"); describe("Tier TC — the boundary", () => { beforeAll(() => useTempFileCompiler()); @@ -16,33 +18,36 @@ describe("Tier TC — the boundary", () => { // that is ``'s job — so an error beside a test renders where it was // written and the boundary still reports. Projecting the body through // `content()` instead would abort the boundary and lose both. - it("TC1: an error beside a test renders inline, and the boundary still reports", function* () { - // The region prints, which is what makes "renders inline and the boundary - // still reports" a thing the document asked for. - const doc = [ - "", - "", - "", - "", - "", - '', - "", - "", - "", - "", - ].join("\n"); - - const run = yield* runDoc({ "README.md": doc }); - - // The stray error is rendered, not swallowed and not fatal… - expect(run.output).toContain("Failed to import component Missing"); - // …the test beside it still ran… - expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); - // …and the boundary still reported its outcome. - expect(run.boundaries).toEqual([{ tests: 1, failed: 0 }]); - }); - - it("TC2: text around a test is preserved in order", function* () { + documentCase( + "TC1: an error beside a test renders inline, and the boundary still reports", + function* (runFresh) { + // The region prints, which is what makes "renders inline and the boundary + // still reports" a thing the document asked for. + const doc = [ + "", + "", + "", + "", + "", + '', + "", + "", + "", + "", + ].join("\n"); + + const run = yield* runFresh({ "README.md": doc }); + + // The stray error is rendered, not swallowed and not fatal… + expect(run.output).toContain("Failed to import component Missing"); + // …the test beside it still ran… + expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); + // …and the boundary still reported its outcome. + expect(run.boundaries).toEqual([{ tests: 1, failed: 0 }]); + }, + ); + + documentCase("TC2: text around a test is preserved in order", function* (runFresh) { const doc = [ "", "", @@ -56,14 +61,14 @@ describe("Tier TC — the boundary", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.output.indexOf("BEFORE")).toBeGreaterThan(-1); expect(run.output.indexOf("AFTER")).toBeGreaterThan(run.output.indexOf("BEFORE")); }); - it("TC3: an empty boundary reports zero tests", function* () { - const run = yield* runDoc({ "README.md": "\n\nnothing here\n\n\n" }); + documentCase("TC3: an empty boundary reports zero tests", function* (runFresh) { + const run = yield* runFresh({ "README.md": "\n\nnothing here\n\n\n" }); expect(run.boundaries).toEqual([{ tests: 0, failed: 0 }]); }); @@ -74,33 +79,36 @@ describe("Tier TC — what a keeps when it fails", () => { // The behavior `content()` cannot express: a test that fails partway still // shows what it rendered up to that point, then its diagnostics. - it("TC4: output produced before a failure survives, and precedes the diagnostic", function* () { - const doc = [ - "", - '', - "", - "RENDERED FIRST", - "", - "", - "", - "NEVER REACHED", - "", - "", - "", - "", - ].join("\n"); - - const run = yield* runDoc({ "README.md": doc }); - - expect(run.results.map((entry) => entry.status)).toEqual(["fail"]); - expect(run.output).toContain("RENDERED FIRST"); - // The body stopped where it failed. - expect(run.output).not.toContain("NEVER REACHED"); - // The diagnostic follows what was rendered, rather than replacing it. - expect(run.output.indexOf("RENDERED FIRST")).toBeLessThan(run.output.indexOf("partial")); - }); - - it("TC5: exactly one result is recorded for a failing test", function* () { + documentCase( + "TC4: output produced before a failure survives, and precedes the diagnostic", + function* (runFresh) { + const doc = [ + "", + '', + "", + "RENDERED FIRST", + "", + "", + "", + "NEVER REACHED", + "", + "", + "", + "", + ].join("\n"); + + const run = yield* runFresh({ "README.md": doc }); + + expect(run.results.map((entry) => entry.status)).toEqual(["fail"]); + expect(run.output).toContain("RENDERED FIRST"); + // The body stopped where it failed. + expect(run.output).not.toContain("NEVER REACHED"); + // The diagnostic follows what was rendered, rather than replacing it. + expect(run.output.indexOf("RENDERED FIRST")).toBeLessThan(run.output.indexOf("partial")); + }, + ); + + documentCase("TC5: exactly one result is recorded for a failing test", function* (runFresh) { const doc = [ "", '', @@ -108,31 +116,34 @@ describe("Tier TC — what a keeps when it fails", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results).toHaveLength(1); expect(run.boundaries).toEqual([{ tests: 1, failed: 1 }]); }); - it("TC6: a failing test returns only text — no error segment escapes it", function* () { - const doc = [ - "", - '', - "", - "AFTER", - "", - "", - ].join("\n"); - - const run = yield* runDoc({ "README.md": doc }); - - expect(run.results.map((entry) => entry.status)).toEqual(["fail"]); - // The failure is contained in the test's own report; the boundary carries on. - expect(run.output).toContain("AFTER"); - expect(run.boundaries).toEqual([{ tests: 1, failed: 1 }]); - }); - - it("TC7: a later test runs after an earlier one fails", function* () { + documentCase( + "TC6: a failing test returns only text — no error segment escapes it", + function* (runFresh) { + const doc = [ + "", + '', + "", + "AFTER", + "", + "", + ].join("\n"); + + const run = yield* runFresh({ "README.md": doc }); + + expect(run.results.map((entry) => entry.status)).toEqual(["fail"]); + // The failure is contained in the test's own report; the boundary carries on. + expect(run.output).toContain("AFTER"); + expect(run.boundaries).toEqual([{ tests: 1, failed: 1 }]); + }, + ); + + documentCase("TC7: a later test runs after an earlier one fails", function* (runFresh) { const doc = [ "", '', @@ -141,13 +152,13 @@ describe("Tier TC — what a keeps when it fails", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results.map((entry) => entry.name)).toEqual(["first", "second"]); expect(run.results.map((entry) => entry.status)).toEqual(["fail", "pass"]); }); - it("TC8: a nested fails the enclosing test, and only it", function* () { + documentCase("TC8: a nested fails the enclosing test, and only it", function* (runFresh) { const doc = [ "", '', @@ -157,14 +168,14 @@ describe("Tier TC — what a keeps when it fails", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results).toHaveLength(1); expect(run.results[0]?.name).toBe("outer"); expect(run.results[0]?.status).toBe("fail"); }); - it("TC9: bindings a test captures do not escape it", function* () { + documentCase("TC9: bindings a test captures do not escape it", function* (runFresh) { const doc = [ "", '', @@ -179,7 +190,7 @@ describe("Tier TC — what a keeps when it fails", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); // The binding did not leak into the document after the boundary. diff --git a/packages/testing/tests/helpers.ts b/packages/testing/tests/helpers.ts index f95092a40..d5669be17 100644 --- a/packages/testing/tests/helpers.ts +++ b/packages/testing/tests/helpers.ts @@ -12,6 +12,8 @@ import { InMemoryStream } from "@executablemd/durable-streams"; import type { DurableStream } from "@executablemd/durable-streams"; import { useStubFs } from "@executablemd/runtime/test"; import { execute } from "@executablemd/core"; +import { it } from "@executablemd/test-support/bdd"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { useTesting } from "../src/use-testing.ts"; import { installHandlers, installTestingComponents } from "../src/components.ts"; import { activateTesting } from "../src/activation.ts"; @@ -41,6 +43,27 @@ export interface RunDocOptions { stream?: DurableStream; } +type RunFreshDoc = ( + files: Record, + options?: Omit, +) => Operation; + +export function documentCases(owner: string) { + return (name: string, body: (run: RunFreshDoc) => Operation): void => { + it(name, () => withFreshDocument(owner, name, body)); + }; +} + +export function withFreshDocument( + owner: string, + name: string, + body: (run: RunFreshDoc) => Operation, +): Operation { + return captureTestJournal({ owner, name }, "README.md", (stream) => + body((files, options) => runDoc(files, { ...options, stream })), + ); +} + export function* runDoc( files: Record, options: RunDocOptions = {}, diff --git a/packages/testing/tests/test-component.test.ts b/packages/testing/tests/test-component.test.ts index 7e270d9f3..5ee77a0a6 100644 --- a/packages/testing/tests/test-component.test.ts +++ b/packages/testing/tests/test-component.test.ts @@ -18,7 +18,10 @@ import { Component, registerComponents, useTempFileCompiler } from "@executablem import type { ErrorSegment } from "@executablemd/core"; import { createTestHandlers } from "../src/handlers.ts"; import { absorbTestFailure, Staging } from "../src/test-component.ts"; -import { runDoc } from "./helpers.ts"; +import { documentCases, runDoc, withFreshDocument } from "./helpers.ts"; + +const OWNER = "packages/testing/tests/test-component.test.ts"; +const documentCase = documentCases(OWNER); describe(" as a function component", () => { beforeAll(() => useTempFileCompiler()); @@ -29,56 +32,59 @@ describe(" as a function component", () => { 'yield* spawn(function* () { try { yield* suspend(); } finally { throw new Error("cleanup exploded"); } });', "```", ].join("\n"); - it("keeps Try release safety local to the canonical failed Test report", function* () { - let released = 0; - let replacement = 0; - let finalized = 0; - yield* registerComponents([ - { - name: "BrokenTestRelease", - origin: "test-interaction", - props: { type: "object" }, - *fn() { - yield* ensure(() => { - released++; - throw new Error("test release failed"); - }); - return "body"; + documentCase( + "keeps Try release safety local to the canonical failed Test report", + function* (runFresh) { + let released = 0; + let replacement = 0; + let finalized = 0; + yield* registerComponents([ + { + name: "BrokenTestRelease", + origin: "test-interaction", + props: { type: "object" }, + *fn() { + yield* ensure(() => { + released++; + throw new Error("test release failed"); + }); + return "body"; + }, }, - }, - { - name: "TestReplacement", - origin: "test-interaction", - props: { type: "object" }, - *fn() { - replacement++; - return "WRONG"; + { + name: "TestReplacement", + origin: "test-interaction", + props: { type: "object" }, + *fn() { + replacement++; + return "WRONG"; + }, }, - }, - { - name: "TestFinally", - origin: "test-interaction", - props: { type: "object" }, - *fn() { - finalized++; - return "WRONG"; + { + name: "TestFinally", + origin: "test-interaction", + props: { type: "object" }, + *fn() { + finalized++; + return "WRONG"; + }, }, - }, - ]); - const run = yield* runDoc({ - "README.md": - '', - }); - expect(released).toBe(1); - expect(replacement).toBe(0); - expect(finalized).toBe(0); - expect(run.results.map((result) => [result.name, result.status])).toEqual([ - ["broken", "fail"], - ["fine", "pass"], - ]); - expect(run.completion.ok).toBe(false); - expect(run.output).not.toContain("WRONG"); - }); + ]); + const run = yield* runFresh({ + "README.md": + '', + }); + expect(released).toBe(1); + expect(replacement).toBe(0); + expect(finalized).toBe(0); + expect(run.results.map((result) => [result.name, result.status])).toEqual([ + ["broken", "fail"], + ["fine", "pass"], + ]); + expect(run.completion.ok).toBe(false); + expect(run.output).not.toContain("WRONG"); + }, + ); it("keeps actual Files infrastructure failure globally terminal inside canonical Test", function* () { let fatal: unknown; @@ -140,7 +146,7 @@ describe(" as a function component", () => { // diagnostic before the test claims it. That must not cost the property the // interception exists for: a raise the test does NOT claim still fails it, // even when other middleware observed the segment first. - it("fails the test on a raise an outer observer already saw", function* () { + documentCase("fails the test on a raise an outer observer already saw", function* (runFresh) { const observed: ErrorSegment[] = []; const doc = [ "", @@ -170,7 +176,7 @@ describe(" as a function component", () => { return yield* next(segment); }, }); - return yield* runDoc({ "README.md": doc, "Strict.md": strict }); + return yield* runFresh({ "README.md": doc, "Strict.md": strict }); }); // The observer saw it, and the test still failed because of it. @@ -182,7 +188,7 @@ describe(" as a function component", () => { // Content a component projects is the CALLER's markdown, so `{meta.x}` in it // resolves against the expansion that wrote it, which projection has to be // handed. - it("resolves the document's frontmatter inside a test body", function* () { + documentCase("resolves the document's frontmatter inside a test body", function* (runFresh) { const doc = [ "---", "title: Executable MDX", @@ -197,7 +203,7 @@ describe(" as a function component", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results[0]?.status).toBe("pass"); expect(run.completion.ok).toBe(true); @@ -207,30 +213,33 @@ describe(" as a function component", () => { // own eval scope, so its cleanup failing IS the test's invocation teardown. // That arrives at the session boundary after has returned, and has to // land on that test's staged result. - it("records a teardown failure as that test's outcome, and fails only it", function* () { - const doc = [ - "", - '', - FAILING_CLEANUP, - "", - "", - '', - "", - "", - ].join("\n"); - - const run = yield* runDoc({ "README.md": doc }); - - expect(run.results.map((r) => [r.name, r.status, r.error?.kind])).toEqual([ - ["tears", "fail", "teardown"], - ["fine", "pass", undefined], - ]); - expect(run.results[0]?.error?.message).toContain("cleanup exploded"); - }); + documentCase( + "records a teardown failure as that test's outcome, and fails only it", + function* (runFresh) { + const doc = [ + "", + '', + FAILING_CLEANUP, + "", + "", + '', + "", + "", + ].join("\n"); + + const run = yield* runFresh({ "README.md": doc }); + + expect(run.results.map((r) => [r.name, r.status, r.error?.kind])).toEqual([ + ["tears", "fail", "teardown"], + ["fine", "pass", undefined], + ]); + expect(run.results[0]?.error?.message).toContain("cleanup exploded"); + }, + ); // The body's account is the more useful one, so a test that already failed // keeps its own classification when teardown fails too. - it("keeps the body's classification when teardown also fails", function* () { + documentCase("keeps the body's classification when teardown also fails", function* (runFresh) { const doc = [ "", '', @@ -241,7 +250,7 @@ describe(" as a function component", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results[0]?.status).toBe("fail"); expect(run.results[0]?.error?.kind).toBe("assertion"); @@ -249,33 +258,38 @@ describe(" as a function component", () => { // A component failing beside a test is not the test's outcome: the session // layer delegates anything that is not a invocation. - it("does not turn a neighbouring component's failure into a test result", function* () { - const doc = ["", '', "", ""].join("\n"); - - const run = yield* scoped(function* () { - yield* registerComponents([ - { - name: "Wilting", - origin: "test", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn() { - yield* ensure(function* () { - throw new Error("component cleanup exploded"); - }); - return ""; + documentCase( + "does not turn a neighbouring component's failure into a test result", + function* (runFresh) { + const doc = ["", '', "", ""].join( + "\n", + ); + + const run = yield* scoped(function* () { + yield* registerComponents([ + { + name: "Wilting", + origin: "test", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn() { + yield* ensure(function* () { + throw new Error("component cleanup exploded"); + }); + return ""; + }, }, - }, - ]); - return yield* runDoc({ "README.md": doc }); - }); + ]); + return yield* runFresh({ "README.md": doc }); + }); - // One result, for the test that contained it — classified as an ordinary - // error, because the component's teardown is the component's, not the - // test's. - expect(run.results).toHaveLength(1); - expect(run.results[0]?.name).toBe("only"); - expect(run.results[0]?.error?.kind).toBe("error"); - }); + // One result, for the test that contained it — classified as an ordinary + // error, because the component's teardown is the component's, not the + // test's. + expect(run.results).toHaveLength(1); + expect(run.results[0]?.name).toBe("only"); + expect(run.results[0]?.error?.kind).toBe("error"); + }, + ); /** Every journalled entry of `type`, by the name it recorded, in order. */ function* entriesOf(stream: InMemoryStream, type: string): Operation { @@ -365,7 +379,7 @@ describe(" as a function component", () => { // A timed-out body was halted mid-flight, so there is no partial output to // keep — the report is the diagnostic alone (§5.3). - it("renders only the diagnostic when a test times out", function* () { + documentCase("renders only the diagnostic when a test times out", function* (runFresh) { const doc = [ "", '', @@ -379,7 +393,7 @@ describe(" as a function component", () => { "", ].join("\n"); - const run = yield* runDoc( + const run = yield* runFresh( { "README.md": doc }, { handlers: createTestHandlers({ timeoutMs: 60 }) }, ); @@ -391,7 +405,7 @@ describe(" as a function component", () => { // `timeout=` is the test's own bound: a body the installed default would cut // short finishes inside the duration the element declares (§5.3). - it("lets a declared timeout outlive a shorter installed default", function* () { + documentCase("lets a declared timeout outlive a shorter installed default", function* (runFresh) { const doc = [ "", '', @@ -404,7 +418,7 @@ describe(" as a function component", () => { "", ].join("\n"); - const run = yield* runDoc( + const run = yield* runFresh( { "README.md": doc }, { handlers: createTestHandlers({ timeoutMs: 60 }) }, ); @@ -414,7 +428,7 @@ describe(" as a function component", () => { // The declared bound also cuts, and the diagnostic names the duration the // element declared rather than the default it replaced. - it("times out at a declared timeout below the default", function* () { + documentCase("times out at a declared timeout below the default", function* (runFresh) { const doc = [ "", '', @@ -426,7 +440,7 @@ describe(" as a function component", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results[0]?.error?.kind).toBe("timeout"); expect(run.results[0]?.error?.message).toContain("0.06 seconds"); @@ -434,7 +448,7 @@ describe(" as a function component", () => { // A malformed duration is refused where it was written, and where it was // written is one test — the ones after it still run. - it("fails only the declaring test on a malformed timeout", function* () { + documentCase("fails only the declaring test on a malformed timeout", function* (runFresh) { const doc = [ "", 'inside', @@ -443,7 +457,7 @@ describe(" as a function component", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results).toHaveLength(2); expect(run.results[0]?.status).toBe("fail"); @@ -453,7 +467,7 @@ describe(" as a function component", () => { // A teardown-failed test had already returned, so the engine replaces its // output with the boundary's diagnostic — no body text survives (§5.4). - it("renders only the boundary diagnostic when teardown fails", function* () { + documentCase("renders only the boundary diagnostic when teardown fails", function* (runFresh) { const doc = [ "", '', @@ -465,7 +479,7 @@ describe(" as a function component", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results[0]?.error?.kind).toBe("teardown"); expect(run.output).not.toContain("BODY TEXT"); @@ -476,22 +490,24 @@ describe(" as a function component", () => { // around it are the author's and stay, exactly as they would around any // element that renders nothing — so the comparison is against the element // removed, not against the lines it sat between removed too (§5.2). - it("renders nothing of itself when skipped", function* () { + const skippedCase = "renders nothing of itself when skipped"; + documentCase(skippedCase, function* (runFresh) { const withTest = ["before", "", 'inside', "", "after", ""].join( "\n", ); const withoutTest = ["before", "", "", "", "after", ""].join("\n"); - const skipped = yield* runDoc({ "README.md": withTest }, { testing: false }); - const plain = yield* runDoc({ "README.md": withoutTest }, { testing: false }); - - expect(skipped.output).not.toContain("inside"); - expect(skipped.output).toBe(plain.output); + const skipped = yield* runFresh({ "README.md": withTest }, { testing: false }); + yield* withFreshDocument(OWNER, skippedCase, function* (runPlain) { + const plain = yield* runPlain({ "README.md": withoutTest }, { testing: false }); + expect(skipped.output).not.toContain("inside"); + expect(skipped.output).toBe(plain.output); + }); }); // A nested is invalid, and what that means is the ENCLOSING test's // recorded outcome — not the shape of anything it returned. - it("fails the enclosing test on nesting, recorded as an error", function* () { + documentCase("fails the enclosing test on nesting, recorded as an error", function* (runFresh) { const doc = [ "", '', @@ -499,7 +515,7 @@ describe(" as a function component", () => { "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results.map((r) => [r.name, r.status, r.error?.kind])).toEqual([ ["outer", "fail", "error"], diff --git a/packages/testing/tests/testing-boundary.test.ts b/packages/testing/tests/testing-boundary.test.ts index 6fb97d617..e88029219 100644 --- a/packages/testing/tests/testing-boundary.test.ts +++ b/packages/testing/tests/testing-boundary.test.ts @@ -14,7 +14,9 @@ import { scoped } from "effection"; import type { Operation } from "effection"; import { InMemoryStream } from "@executablemd/durable-streams"; import { registerComponents, useTempFileCompiler } from "@executablemd/core"; -import { runDoc } from "./helpers.ts"; +import { documentCases, runDoc } from "./helpers.ts"; + +const documentCase = documentCases("packages/testing/tests/testing-boundary.test.ts"); import type { DocRun } from "./helpers.ts"; /** Every journalled boundary entry, by the name it recorded. */ @@ -125,23 +127,26 @@ describe("Tier TB — a boundary that never finished", () => { describe("Tier TB — a repository component replaces ", () => { beforeAll(() => useTempFileCompiler()); - it("TB4: a local Testing component is selected, and the package's never runs", function* () { - const run = yield* runDoc({ - "README.md": [ - "", - '', - "", - "", - ].join("\n"), - "components/Testing.md": "LOCAL TESTING BOUNDARY\n", - }); - - // The repository component answered… - expect(run.output).toContain("LOCAL TESTING BOUNDARY"); - // …so the package implementation never activated testing: the `` - // inside stayed inert, recorded no result, and reported no boundary. - expect(run.results).toEqual([]); - expect(run.boundaries).toEqual([]); - expect(run.output).not.toContain("would-run"); - }); + documentCase( + "TB4: a local Testing component is selected, and the package's never runs", + function* (runFresh) { + const run = yield* runFresh({ + "README.md": [ + "", + '', + "", + "", + ].join("\n"), + "components/Testing.md": "LOCAL TESTING BOUNDARY\n", + }); + + // The repository component answered… + expect(run.output).toContain("LOCAL TESTING BOUNDARY"); + // …so the package implementation never activated testing: the `` + // inside stayed inert, recorded no result, and reported no boundary. + expect(run.results).toEqual([]); + expect(run.boundaries).toEqual([]); + expect(run.output).not.toContain("would-run"); + }, + ); }); diff --git a/packages/testing/tests/testing-mode.test.ts b/packages/testing/tests/testing-mode.test.ts index ceafaf300..06e586f0e 100644 --- a/packages/testing/tests/testing-mode.test.ts +++ b/packages/testing/tests/testing-mode.test.ts @@ -7,11 +7,13 @@ import { API } from "@executablemd/runtime"; import { useFailingExec } from "@executablemd/runtime/test"; import { TestFailureError } from "../src/test-api.ts"; import { createTestHandlers } from "../src/handlers.ts"; -import { failureOf, runDoc } from "./helpers.ts"; +import { documentCases, failureOf, runDoc } from "./helpers.ts"; + +const documentCase = documentCases("packages/testing/tests/testing-mode.test.ts"); describe("testing mode", () => { beforeAll(() => useTempFileCompiler()); - it("skips entirely during regular execution", function* () { + documentCase("skips entirely during regular execution", function* (runFresh) { const execCalls: string[] = []; yield* API.Process.around({ // deno-lint-ignore require-yield @@ -31,7 +33,7 @@ describe("testing mode", () => { "after", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.completion.ok).toBe(true); expect(run.output).toContain("before"); expect(run.output).toContain("after"); @@ -40,49 +42,49 @@ describe("testing mode", () => { expect(run.results).toEqual([]); }); - it("explicit runs its subtree during a regular run", function* () { + documentCase("explicit runs its subtree during a regular run", function* (runFresh) { const doc = '\n'; - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.completion.ok).toBe(true); expect(run.results.map((r) => [r.name, r.status])).toEqual([["t", "pass"]]); expect(run.boundaries).toEqual([{ tests: 1, failed: 0 }]); }); - it("a failing boundary rejects an ordinary run", function* () { + documentCase("a failing boundary rejects an ordinary run", function* (runFresh) { const doc = "\n"; - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(failureOf(run)).toBeInstanceOf(TestFailureError); expect(run.output).toContain("Test"); }); - it("an empty boundary rejects an ordinary run", function* () { - const run = yield* runDoc({ "README.md": "no tests here\n" }); + documentCase("an empty boundary rejects an ordinary run", function* (runFresh) { + const run = yield* runFresh({ "README.md": "no tests here\n" }); expect(failureOf(run)).toBeInstanceOf(TestFailureError); expect(run.boundaries).toEqual([{ tests: 0, failed: 0 }]); }); - it("root activation runs tests without ", function* () { + documentCase("root activation runs tests without ", function* (runFresh) { const doc = '\n'; - const run = yield* runDoc({ "README.md": doc }, { testing: true }); + const run = yield* runFresh({ "README.md": doc }, { testing: true }); expect(run.completion.ok).toBe(true); expect(run.results.map((r) => [r.name, r.status])).toEqual([["rooted", "pass"]]); }); - it("root activation with zero tests fails", function* () { - const run = yield* runDoc({ "README.md": "just text\n" }, { testing: true }); + documentCase("root activation with zero tests fails", function* (runFresh) { + const run = yield* runFresh({ "README.md": "just text\n" }, { testing: true }); const error = failureOf(run); expect(error).toBeInstanceOf(TestFailureError); expect(error?.message).toContain("no tests were discovered"); }); - it("nested delegates results outward", function* () { + documentCase("nested delegates results outward", function* (runFresh) { const doc = [ "", "", "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.completion.ok).toBe(true); // Inner boundary reports first; the outer boundary sees the delegated // result, so neither boundary is empty. @@ -93,7 +95,7 @@ describe("testing mode", () => { expect(run.results).toHaveLength(1); }); - it("a failing exec block fails the test; later tests run", function* () { + documentCase("a failing exec block fails the test; later tests run", function* (runFresh) { yield* useFailingExec(3, "command exploded"); const doc = [ "", @@ -106,7 +108,7 @@ describe("testing mode", () => { "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(failureOf(run)).toBeInstanceOf(TestFailureError); expect(run.results.map((r) => [r.name, r.status, r.error?.kind])).toEqual([ ["broken", "fail", "error"], @@ -114,22 +116,25 @@ describe("testing mode", () => { ]); }); - it("an unresolvable component import fails the test; later tests run", function* () { - const doc = [ - "", - '', - '', - "", - "", - ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); - expect(run.results.map((r) => [r.name, r.status, r.error?.kind])).toEqual([ - ["missing", "fail", "error"], - ["fine", "pass", undefined], - ]); - }); + documentCase( + "an unresolvable component import fails the test; later tests run", + function* (runFresh) { + const doc = [ + "", + '', + '', + "", + "", + ].join("\n"); + const run = yield* runFresh({ "README.md": doc }); + expect(run.results.map((r) => [r.name, r.status, r.error?.kind])).toEqual([ + ["missing", "fail", "error"], + ["fine", "pass", undefined], + ]); + }, + ); - it("nested fails the enclosing test; later tests run", function* () { + documentCase("nested fails the enclosing test; later tests run", function* (runFresh) { const doc = [ "", '', @@ -137,7 +142,7 @@ describe("testing mode", () => { "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results.map((r) => [r.name, r.status, r.error?.kind])).toEqual([ ["outer", "fail", "error"], ["fine", "pass", undefined], @@ -145,38 +150,44 @@ describe("testing mode", () => { expect(run.results[0]?.error?.message).toContain("Nested "); }); - it("an error raised inside a component-owned region fails the test", function* () { - const comp = "\nregion start\n\n\n"; - const doc = [ - "", - '', - '', - "", - "", - ].join("\n"); - const run = yield* runDoc({ "README.md": doc, "components/Regioned.md": comp }); - expect(run.results.map((r) => [r.name, r.status])).toEqual([ - ["output-region", "fail"], - ["fine", "pass"], - ]); - }); + documentCase( + "an error raised inside a component-owned region fails the test", + function* (runFresh) { + const comp = "\nregion start\n\n\n"; + const doc = [ + "", + '', + '', + "", + "", + ].join("\n"); + const run = yield* runFresh({ "README.md": doc, "components/Regioned.md": comp }); + expect(run.results.map((r) => [r.name, r.status])).toEqual([ + ["output-region", "fail"], + ["fine", "pass"], + ]); + }, + ); - it("a completed failing test inside a documentation region stays contained", function* () { - const comp = "\n\n\n"; - const doc = [ - "", - '', - "", - "", - ].join("\n"); - const run = yield* runDoc({ "README.md": doc, "components/Regioned.md": comp }); - // The document expands fully — the failure surfaces as a testing - // outcome, not an expansion abort. - expect(failureOf(run)).toBeInstanceOf(TestFailureError); - expect(run.results.map((r) => [r.name, r.status])).toEqual([["contained", "fail"]]); - }); + documentCase( + "a completed failing test inside a documentation region stays contained", + function* (runFresh) { + const comp = "\n\n\n"; + const doc = [ + "", + '', + "", + "", + ].join("\n"); + const run = yield* runFresh({ "README.md": doc, "components/Regioned.md": comp }); + // The document expands fully — the failure surfaces as a testing + // outcome, not an expansion abort. + expect(failureOf(run)).toBeInstanceOf(TestFailureError); + expect(run.results.map((r) => [r.name, r.status])).toEqual([["contained", "fail"]]); + }, + ); - it("bindings written in one test are invisible to the next", function* () { + documentCase("bindings written in one test are invisible to the next", function* (runFresh) { const doc = [ "```js eval", "const inherited = 7;", @@ -196,32 +207,35 @@ describe("testing mode", () => { "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.completion.ok).toBe(true); expect(run.results.map((r) => r.status)).toEqual(["pass", "pass"]); }); - it("a projected through sees caller bindings in its eval blocks", function* () { - const doc = [ - "```js eval", - 'const callerValue = "from-caller";', - "```", - "", - '', - "```js eval", - 'const copied = callerValue + "!";', - "```", - '', - "", - "", - "", - ].join("\n"); - const run = yield* runDoc({ "README.md": doc, "components/Wrap.md": "\n" }); - expect(run.completion.ok).toBe(true); - expect(run.results.map((r) => [r.name, r.status])).toEqual([["projected", "pass"]]); - }); + documentCase( + "a projected through sees caller bindings in its eval blocks", + function* (runFresh) { + const doc = [ + "```js eval", + 'const callerValue = "from-caller";', + "```", + "", + '', + "```js eval", + 'const copied = callerValue + "!";', + "```", + '', + "", + "", + "", + ].join("\n"); + const run = yield* runFresh({ "README.md": doc, "components/Wrap.md": "\n" }); + expect(run.completion.ok).toBe(true); + expect(run.results.map((r) => [r.name, r.status])).toEqual([["projected", "pass"]]); + }, + ); - it("captures persist for the immediately following assertion", function* () { + documentCase("captures persist for the immediately following assertion", function* (runFresh) { const doc = [ "", 'Hello World', @@ -229,37 +243,40 @@ describe("testing mode", () => { "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.completion.ok).toBe(true); expect(run.results.map((r) => r.status)).toEqual(["pass"]); }); - it("effects spawned in one test are torn down before the next begins", function* () { - Reflect.deleteProperty(globalThis, "__testingLeaseAlive"); - const doc = [ - "", - '', - "```js persist eval", - "globalThis.__testingLeaseAlive = true;", - "yield* spawn(function* () { try { yield* suspend(); } finally { globalThis.__testingLeaseAlive = false; } });", - "```", - "", - "", - '', - "", - "", - "", - "", - ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); - expect(run.completion.ok).toBe(true); - expect(run.results.map((r) => [r.name, r.status])).toEqual([ - ["spawner", "pass"], - ["observer", "pass"], - ]); - }); + documentCase( + "effects spawned in one test are torn down before the next begins", + function* (runFresh) { + Reflect.deleteProperty(globalThis, "__testingLeaseAlive"); + const doc = [ + "", + '', + "```js persist eval", + "globalThis.__testingLeaseAlive = true;", + "yield* spawn(function* () { try { yield* suspend(); } finally { globalThis.__testingLeaseAlive = false; } });", + "```", + "", + "", + '', + "", + "", + "", + "", + ].join("\n"); + const run = yield* runFresh({ "README.md": doc }); + expect(run.completion.ok).toBe(true); + expect(run.results.map((r) => [r.name, r.status])).toEqual([ + ["spawner", "pass"], + ["observer", "pass"], + ]); + }, + ); - it("output before a failure is kept, followed by the diagnostic", function* () { + documentCase("output before a failure is kept, followed by the diagnostic", function* (runFresh) { const doc = [ "", "first line", @@ -268,7 +285,7 @@ describe("testing mode", () => { "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.output).toContain("first line"); expect(run.output).toContain("**Assert** failed"); expect(run.output).not.toContain("never rendered"); @@ -277,7 +294,7 @@ describe("testing mode", () => { expect(firstAt).toBeLessThan(diagnosticAt); }); - it("a hanging test times out, is torn down, and later tests run", function* () { + documentCase("a hanging test times out, is torn down, and later tests run", function* (runFresh) { yield* API.Process.around({ *exec(_args, _next) { yield* sleep(10_000); @@ -295,7 +312,7 @@ describe("testing mode", () => { "", "", ].join("\n"); - const run = yield* runDoc( + const run = yield* runFresh( { "README.md": doc }, { handlers: createTestHandlers({ timeoutMs: 100 }) }, ); @@ -306,7 +323,7 @@ describe("testing mode", () => { ]); }); - it("unnamed tests are identified by source location", function* () { + documentCase("unnamed tests are identified by source location", function* (runFresh) { const doc = [ "---", "title: Located", @@ -316,7 +333,7 @@ describe("testing mode", () => { "", "", ].join("\n"); - const run = yield* runDoc({ "README.md": doc }); + const run = yield* runFresh({ "README.md": doc }); expect(run.results[0]?.location).toBe("README.md:5:1"); expect(run.output).toContain("test at README.md:5:1"); }); @@ -328,7 +345,7 @@ describe("testing mode", () => { * exactly as it would be anywhere else a document did not authorize one * (#441). */ - it("a repository Test of the same name contains nothing", function* () { + documentCase("a repository Test of the same name contains nothing", function* (runFresh) { yield* useFailingExec(3, "command exploded"); const doc = [ "", @@ -341,7 +358,7 @@ describe("testing mode", () => { "", "", ].join("\n"); - const run = yield* runDoc({ + const run = yield* runFresh({ "README.md": doc, // Chosen ahead of the package's, and a different function object. "Test.md": "\n", diff --git a/packages/testing/tests/use-testing.test.ts b/packages/testing/tests/use-testing.test.ts index e10d38053..d8051f222 100644 --- a/packages/testing/tests/use-testing.test.ts +++ b/packages/testing/tests/use-testing.test.ts @@ -5,13 +5,20 @@ import { when } from "@effectionx/converge"; import { scoped, sleep, spawn } from "effection"; import type { Operation, Subscription } from "effection"; import { InMemoryStream } from "@executablemd/durable-streams"; +import { parseDurableEvent } from "@executablemd/durable-streams"; +import { exists, readdir, readTextFile } from "@effectionx/fs"; +import { useTempDirectory } from "@executablemd/test-support/temp"; +import { join } from "node:path"; import { useStubFs } from "@executablemd/runtime/test"; import { API } from "@executablemd/runtime"; import { execute, Execution, registerComponents } from "@executablemd/core"; import type { Json } from "@executablemd/core"; import { Test, TestFailureError, testing } from "../src/test-api.ts"; import { useTesting } from "../src/use-testing.ts"; -import { failureOf, runDoc } from "./helpers.ts"; +import { documentCases, failureOf, runDoc, withFreshDocument } from "./helpers.ts"; + +const OWNER = "packages/testing/tests/use-testing.test.ts"; +const documentCase = documentCases(OWNER); function* drain( subscription: Subscription, @@ -27,6 +34,60 @@ function* drain( describe("useTesting composition", () => { beforeAll(() => useTempFileCompiler()); + + const journalWitness = "attributes a fresh document when its caller fails after execution"; + it(journalWitness, function* () { + const root = yield* useTempDirectory("xmd-testing-fresh-document-"); + const failure = new Error("outer assertion"); + function attempt(directory: string, check: () => void): Operation { + return scoped(function* () { + yield* API.Env.around({ + *env([variable], next) { + return variable === "XMD_TEST_ARTIFACTS" ? directory : yield* next(variable); + }, + }); + yield* withFreshDocument(OWNER, journalWitness, function* (runFresh) { + const result = yield* runFresh( + { "README.md": "\n" }, + { testing: true }, + ); + expect(result.completion.ok).toBe(false); + check(); + }); + }); + } + + const passed = join(root, "passed"); + yield* attempt(passed, () => undefined); + expect(yield* exists(passed)).toBe(false); + + const failed = join(root, "failed"); + let caught: unknown; + try { + yield* attempt(failed, () => { + throw failure; + }); + } catch (error) { + caught = error; + } + expect(caught).toBe(failure); + const invocations = yield* readdir(failed); + expect(invocations).toHaveLength(1); + const directory = join(failed, invocations[0]); + expect(JSON.parse(yield* readTextFile(join(directory, "root-1.case.json")))).toEqual({ + owner: OWNER, + name: journalWitness, + kind: "root", + ordinal: 1, + source: "README.md", + }); + const lines = (yield* readTextFile(join(directory, "root-1.jsonl"))).trimEnd().split("\n"); + expect(parseDurableEvent(lines.at(-1) ?? "")).toMatchObject({ + ok: true, + value: { type: "close", coroutineId: "root" }, + }); + }); + it("composes around core execute and returns session results", function* () { const outcome = yield* scoped(function* () { yield* useStubFs({ @@ -112,7 +173,7 @@ describe("useTesting composition", () => { expect(error?.message).toContain("one session per execution scope"); }); - it("removes all session middleware with its scope", function* () { + documentCase("removes all session middleware with its scope", function* (runFresh) { yield* scoped(function* () { yield* useStubFs({ "README.md": "\n" }); yield* useTesting(); @@ -124,7 +185,7 @@ describe("useTesting composition", () => { // Outside the session scope: activation, collectors, and policy are gone. expect(yield* testing).toBe(false); expect(yield* Test.operations.results()).toEqual([]); - const second = yield* runDoc({ "README.md": "\n" }); + const second = yield* runFresh({ "README.md": "\n" }); expect(second.completion.ok).toBe(true); expect(second.output).not.toContain("Assert"); expect(second.results).toEqual([]); From 0a1f45ebcbe134be31ec117e88c00379129b356d Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 13:33:10 -0500 Subject: [PATCH 03/78] test: capture failure journals for live WebForm cases --- packages/web/tests/component-support.ts | 16 ++ packages/web/tests/component.test.ts | 235 ++++++++++++++++-------- packages/web/tests/document.test.ts | 95 +++++----- 3 files changed, 226 insertions(+), 120 deletions(-) diff --git a/packages/web/tests/component-support.ts b/packages/web/tests/component-support.ts index 22b645ad5..2e3a5a59c 100644 --- a/packages/web/tests/component-support.ts +++ b/packages/web/tests/component-support.ts @@ -19,6 +19,8 @@ import { mkdtemp, realpath } from "node:fs/promises"; import process from "node:process"; import { basename, join } from "node:path"; import { rm, writeTextFile } from "@effectionx/fs"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; +import type { JournalCase } from "../../cli/src/test-diagnostics.ts"; import { FormAssets } from "../src/assets.ts"; import type { Json } from "../src/json.ts"; @@ -76,6 +78,20 @@ export interface DocRun { stream: DurableStream; } +export function withWebFormDocument( + testCase: JournalCase, + source: string, + options: Omit, + check: (run: DocRun) => void | Operation, +): Operation { + return captureTestJournal(testCase, options.realFiles ? source : "README.md", function* (stream) { + const assertions = check(yield* runWebFormDoc(source, { ...options, stream })); + if (assertions !== undefined) { + yield* assertions; + } + }); +} + /** * Run one document with `` registered and every seam observed. * diff --git a/packages/web/tests/component.test.ts b/packages/web/tests/component.test.ts index 0926e4c73..2c1d3f170 100644 --- a/packages/web/tests/component.test.ts +++ b/packages/web/tests/component.test.ts @@ -4,6 +4,10 @@ import { expect } from "@executablemd/test-support/expect"; import { InMemoryStream } from "@executablemd/durable-streams"; import type { Operation } from "effection"; import { join } from "node:path"; +import { scoped } from "effection"; +import { exists, readdir, readTextFile } from "@effectionx/fs"; +import { API } from "@executablemd/runtime"; +import { useTempDirectory } from "@executablemd/test-support/temp"; import { journaled, @@ -12,8 +16,26 @@ import { REVIEW_SCHEMA, runWebFormDoc, useLocalFixture, + withWebFormDocument, writeFile, } from "./component-support.ts"; +import type { DocRun, RunOptions } from "./component-support.ts"; + +type RunFreshForm = ( + source: string, + options: Omit, + check: (run: DocRun) => void | Operation, +) => Operation; + +const OWNER = "packages/web/tests/component.test.ts"; + +function formCase(name: string, body: (run: RunFreshForm) => Operation): void { + it(name, () => + body((source, options, check) => + withWebFormDocument({ owner: OWNER, name }, source, options, check), + ), + ); +} const SCHEMA_BLOCK = [ "```js eval", @@ -26,8 +48,61 @@ function document(body: string, props = "schema={reviewSchema}"): string { } describe("WebForm: what a document gets", () => { - it("binds the validated response and renders nothing", function* () { - const run = yield* runWebFormDoc( + const artifactCase = "attributes a failed assertion to the settled live form"; + it(artifactCase, function* () { + const root = yield* useTempDirectory("xmd-webform-artifacts-"); + const failure = new Error("post-response assertion"); + function attempt(artifacts: string, assertion: () => void): Operation { + return scoped(function* () { + yield* API.Env.around({ + *env([variable], next) { + return variable === "XMD_TEST_ARTIFACTS" ? artifacts : yield* next(variable); + }, + }); + yield* withWebFormDocument( + { owner: OWNER, name: artifactCase }, + document("Decide."), + { answer: { decision: "approve" } }, + (run) => { + expect(run.completion.ok).toBe(true); + expect(run.effects.served).toBe(1); + assertion(); + }, + ); + }); + } + + const passed = join(root, "passed"); + yield* attempt(passed, () => undefined); + expect(yield* exists(passed)).toBe(false); + + const failed = join(root, "failed"); + let caught: unknown; + try { + yield* attempt(failed, () => { + throw failure; + }); + } catch (error) { + caught = error; + } + expect(caught).toBe(failure); + const invocations = yield* readdir(failed); + expect(invocations).toHaveLength(1); + const directory = join(failed, invocations[0]); + expect(JSON.parse(yield* readTextFile(join(directory, "root-1.case.json")))).toEqual({ + owner: OWNER, + name: artifactCase, + kind: "root", + ordinal: 1, + source: "README.md", + }); + const records = yield* readTextFile(join(directory, "root-1.jsonl")); + expect(records).toContain('"type":"web_form"'); + expect(records).not.toContain("127.0.0.1"); + }); + + formCase("binds the validated response and renders nothing", function* (runFresh) { + yield* runFresh( [ document("# Review required\n\nDecide."), "```js eval", @@ -35,38 +110,45 @@ describe("WebForm: what a document gets", () => { "```", ].join("\n"), { answer: { decision: "approve", note: "fine" } }, + function (run) { + expect(run.completion.ok).toBe(true); + // The captured value, and no trace of the form around it. + expect(run.output).toContain('"decision":"approve"'); + expect(run.output).toContain('"note":"fine"'); + expect(run.output.includes("127.0.0.1")).toBe(false); + expect(run.output.includes("Review required")).toBe(false); + }, ); - - expect(run.completion.ok).toBe(true); - // The captured value, and no trace of the form around it. - expect(run.output).toContain('"decision":"approve"'); - expect(run.output).toContain('"note":"fine"'); - expect(run.output.includes("127.0.0.1")).toBe(false); - expect(run.output.includes("Review required")).toBe(false); }); - it("is answered through its own live server", function* () { - const run = yield* runWebFormDoc(document("Decide."), { - answer: { decision: "reject" }, - }); - - expect(run.completion.ok).toBe(true); - expect(run.effects.served).toBe(1); - expect(run.effects.opened.length).toBe(1); - expect(run.effects.responded.length).toBe(1); - // Opener and responder were handed the same live URL. - expect(run.effects.opened[0]).toBe(run.effects.responded[0]); - expect(run.effects.opened[0]).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/f\/[A-Za-z0-9_-]{43}\/$/); + formCase("is answered through its own live server", function* (runFresh) { + yield* runFresh( + document("Decide."), + { + answer: { decision: "reject" }, + }, + function (run) { + expect(run.completion.ok).toBe(true); + expect(run.effects.served).toBe(1); + expect(run.effects.opened.length).toBe(1); + expect(run.effects.responded.length).toBe(1); + // Opener and responder were handed the same live URL. + expect(run.effects.opened[0]).toBe(run.effects.responded[0]); + expect(run.effects.opened[0]).toMatch( + /^http:\/\/127\.0\.0\.1:\d+\/f\/[A-Za-z0-9_-]{43}\/$/, + ); + }, + ); }); - it("prints the URL a person can use", function* () { - const run = yield* runWebFormDoc(document("Decide."), { answer: { decision: "approve" } }); - - const url = run.effects.opened[0]; - expect(run.effects.printed.some((line) => line.includes(url))).toBe(true); + formCase("prints the URL a person can use", function* (runFresh) { + yield* runFresh(document("Decide."), { answer: { decision: "approve" } }, function (run) { + const url = run.effects.opened[0]; + expect(run.effects.printed.some((line) => line.includes(url))).toBe(true); + }); }); - it("resolves an expression-valued uiSchema through core", function* () { + formCase("resolves an expression-valued uiSchema through core", function* (runFresh) { const source = [ "```js eval", `const reviewSchema = ${JSON.stringify(REVIEW_SCHEMA)};`, @@ -82,10 +164,10 @@ describe("WebForm: what a document gets", () => { "```", ].join("\n"); - const run = yield* runWebFormDoc(source, { answer: { decision: "approve" } }); - - expect(run.completion.ok).toBe(true); - expect(run.output).toContain("approve"); + yield* runFresh(source, { answer: { decision: "approve" } }, function (run) { + expect(run.completion.ok).toBe(true); + expect(run.output).toContain("approve"); + }); }); }); @@ -102,7 +184,7 @@ describe("WebForm: nothing happens before the question is ready", () => { * this asserts is the consequence — the diagnostic reached the document and * nothing was served. */ - it("causes no live effect when its content fails", function* () { + formCase("causes no live effect when its content fails", function* (runFresh) { const source = [ SCHEMA_BLOCK, "", @@ -113,22 +195,22 @@ describe("WebForm: nothing happens before the question is ready", () => { "", ].join("\n"); - const run = yield* runWebFormDoc(source, { answer: { decision: "approve" } }); - - // Nothing recovers the body's failure, so the run reports it. - expect(run.completion.ok).toBe(false); - expect(run.completion.ok ? "" : run.completion.error.message).toContain("the body failed"); - expect(run.effects.served).toBe(0); - expect(run.effects.opened).toEqual([]); - expect(run.effects.responded).toEqual([]); - expect(run.effects.printed).toEqual([]); - // No entry at all, not merely no successful one: a durable operation that - // began and failed would leave an `err` event, and that is still work done - // for a question nobody was ever asked. - expect(yield* journalEvents(run.stream, "web_form")).toEqual([]); + yield* runFresh(source, { answer: { decision: "approve" } }, function* (run) { + // Nothing recovers the body's failure, so the run reports it. + expect(run.completion.ok).toBe(false); + expect(run.completion.ok ? "" : run.completion.error.message).toContain("the body failed"); + expect(run.effects.served).toBe(0); + expect(run.effects.opened).toEqual([]); + expect(run.effects.responded).toEqual([]); + expect(run.effects.printed).toEqual([]); + // No entry at all, not merely no successful one: a durable operation that + // began and failed would leave an `err` event, and that is still work done + // for a question nobody was ever asked. + expect(yield* journalEvents(run.stream, "web_form")).toEqual([]); + }); }); - it("causes no live effect when the schema cannot be used", function* () { + formCase("causes no live effect when the schema cannot be used", function* (runFresh) { const unusable: [string, string][] = [ ["not JSON", 'x'], ["not an object", 'x'], @@ -148,33 +230,34 @@ describe("WebForm: nothing happens before the question is ready", () => { ]; for (const [label, source] of unusable) { - const run = yield* runWebFormDoc(source, { answer: { decision: "approve" } }); - - expect({ label, ok: run.completion.ok }).toEqual({ label, ok: false }); - expect({ label, served: run.effects.served }).toEqual({ label, served: 0 }); - expect({ label, opened: run.effects.opened }).toEqual({ label, opened: [] }); - expect({ label, responded: run.effects.responded }).toEqual({ label, responded: [] }); - expect({ label, printed: run.effects.printed }).toEqual({ label, printed: [] }); - // Every durable yield, not the successful ones: an operation that began and - // failed leaves an `err` event, and that is still work done for a question - // nobody was ever asked. - expect({ label, events: yield* journalEvents(run.stream, "web_form") }).toEqual({ - label, - events: [], + yield* runFresh(source, { answer: { decision: "approve" } }, function* (run) { + expect({ label, ok: run.completion.ok }).toEqual({ label, ok: false }); + expect({ label, served: run.effects.served }).toEqual({ label, served: 0 }); + expect({ label, opened: run.effects.opened }).toEqual({ label, opened: [] }); + expect({ label, responded: run.effects.responded }).toEqual({ label, responded: [] }); + expect({ label, printed: run.effects.printed }).toEqual({ label, printed: [] }); + // Every durable yield, not the successful ones: an operation that began and + // failed leaves an `err` event, and that is still work done for a question + // nobody was ever asked. + expect({ label, events: yield* journalEvents(run.stream, "web_form") }).toEqual({ + label, + events: [], + }); }); } }); /** Unmarked, so #251's default applies: the failure is the document's. */ - it("fails the document rather than printing", function* () { - const run = yield* runWebFormDoc( + formCase("fails the document rather than printing", function* (runFresh) { + yield* runFresh( 'Decide.\n\nafter\n', { answer: { decision: "approve" } }, + function (run) { + expect(run.completion.ok).toBe(false); + // Nothing after it ran, which a printed error would have allowed. + expect(run.output.includes("after")).toBe(false); + }, ); - - expect(run.completion.ok).toBe(false); - // Nothing after it ran, which a printed error would have allowed. - expect(run.output.includes("after")).toBe(false); }); }); @@ -309,20 +392,20 @@ describe("WebForm: a repository file outranks the registration", () => { * Real files rather than a stubbed filesystem: a `.ts` component is `import()`ed * from a real path, so a stub can resolve its name and then fail to load it. */ - it("prefers a repository WebForm.md", function* () { + formCase("prefers a repository WebForm.md", function* (runFresh) { const dir = yield* useLocalFixture(); yield* writeFile(join(dir, "WebForm.md"), "the repository's own form\n"); const doc = join(dir, "README.md"); yield* writeFile(doc, "\n"); - const run = yield* runWebFormDoc(doc, { realFiles: true, includes: [dir] }); - - expect(run.output).toContain("the repository's own form"); - // The registered default never ran, so nothing was served. - expect(run.effects.served).toBe(0); + yield* runFresh(doc, { realFiles: true, includes: [dir] }, function (run) { + expect(run.output).toContain("the repository's own form"); + // The registered default never ran, so nothing was served. + expect(run.effects.served).toBe(0); + }); }); - it("prefers a repository WebForm.ts", function* () { + formCase("prefers a repository WebForm.ts", function* (runFresh) { yield* useComponentModuleLoader(); const dir = yield* useLocalFixture(); yield* writeFile( @@ -334,9 +417,9 @@ describe("WebForm: a repository file outranks the registration", () => { const doc = join(dir, "README.md"); yield* writeFile(doc, "\n"); - const run = yield* runWebFormDoc(doc, { realFiles: true, includes: [dir] }); - - expect(run.output).toContain("the repository's own function"); - expect(run.effects.served).toBe(0); + yield* runFresh(doc, { realFiles: true, includes: [dir] }, function (run) { + expect(run.output).toContain("the repository's own function"); + expect(run.effects.served).toBe(0); + }); }); }); diff --git a/packages/web/tests/document.test.ts b/packages/web/tests/document.test.ts index 6344c3d4e..501d6e185 100644 --- a/packages/web/tests/document.test.ts +++ b/packages/web/tests/document.test.ts @@ -3,7 +3,7 @@ import { expect } from "@executablemd/test-support/expect"; import { scoped } from "effection"; import { readTextFile } from "@effectionx/fs"; import { collect, execute, registerComponents, useTempFileCompiler } from "@executablemd/core"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { useTesting } from "@executablemd/testing"; import { fileURLToPath } from "node:url"; @@ -24,53 +24,60 @@ const DOCUMENT = fileURLToPath(new URL("../src/WebForm.test.md", import.meta.url * is not coming. */ describe("WebForm.test.md", () => { - it("passes with an installed responder answering its forms", function* () { - const source = yield* readTextFile(DOCUMENT); + const name = "passes with an installed responder answering its forms"; + it(name, () => + captureTestJournal( + { owner: "packages/web/tests/document.test.ts", name }, + "WebForm.test.md", + function* (stream) { + const source = yield* readTextFile(DOCUMENT); - const outcome = yield* scoped(function* () { - yield* useTempFileCompiler(); - yield* useStubFs({ "WebForm.test.md": source }); + const outcome = yield* scoped(function* () { + yield* useTempFileCompiler(); + yield* useStubFs({ "WebForm.test.md": source }); - yield* FormAssets.around({ - // deno-lint-ignore require-yield - *assets() { - return { clientJs: "/* fixture */", themeCss: "/* fixture */" }; - }, - }); - yield* FormOpener.around({ - // deno-lint-ignore require-yield - *open() {}, - }); - yield* FormResponder.around({ - *respond([url]) { - yield* submitForm(url, { decision: "approve", note: "looks right" }); - }, - }); + yield* FormAssets.around({ + // deno-lint-ignore require-yield + *assets() { + return { clientJs: "/* fixture */", themeCss: "/* fixture */" }; + }, + }); + yield* FormOpener.around({ + // deno-lint-ignore require-yield + *open() {}, + }); + yield* FormResponder.around({ + *respond([url]) { + yield* submitForm(url, { decision: "approve", note: "looks right" }); + }, + }); - yield* useTesting(); - yield* registerComponents([ - { - name: "WebForm", - origin: "@executablemd/web", - fn: WebForm, - props: WEB_FORM_PROPS, - returns: WEB_FORM_RETURNS, - }, - ]); + yield* useTesting(); + yield* registerComponents([ + { + name: "WebForm", + origin: "@executablemd/web", + fn: WebForm, + props: WEB_FORM_PROPS, + returns: WEB_FORM_RETURNS, + }, + ]); - const execution = yield* execute({ - path: "WebForm.test.md", - stream: new InMemoryStream(), - }); + const execution = yield* execute({ + path: "WebForm.test.md", + stream, + }); - try { - yield* collect(execution); - return { ok: true, message: "" }; - } catch (error) { - return { ok: false, message: error instanceof Error ? error.message : String(error) }; - } - }); + try { + yield* collect(execution); + return { ok: true, message: "" }; + } catch (error) { + return { ok: false, message: error instanceof Error ? error.message : String(error) }; + } + }); - expect(outcome).toEqual({ ok: true, message: "" }); - }); + expect(outcome).toEqual({ ok: true, message: "" }); + }, + ), + ); }); From e9aef6f25d7142033ecf22a0727cfba686ac473f Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 13:35:58 -0500 Subject: [PATCH 04/78] test: capture failure journals for held Core hosts --- .../tests/component-invocation-hooks.test.ts | 280 ++++----- .../core/tests/generated-xmd-root.test.ts | 110 ++-- .../core/tests/host-generated-root.test.ts | 531 +++++++++++------- packages/core/tests/support/held-host.ts | 12 + 4 files changed, 531 insertions(+), 402 deletions(-) diff --git a/packages/core/tests/component-invocation-hooks.test.ts b/packages/core/tests/component-invocation-hooks.test.ts index 4a32981df..8360c357b 100644 --- a/packages/core/tests/component-invocation-hooks.test.ts +++ b/packages/core/tests/component-invocation-hooks.test.ts @@ -20,7 +20,9 @@ import type { IdentityComponent, } from "../host.ts"; import { retainedSource } from "../src/root-source.ts"; -import { useHeldHost } from "./support/held-host.ts"; +import { heldHostCases, useHeldHost } from "./support/held-host.ts"; + +const heldHostCase = heldHostCases("packages/core/tests/component-invocation-hooks.test.ts"); const props = { type: "object", properties: {}, additionalProperties: false }; function declaration(body: () => Operation, name = "Observed"): IdentityComponent { @@ -39,145 +41,153 @@ function* text(): Operation { } describe("Installation-owned component observation", () => { - it("R4a/R6: preserves dual-form dispatch, generated identity and accepted values", function* () { - const events: string[] = []; - const observations: ComponentInvocationObservation[] = []; - const values: unknown[] = []; - const names: string[] = []; - let projected = 0; - const component: IdentityComponent = { - name: "Observed", - origin: "test://observation", - props: { - type: "object", - properties: { - nested: { - type: "object", - properties: { label: { type: "string", default: "default" } }, - additionalProperties: false, + heldHostCase( + "R4a/R6: preserves dual-form dispatch, generated identity and accepted values", + function* (stream) { + const events: string[] = []; + const observations: ComponentInvocationObservation[] = []; + const values: unknown[] = []; + const names: string[] = []; + let projected = 0; + const component: IdentityComponent = { + name: "Observed", + origin: "test://observation", + props: { + type: "object", + properties: { + nested: { + type: "object", + properties: { label: { type: "string", default: "default" } }, + additionalProperties: false, + }, }, + additionalProperties: false, }, - additionalProperties: false, - }, - captures: ["raw"], - returns: { - type: "object", - properties: { form: { type: "string" }, accepted: { type: "boolean", default: true } }, - required: ["form", "accepted"], - additionalProperties: false, - }, - forms: ["self-closing", "paired"], - generated: { - "self-closing": { identity: "https://executable.md/test/observed/read", effect: "read" }, - paired: { identity: "https://executable.md/test/observed/write", effect: "write" }, - }, - factory(claim) { - function body(form: string) { - return function* (input: Record, invocation: Parameters[0]) { - const name = yield* claim(invocation); - names.push(name); - if (form === "write") { - yield* content(); - } - const nested = input.nested; - if (nested !== null && typeof nested === "object" && !Array.isArray(nested)) { - nested.label = "changed"; - } - yield createDurableOperation({ type: "observed", name }, function* () { - events.push(form); - return form; - }); - return { form }; + captures: ["raw"], + returns: { + type: "object", + properties: { form: { type: "string" }, accepted: { type: "boolean", default: true } }, + required: ["form", "accepted"], + additionalProperties: false, + }, + forms: ["self-closing", "paired"], + generated: { + "self-closing": { identity: "https://executable.md/test/observed/read", effect: "read" }, + paired: { identity: "https://executable.md/test/observed/write", effect: "write" }, + }, + factory(claim) { + function body(form: string) { + return function* ( + input: Record, + invocation: Parameters[0], + ) { + const name = yield* claim(invocation); + names.push(name); + if (form === "write") { + yield* content(); + } + const nested = input.nested; + if (nested !== null && typeof nested === "object" && !Array.isArray(nested)) { + nested.label = "changed"; + } + yield createDurableOperation({ type: "observed", name }, function* () { + events.push(form); + return form; + }); + return { form }; + }; + } + return formDispatcher({ + forms: "both", + "self-closing": body("read"), + paired: body("write"), + }); + }, + }; + const hooks: ComponentInvocationHooks = { + *before(observation) { + expect(projected).toBe(observations.length < 2 ? 0 : 1); + observations.push(observation); + expect(Object.isFrozen(observation)).toBe(true); + expect(Object.isFrozen(observation.props.nested)).toBe(true); + expect(observation.props).toEqual({ nested: { label: "default" } }); + yield* sleep(0); + }, + *after(observation, outcome, cancelled) { + expect(observations.includes(observation)).toBe(true); + expect(cancelled).toBe(false); + expect(observation.props).toEqual({ nested: { label: "default" } }); + if (outcome.ok) { + values.push(outcome.value); + } + yield* sleep(0); + }, + }; + const installation: ExecutionInstallation = { + components: [component], + componentInvocations: hooks, + *install() { + hooks.before = function* () { + throw new Error("late mutation"); }; - } - return formDispatcher({ - forms: "both", - "self-closing": body("read"), - paired: body("write"), - }); - }, - }; - const hooks: ComponentInvocationHooks = { - *before(observation) { - expect(projected).toBe(observations.length < 2 ? 0 : 1); - observations.push(observation); - expect(Object.isFrozen(observation)).toBe(true); - expect(Object.isFrozen(observation.props.nested)).toBe(true); - expect(observation.props).toEqual({ nested: { label: "default" } }); - yield* sleep(0); - }, - *after(observation, outcome, cancelled) { - expect(observations.includes(observation)).toBe(true); - expect(cancelled).toBe(false); - expect(observation.props).toEqual({ nested: { label: "default" } }); - if (outcome.ok) { - values.push(outcome.value); - } - yield* sleep(0); - }, - }; - const installation: ExecutionInstallation = { - components: [component], - componentInvocations: hooks, - *install() { - hooks.before = function* () { - throw new Error("late mutation"); - }; - hooks.after = hooks.before; - yield* registerComponents([ - { - name: "Projected", - origin: "test://projection", - props, - *fn() { - projected++; - yield* sleep(0); - return "content"; + hooks.after = hooks.before; + yield* registerComponents([ + { + name: "Projected", + origin: "test://projection", + props, + *fn() { + projected++; + yield* sleep(0); + return "content"; + }, }, - }, - ]); - yield* Component.around({ generated: () => ({ Observed: ["self-closing", "paired"] }) }); - }, - }; - const held = yield* useHeldHost({ - installations: [installation], - root: { - path: "hooks.md", + ]); + yield* Component.around({ generated: () => ({ Observed: ["self-closing", "paired"] }) }); + }, + }; + const held = yield* useHeldHost({ + stream, + installations: [installation], + root: { + path: "hooks.md", + source: + '\n\n', + }, + inside: function* () { + const caller = yield* Component.operations.env; + expect(caller?.values.inputs).toEqual({}); + expect(caller?.values.read).toEqual({ form: "read", accepted: true }); + expect(caller?.values.write).toEqual({ form: "write", accepted: true }); + }, + }); + expect(events).toEqual(["read", "write"]); + const evaluated = yield* held.execution.evaluateGeneratedXmdRoot({ + id: "dual", source: - '\n\n', - }, - inside: function* () { - const caller = yield* Component.operations.env; - expect(caller?.values.inputs).toEqual({}); - expect(caller?.values.read).toEqual({ form: "read", accepted: true }); - expect(caller?.values.write).toEqual({ form: "write", accepted: true }); - }, - }); - expect(events).toEqual(["read", "write"]); - const evaluated = yield* held.execution.evaluateGeneratedXmdRoot({ - id: "dual", - source: - '\nbody\n', - allow: ["read", "write"], - }); - expect(evaluated.ok).toBe(true); - expect(events).toEqual(["read", "write", "read", "write"]); - expect(values).toEqual([ - { form: "read", accepted: true }, - { form: "write", accepted: true }, - { form: "read", accepted: true }, - { form: "write", accepted: true }, - ]); - expect(new Set(names).size).toBe(4); - expect(new Set(observations).size).toBe(4); - const refused = yield* held.execution.evaluateGeneratedXmdRoot({ - id: "readonly", - source: 'body', - allow: ["read"], - }); - expect(refused.ok).toBe(false); - expect(events).toHaveLength(4); - }); + '\nbody\n', + allow: ["read", "write"], + }); + expect(evaluated.ok).toBe(true); + expect(events).toEqual(["read", "write", "read", "write"]); + expect(values).toEqual([ + { form: "read", accepted: true }, + { form: "write", accepted: true }, + { form: "read", accepted: true }, + { form: "write", accepted: true }, + ]); + expect(new Set(names).size).toBe(4); + expect(new Set(observations).size).toBe(4); + const refused = yield* held.execution.evaluateGeneratedXmdRoot({ + id: "readonly", + source: 'body', + allow: ["read"], + }); + expect(refused.ok).toBe(false); + expect(events).toHaveLength(4); + }, + "hooks.md", + ); it("R4b: independently optional callbacks and invalid inputs", function* () { for (const mode of ["none", "before", "after"]) { diff --git a/packages/core/tests/generated-xmd-root.test.ts b/packages/core/tests/generated-xmd-root.test.ts index d39c15f21..3939cf2de 100644 --- a/packages/core/tests/generated-xmd-root.test.ts +++ b/packages/core/tests/generated-xmd-root.test.ts @@ -52,7 +52,7 @@ import { Documentation } from "../src/documentation-api.ts"; import { Execution } from "../src/execute.ts"; import { retainedSource } from "../src/root-source.ts"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; -import { HELD_ROOT_PATH, withHeldHost } from "./support/held-host.ts"; +import { heldHostCases, HELD_ROOT_PATH, withHeldHost } from "./support/held-host.ts"; // Imported from the module rather than the host surface: there is no public // siteless evaluator, and these pinned factories are core-internal — the same // import main's own generated-xmd tier uses. @@ -73,6 +73,8 @@ import type { } from "../src/generated-xmd.ts"; import type { FunctionComponent, FunctionComponentDefinition, Json } from "../src/types.ts"; +const heldHostCase = heldHostCases("packages/core/tests/generated-xmd-root.test.ts"); + const ROOT_PATH = "repl/sidekick.md"; const ROOT_SOURCE = "The host evaluated a generated root.\n"; const URL_ONE = "https://api.example.test/one"; @@ -1767,55 +1769,59 @@ describe("993 generated nested roots", () => { describe("1178 generated root references and scope", () => { beforeAll(() => useTempFileCompiler()); - it("keeps root engine availability local across sibling roots and restores enclosing installed syntax", function* () { - const calls: string[] = []; - const names = ["If", "Output", "Content", "Return", "Banner", "BannerLine"]; - const named = ``; - const candidate = request(`${named}1178-ROOT`); - const run = yield* withHeldHost( - { - installations: [candidate.installation, syntaxInstallation(calls)], - root: { path: HELD_ROOT_PATH, source: `${named}` }, - }, - function* (held) { - const first = yield* held.execution.evaluateGeneratedXmdRoot(candidate.root); - if (!first.ok) { - throw first.error; - } - expect(first.value.output).toContain("1178-ROOT"); - for (const name of ["If", "Output"]) { - expectAvailability(first.value.output, name, true); - } - for (const name of ["Content", "Return", "Banner", "BannerLine"]) { - expectAvailability(first.value.output, name, false); - } - const second = yield* held.execution.evaluateGeneratedXmdRoot({ - id: "turn-2", - source: `{before}1178-CUT{reference}1178-CUT{after}`, - }); - if (!second.ok) { - throw second.error; - } - const [before, reference, after] = second.value.output.split("1178-CUT"); - expect(before).toBe(baseline1178["root-base.txt"]); - expect(after).toBe(baseline1178["root-base.txt"]); - expectAvailability(reference, "If", true); - const third = yield* held.execution.evaluateGeneratedXmdRoot({ - id: "turn-3", - source: "", - }); - if (!third.ok) { - throw third.error; - } - expect(third.value.output).toBe(baseline1178["root-base.txt"]); - }, - ); - if (!run.completion.ok) { - throw run.completion.error; - } - for (const name of names) { - expectAvailability(String(run.completion.value), name, true); - } - expect(calls).toEqual([]); - }); + heldHostCase( + "keeps root engine availability local across sibling roots and restores enclosing installed syntax", + function* (stream) { + const calls: string[] = []; + const names = ["If", "Output", "Content", "Return", "Banner", "BannerLine"]; + const named = ``; + const candidate = request(`${named}1178-ROOT`); + const run = yield* withHeldHost( + { + stream, + installations: [candidate.installation, syntaxInstallation(calls)], + root: { path: HELD_ROOT_PATH, source: `${named}` }, + }, + function* (held) { + const first = yield* held.execution.evaluateGeneratedXmdRoot(candidate.root); + if (!first.ok) { + throw first.error; + } + expect(first.value.output).toContain("1178-ROOT"); + for (const name of ["If", "Output"]) { + expectAvailability(first.value.output, name, true); + } + for (const name of ["Content", "Return", "Banner", "BannerLine"]) { + expectAvailability(first.value.output, name, false); + } + const second = yield* held.execution.evaluateGeneratedXmdRoot({ + id: "turn-2", + source: `{before}1178-CUT{reference}1178-CUT{after}`, + }); + if (!second.ok) { + throw second.error; + } + const [before, reference, after] = second.value.output.split("1178-CUT"); + expect(before).toBe(baseline1178["root-base.txt"]); + expect(after).toBe(baseline1178["root-base.txt"]); + expectAvailability(reference, "If", true); + const third = yield* held.execution.evaluateGeneratedXmdRoot({ + id: "turn-3", + source: "", + }); + if (!third.ok) { + throw third.error; + } + expect(third.value.output).toBe(baseline1178["root-base.txt"]); + }, + ); + if (!run.completion.ok) { + throw run.completion.error; + } + for (const name of names) { + expectAvailability(String(run.completion.value), name, true); + } + expect(calls).toEqual([]); + }, + ); }); diff --git a/packages/core/tests/host-generated-root.test.ts b/packages/core/tests/host-generated-root.test.ts index d235c195b..5fdc041c2 100644 --- a/packages/core/tests/host-generated-root.test.ts +++ b/packages/core/tests/host-generated-root.test.ts @@ -46,8 +46,14 @@ import { DurablePersistenceError, InMemoryStream, createDurableOperation, + parseDurableEvent, } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; +import { exists, readdir, readTextFile } from "@effectionx/fs"; +import { API } from "@executablemd/runtime"; +import { useTempDirectory } from "@executablemd/test-support/temp"; +import { join } from "node:path"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { contributeDocumentation, Documentation } from "../src/documentation-api.ts"; import { registerComponents } from "../src/components/registration.ts"; @@ -55,7 +61,7 @@ import { durabilityFailure } from "../src/errors.ts"; import { Execution, execute } from "../src/execute.ts"; import { retainedSource } from "../src/root-source.ts"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; -import { HELD_ROOT_PATH, useHeldHost, withHeldHost } from "./support/held-host.ts"; +import { heldHostCases, HELD_ROOT_PATH, useHeldHost, withHeldHost } from "./support/held-host.ts"; import * as hostModule from "../host.ts"; import { executeInstalled, HostExecutionError } from "../host.ts"; // The request and the class it names are taken from the trusted host @@ -73,6 +79,74 @@ import type { Json } from "../src/types.ts"; import type { FunctionComponent } from "../src/types.ts"; import { formDispatcher } from "../src/invocation-identity.ts"; +const OWNER = "packages/core/tests/host-generated-root.test.ts"; +const heldHostCase = heldHostCases(OWNER); + +describe("held host failure journal", () => { + const name = "saves the held root after cleanup and an enclosing assertion failure"; + it(name, function* () { + const root = yield* useTempDirectory("xmd-held-journal-"); + const failure = new Error("post-execution assertion"); + function attempt(artifacts: string, check: () => void): Operation { + return scoped(function* () { + yield* API.Env.around({ + *env([variable], next) { + return variable === "XMD_TEST_ARTIFACTS" ? artifacts : yield* next(variable); + }, + }); + yield* captureTestJournal({ owner: OWNER, name }, HELD_ROOT_PATH, function* (stream) { + let cleaned = false; + const run = yield* withHeldHost( + { + stream, + *inside() { + yield* ensure(() => { + cleaned = true; + }); + }, + }, + function* (held) { + yield* held.started; + }, + ); + expect(run.completion.ok).toBe(true); + expect(cleaned).toBe(true); + check(); + }); + }); + } + const passed = join(root, "passed"); + yield* attempt(passed, () => undefined); + expect(yield* exists(passed)).toBe(false); + + const failed = join(root, "failed"); + let caught: unknown; + try { + yield* attempt(failed, () => { + throw failure; + }); + } catch (error) { + caught = error; + } + expect(caught).toBe(failure); + const invocations = yield* readdir(failed); + expect(invocations).toHaveLength(1); + const directory = join(failed, invocations[0]); + expect(JSON.parse(yield* readTextFile(join(directory, "root-1.case.json")))).toEqual({ + owner: OWNER, + name, + kind: "root", + ordinal: 1, + source: HELD_ROOT_PATH, + }); + const lines = (yield* readTextFile(join(directory, "root-1.jsonl"))).trimEnd().split("\n"); + expect(parseDurableEvent(lines.at(-1) ?? "")).toMatchObject({ + ok: true, + value: { type: "close", coroutineId: "root" }, + }); + }); +}); + describe("Generated ordinary component identity", () => { it("captures installed forms and names their durable work without protected dispatch", function* () { const claimed: string[] = []; @@ -565,52 +639,55 @@ describe("Tier E3 — the documentation this execution captured", () => { expect(counted.reads).toBe(1); }); - it("E3b: late Documentation middleware in the document's own scope changes nothing", function* () { - const counted = { reads: 0 }; - const invoked: string[] = []; - const answer: { lookup?: Result } = {}; - - // Installed in an `Execution.document` wrapper: after canonical capture and - // before the document workflow, which is the scope the evaluation runner is - // attached inside. A recollection there *would* encounter this, so the row - // distinguishes a captured reference from one rebuilt at evaluation time. - // Middleware installed only in a sibling caller scope could not. - yield* Execution.around({ - *document([claimed], next) { - yield* Documentation.around({ - *contributions([read], nextChapter) { - const held = yield* nextChapter(read); - return held.map((one) => - one.source.owner === "@executablemd/test" - ? { - ...one, - source: { ...one.source, text: "## Marker\n\nSUBSTITUTED LATE.\n" }, - } - : one, - ); - }, - }); - yield* next(claimed); - }, - }); + heldHostCase( + "E3b: late Documentation middleware in the document's own scope changes nothing", + function* (stream) { + const counted = { reads: 0 }; + const invoked: string[] = []; + const answer: { lookup?: Result } = {}; + + // Installed in an `Execution.document` wrapper: after canonical capture and + // before the document workflow, which is the scope the evaluation runner is + // attached inside. A recollection there *would* encounter this, so the row + // distinguishes a captured reference from one rebuilt at evaluation time. + // Middleware installed only in a sibling caller scope could not. + yield* Execution.around({ + *document([claimed], next) { + yield* Documentation.around({ + *contributions([read], nextChapter) { + const held = yield* nextChapter(read); + return held.map((one) => + one.source.owner === "@executablemd/test" + ? { + ...one, + source: { ...one.source, text: "## Marker\n\nSUBSTITUTED LATE.\n" }, + } + : one, + ); + }, + }); + yield* next(claimed); + }, + }); - const run = yield* withHeldHost( - { installations: [markerPackage(MARKER_PROSE, counted), selecting([probe()])] }, - function* (open) { - answer.lookup = yield* open.execution.evaluateGeneratedXmdRoot( - request('\n\n\n', invoked), - ); - }, - ); + const run = yield* withHeldHost( + { stream, installations: [markerPackage(MARKER_PROSE, counted), selecting([probe()])] }, + function* (open) { + answer.lookup = yield* open.execution.evaluateGeneratedXmdRoot( + request('\n\n\n', invoked), + ); + }, + ); - expect(run.completion.ok).toBe(true); - const described = rendered(answer.lookup ?? { ok: false, error: new Error("none") }).output; - expect(described).toContain("THE MARKER CHAPTER."); - expect(described).not.toContain("SUBSTITUTED LATE."); - // No new collection happened, which is the mechanism rather than the - // symptom: the count is the same before and after the evaluation. - expect(counted.reads).toBe(1); - }); + expect(run.completion.ok).toBe(true); + const described = rendered(answer.lookup ?? { ok: false, error: new Error("none") }).output; + expect(described).toContain("THE MARKER CHAPTER."); + expect(described).not.toContain("SUBSTITUTED LATE."); + // No new collection happened, which is the mechanism rather than the + // symptom: the count is the same before and after the evaluation. + expect(counted.reads).toBe(1); + }, + ); it("E3c: two live executions each keep the capture they made", function* () { const mine = { reads: 0 }; @@ -918,67 +995,71 @@ describe("Tier E5 — cancelling joins before anything else starts", () => { ).toBe(false); }); - it("E5b: closing the execution joins a held evaluation before closure completes", function* () { - const order: string[] = []; - const reached = withResolvers(); - const release = withResolvers(); - const saved: { execution?: HostExecution } = {}; - const interrupted: { answer?: Result } = {}; - const invoked: string[] = []; - - yield* scoped(function* () { - const open = yield* useHeldHost({ - // The latch is resolved by the document element's own cleanup, which - // unwinds before the evaluation runner does. So the evaluation's - // cleanup is genuinely held at the moment closure begins, and it is the - // closing that frees it rather than this case pre-arranging the order. - *inside(): Operation { - yield* ensure(() => { - release.resolve(); - }); - }, - installations: [selecting([...declared(), holding(reached, release.operation, order)])], - }); - saved.execution = open.execution; - const running = yield* spawn(() => - open.execution.evaluateGeneratedXmdRoot({ - id: "turn-1", - source: "\n\n\n", - }), - ); - yield* reached.operation; - // Closing the execution: halting the handle's consumer takes the - // invocation down with it. - const closing = yield* spawn(function* () { - yield* open.watched.halt(); - order.push("closed"); + heldHostCase( + "E5b: closing the execution joins a held evaluation before closure completes", + function* (stream) { + const order: string[] = []; + const reached = withResolvers(); + const release = withResolvers(); + const saved: { execution?: HostExecution } = {}; + const interrupted: { answer?: Result } = {}; + const invoked: string[] = []; + + yield* scoped(function* () { + const open = yield* useHeldHost({ + stream, + // The latch is resolved by the document element's own cleanup, which + // unwinds before the evaluation runner does. So the evaluation's + // cleanup is genuinely held at the moment closure begins, and it is the + // closing that frees it rather than this case pre-arranging the order. + *inside(): Operation { + yield* ensure(() => { + release.resolve(); + }); + }, + installations: [selecting([...declared(), holding(reached, release.operation, order)])], + }); + saved.execution = open.execution; + const running = yield* spawn(() => + open.execution.evaluateGeneratedXmdRoot({ + id: "turn-1", + source: "\n\n\n", + }), + ); + yield* reached.operation; + // Closing the execution: halting the handle's consumer takes the + // invocation down with it. + const closing = yield* spawn(function* () { + yield* open.watched.halt(); + order.push("closed"); + }); + yield* closing; + interrupted.answer = yield* running; }); - yield* closing; - interrupted.answer = yield* running; - }); - // The held cleanup joined, and only then did closure complete. - expect(order).toEqual(["evaluation cleanup", "closed"]); - // The caller was told the execution closed rather than left waiting on an - // answer nothing was left to produce. - expect(interrupted.answer?.ok).toBe(false); - expect(interrupted.answer?.ok === false && interrupted.answer.error).toBeInstanceOf( - HostExecutionError, - ); - expect(interrupted.answer?.ok === false && interrupted.answer.error.message).toContain( - "closed while it was evaluating", - ); + // The held cleanup joined, and only then did closure complete. + expect(order).toEqual(["evaluation cleanup", "closed"]); + // The caller was told the execution closed rather than left waiting on an + // answer nothing was left to produce. + expect(interrupted.answer?.ok).toBe(false); + expect(interrupted.answer?.ok === false && interrupted.answer.error).toBeInstanceOf( + HostExecutionError, + ); + expect(interrupted.answer?.ok === false && interrupted.answer.error.message).toContain( + "closed while it was evaluating", + ); - const execution = saved.execution; - if (execution === undefined) { - throw new Error("the case never held an execution"); - } - const after = yield* execution.evaluateGeneratedXmdRoot( - request("\n\n\n", invoked), - ); - expect(after.ok).toBe(false); - expect(invoked).toEqual([]); - }); + const execution = saved.execution; + if (execution === undefined) { + throw new Error("the case never held an execution"); + } + const after = yield* execution.evaluateGeneratedXmdRoot( + request("\n\n\n", invoked), + ); + expect(after.ok).toBe(false); + expect(invoked).toEqual([]); + }, + ); }); describe("Tier E6 — reopening without replaying a response", () => { @@ -1242,29 +1323,32 @@ function failingMain(): NonNullable[number] describe("Tier E7 — which failures stay the run's", () => { beforeAll(() => useTempFileCompiler()); - it("E7a: an ordinary control failure is a Result carrying the real partial render", function* () { - const invoked: string[] = []; - const answer: { failed?: Result } = {}; + heldHostCase( + "E7a: an ordinary control failure is a Result carrying the real partial render", + function* (stream) { + const invoked: string[] = []; + const answer: { failed?: Result } = {}; - const run = yield* withHeldHost( - { installations: [selecting(declared(invoked))] }, - function* (open) { - answer.failed = yield* open.execution.evaluateGeneratedXmdRoot({ - id: "turn-1", - source: "\nbefore the failure\n\n\n\n", - }); - }, - ); + const run = yield* withHeldHost( + { stream, installations: [selecting(declared(invoked))] }, + function* (open) { + answer.failed = yield* open.execution.evaluateGeneratedXmdRoot({ + id: "turn-1", + source: "\nbefore the failure\n\n\n\n", + }); + }, + ); - // The request's own failure, so the execution is untouched by it. - expect(run.completion.ok).toBe(true); - expect(answer.failed?.ok).toBe(false); - const error: (Error & { partial?: GeneratedXmdRootResult }) | undefined = - answer.failed?.ok === false ? answer.failed.error : undefined; - expect(error?.message).toContain("the control refused this request"); - expect(error?.partial?.output).toContain("before the failure"); - expect(invoked).toEqual(["boomed"]); - }); + // The request's own failure, so the execution is untouched by it. + expect(run.completion.ok).toBe(true); + expect(answer.failed?.ok).toBe(false); + const error: (Error & { partial?: GeneratedXmdRootResult }) | undefined = + answer.failed?.ok === false ? answer.failed.error : undefined; + expect(error?.message).toContain("the control refused this request"); + expect(error?.partial?.output).toContain("before the failure"); + expect(invoked).toEqual(["boomed"]); + }, + ); it("E7b: a persistence failure stays itself, and the run does not succeed", function* () { const stream = new InMemoryStream(); @@ -1307,29 +1391,32 @@ describe("Tier E7 — which failures stay the run's", () => { expect(invoked).toEqual([]); }); - it("E7c: a teardown failure stays itself, and the run does not succeed", function* () { - const caught: { raised?: unknown; completion?: Result } = {}; + heldHostCase( + "E7c: a teardown failure stays itself, and the run does not succeed", + function* (stream) { + const caught: { raised?: unknown; completion?: Result } = {}; - yield* scoped(function* () { - const open = yield* useHeldHost({ installations: [selecting(declared())] }); - try { - yield* open.execution.evaluateGeneratedXmdRoot({ - id: "turn-1", - source: "\n\n\n", - }); - } catch (error) { - caught.raised = error; - } - open.release(); - caught.completion = yield* open.watched; - }); + yield* scoped(function* () { + const open = yield* useHeldHost({ stream, installations: [selecting(declared())] }); + try { + yield* open.execution.evaluateGeneratedXmdRoot({ + id: "turn-1", + source: "\n\n\n", + }); + } catch (error) { + caught.raised = error; + } + open.release(); + caught.completion = yield* open.watched; + }); - // Work the root owned did not finish unwinding, so a rendering reported - // beside it would describe a root still running. - expect(caught.raised).not.toBe(undefined); - expect(String((caught.raised as Error).message)).toContain("cleanup"); - expect(caught.completion?.ok).toBe(false); - }); + // Work the root owned did not finish unwinding, so a rendering reported + // beside it would describe a root still running. + expect(caught.raised).not.toBe(undefined); + expect(String((caught.raised as Error).message)).toContain("cleanup"); + expect(caught.completion?.ok).toBe(false); + }, + ); it("E7d: a fatal evaluation outranks the ordinary failure the document went on to have", function* () { const stream = new InMemoryStream(); @@ -1430,58 +1517,69 @@ describe("Tier E7 — which failures stay the run's", () => { expect(run.completion.ok).toBe(false); }); - it("E7f: an authoritative evaluation failure of no classified kind is still the run's", function* () { - const caught: { raised?: unknown } = {}; - - // A failed evaluation teardown is neither a durability nor a Files - // failure, so the classified tiers do not reach it — and the document - // fails afterwards for an ordinary reason of its own. Which of the two the - // completion reports is decided by occurrence, and the evaluation's came - // first. - const run = yield* withHeldHost( - { - root: { path: "host/ranking.md", source: "\n\n" }, - installations: [{ components: [failingMain()] }, selecting([probe(), failingCleanup()])], - }, - function* (open) { - try { - yield* open.execution.evaluateGeneratedXmdRoot({ - id: "turn-1", - source: "\n\n\n", - }); - } catch (error) { - caught.raised = error; - } - }, - ); - - // The object the caller was handed, not a rebuilt one carrying its words. - expect(caught.raised).toBeInstanceOf(Error); - expect(run.completion.ok).toBe(false); - expect(run.completion.ok ? undefined : run.completion.error).toBe(caught.raised); - }); + heldHostCase( + "E7f: an authoritative evaluation failure of no classified kind is still the run's", + function* (stream) { + const caught: { raised?: unknown } = {}; + + // A failed evaluation teardown is neither a durability nor a Files + // failure, so the classified tiers do not reach it — and the document + // fails afterwards for an ordinary reason of its own. Which of the two the + // completion reports is decided by occurrence, and the evaluation's came + // first. + const run = yield* withHeldHost( + { + stream, + root: { path: "host/ranking.md", source: "\n\n" }, + installations: [{ components: [failingMain()] }, selecting([probe(), failingCleanup()])], + }, + function* (open) { + try { + yield* open.execution.evaluateGeneratedXmdRoot({ + id: "turn-1", + source: "\n\n\n", + }); + } catch (error) { + caught.raised = error; + } + }, + ); - it("E7g: the same failure is the run's when the document succeeded — by identity", function* () { - const caught: { raised?: unknown } = {}; + // The object the caller was handed, not a rebuilt one carrying its words. + expect(caught.raised).toBeInstanceOf(Error); + expect(run.completion.ok).toBe(false); + expect(run.completion.ok ? undefined : run.completion.error).toBe(caught.raised); + }, + "host/ranking.md", + ); - // The control for E7f. E7c already states that such a run does not report - // success; what this adds is that the completion is the *same* failure, so - // E7f's row is about ranking rather than about reporting one at all. - const run = yield* withHeldHost({ installations: [selecting(declared())] }, function* (open) { - try { - yield* open.execution.evaluateGeneratedXmdRoot({ - id: "turn-1", - source: "\n\n\n", - }); - } catch (error) { - caught.raised = error; - } - }); + heldHostCase( + "E7g: the same failure is the run's when the document succeeded — by identity", + function* (stream) { + const caught: { raised?: unknown } = {}; + + // The control for E7f. E7c already states that such a run does not report + // success; what this adds is that the completion is the *same* failure, so + // E7f's row is about ranking rather than about reporting one at all. + const run = yield* withHeldHost( + { stream, installations: [selecting(declared())] }, + function* (open) { + try { + yield* open.execution.evaluateGeneratedXmdRoot({ + id: "turn-1", + source: "\n\n\n", + }); + } catch (error) { + caught.raised = error; + } + }, + ); - expect(caught.raised).toBeInstanceOf(Error); - expect(run.completion.ok).toBe(false); - expect(run.completion.ok ? undefined : run.completion.error).toBe(caught.raised); - }); + expect(caught.raised).toBeInstanceOf(Error); + expect(run.completion.ok).toBe(false); + expect(run.completion.ok ? undefined : run.completion.error).toBe(caught.raised); + }, + ); }); /** @@ -1689,28 +1787,31 @@ describe("Tier E9 — an availability refusal is the call's answer", () => { * evaluator lives in, so the four decided members and the class name the * request uses are checked at the published boundary. */ - it("E9d: the public request is the four-member shape, typed through core/host", function* () { - const invoked: string[] = []; - const classes: readonly GeneratedEffectClass[] = ["read"]; - const asked: GeneratedXmdRequest = { - id: "turn-1", - source: "\n\n\n", - allow: classes, - position: { line: 1, column: 1, offset: 0 }, - }; - const answer: { value?: Result } = {}; - const run = yield* withHeldHost( - { installations: [selecting([probe(invoked)])] }, - function* (open) { - answer.value = yield* open.execution.evaluateGeneratedXmdRoot(asked); - }, - ); + heldHostCase( + "E9d: the public request is the four-member shape, typed through core/host", + function* (stream) { + const invoked: string[] = []; + const classes: readonly GeneratedEffectClass[] = ["read"]; + const asked: GeneratedXmdRequest = { + id: "turn-1", + source: "\n\n\n", + allow: classes, + position: { line: 1, column: 1, offset: 0 }, + }; + const answer: { value?: Result } = {}; + const run = yield* withHeldHost( + { stream, installations: [selecting([probe(invoked)])] }, + function* (open) { + answer.value = yield* open.execution.evaluateGeneratedXmdRoot(asked); + }, + ); - expect(run.completion.ok).toBe(true); - expect(rendered(answer.value ?? { ok: false, error: new Error("none") }).output).toContain( - "probed", - ); - }); + expect(run.completion.ok).toBe(true); + expect(rendered(answer.value ?? { ok: false, error: new Error("none") }).output).toContain( + "probed", + ); + }, + ); }); describe("R6 — generated ordinary identity remains execution-owned", () => { diff --git a/packages/core/tests/support/held-host.ts b/packages/core/tests/support/held-host.ts index 1dd8cb2b8..c13a110e1 100644 --- a/packages/core/tests/support/held-host.ts +++ b/packages/core/tests/support/held-host.ts @@ -24,6 +24,8 @@ import { executeInstalled } from "../../host.ts"; import type { ExecutionInstallation, HostExecution } from "../../host.ts"; import { retainedSource } from "../../src/root-source.ts"; import type { Json } from "../../src/types.ts"; +import { it } from "@executablemd/test-support/bdd"; +import { captureTestJournal } from "../../../test-support/failure-journal.ts"; const NO_PROPS = { type: "object", properties: {}, additionalProperties: false } as const; @@ -34,6 +36,16 @@ const HOLD_COMPONENT = "Held"; export const HELD_ROOT_PATH = "host/held.md"; const HELD_ROOT_SOURCE = `<${HOLD_COMPONENT} />\n`; +export function heldHostCases(owner: string) { + return ( + name: string, + body: (stream: InMemoryStream) => Operation, + source = HELD_ROOT_PATH, + ): void => { + it(name, () => captureTestJournal({ owner, name }, source, body)); + }; +} + /** The document a held execution runs, for a case that needs its own. */ export interface HeldRoot { readonly path: string; From 72a360f6ab618cc66e381dd3337c39ae34476dc9 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 13:49:26 -0500 Subject: [PATCH 05/78] test: retain the ORC12 child journal for parent failures --- .../git/tests/run-composition-managed.test.ts | 176 ++++++++++++++++-- .../tests/support/run-composition-child.ts | 21 ++- 2 files changed, 177 insertions(+), 20 deletions(-) diff --git a/packages/git/tests/run-composition-managed.test.ts b/packages/git/tests/run-composition-managed.test.ts index e4c8ccd96..6329d9397 100644 --- a/packages/git/tests/run-composition-managed.test.ts +++ b/packages/git/tests/run-composition-managed.test.ts @@ -15,7 +15,14 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { scoped, type Operation } from "effection"; -import { exists, readTextFile, rm, writeTextFile } from "@effectionx/fs"; +import { exists, readdir, readTextFile, rm, writeTextFile } from "@effectionx/fs"; +import { API } from "@executablemd/runtime"; +import { parseDurableEvent } from "@executablemd/durable-streams"; +import type { DurableEvent } from "@executablemd/durable-streams"; +import { useTempDirectory } from "@executablemd/test-support/temp"; +import { withFailureJournal } from "@executablemd/testing"; +import { useTestDiagnostics } from "../../cli/src/test-diagnostics.ts"; +import { join } from "node:path"; import { git, useBareRemote } from "./support/git-remotes.ts"; import { spawnSync } from "node:child_process"; import process from "node:process"; @@ -39,6 +46,7 @@ import { useManagedRoot, worktreeSlotOf, type HostCheckout, + type ManagedSlot, } from "./support/run-composition.ts"; import { CHILD, REMOTE, entriesOf, isManagedRefusal } from "./support/run-composition-tier.ts"; @@ -509,19 +517,77 @@ describe("ORC11 — an interrupted creation", () => { }); }); -describe("ORC12 — exclusive ownership across processes", () => { +const ORC12_SUITE = "ORC12 — exclusive ownership across processes"; +const OWNER = "packages/git/tests/run-composition-managed.test.ts"; + +function parseJournal(value: unknown): DurableEvent[] { + if (!Array.isArray(value)) { + return []; + } + const events: DurableEvent[] = []; + for (const record of value) { + if (typeof record !== "string") { + return []; + } + const parsed = parseDurableEvent(record); + if (!parsed.ok) { + return []; + } + events.push(parsed.value); + } + return events; +} + +describe(ORC12_SUITE, () => { /** One second process, run to completion, and what it reported. */ - function* elsewhere(root: string, cwd: string, source: string): Operation { + function* elsewhere( + root: string, + cwd: string, + source: string, + capture = false, + ): Operation & { events: DurableEvent[] }> { const outcome = spawnSync( process.execPath, - ["run", "--allow-all", "--frozen", CHILD, root, cwd, source], + [ + "run", + "--allow-all", + "--frozen", + CHILD, + root, + cwd, + source, + ...(capture ? ["--capture-journal"] : []), + ], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }, ); - const printed = outcome.stdout.trim().split("\n").at(-1) ?? ""; - if (printed === "") { - throw new Error(`the child printed nothing: ${outcome.stderr}`); + const printed = outcome.stdout?.trim().split("\n").at(-1); + if (outcome.status !== 0 || !printed) { + throw new Error( + `the checkout fixture returned no successful result (exit ${outcome.status})`, + ); } - return JSON.parse(printed) as ChildOutcome; + let result: unknown; + try { + result = JSON.parse(printed); + } catch { + throw new Error("the checkout fixture result is invalid JSON"); + } + if ( + typeof result !== "object" || + result === null || + !("kind" in result) || + (result.kind !== "selected" && result.kind !== "refused" && result.kind !== "failed") + ) { + throw new Error("the checkout fixture result has an invalid kind"); + } + return { + kind: result.kind, + bound: "bound" in result && typeof result.bound === "string" ? result.bound : undefined, + reason: "reason" in result && typeof result.reason === "string" ? result.reason : undefined, + message: + "message" in result && typeof result.message === "string" ? result.message : undefined, + events: capture && "journal" in result ? parseJournal(result.journal) : [], + }; } it("refuses a second process the slot a first is holding, and changes nothing", function* () { @@ -565,6 +631,7 @@ describe("ORC12 — exclusive ownership across processes", () => { expect(refused.kind).toBe("refused"); expect(refused.reason).toBe("in-use"); expect(refused.message).toContain("another process is working in"); + expect(refused.events).toEqual([]); // And nothing under the slot moved. expect(yield* fingerprintTree(held.slot)).toEqual(bytes); @@ -590,7 +657,15 @@ describe("ORC12 — exclusive ownership across processes", () => { expect(yield* exists(`${held.checkout}/held.md`)).toBe(true); }); - it("hands a slot on after a normal release, with the checkout intact", function* () { + function* checkSerialSidecar(slot: ManagedSlot): Operation { + expect(yield* readSidecar(slot)).toMatchObject({ kind: "worktree", name: "serial" }); + } + + function* normalRelease( + name: string, + check: (slot: ManagedSlot, records: readonly DurableEvent[]) => Operation, + artifacts?: string, + ): Operation { const remote = yield* useBareRemote(REMOTE); const root = yield* useManagedRoot(); const checkout = yield* useHostCheckout(remote.locator); @@ -601,11 +676,84 @@ describe("ORC12 — exclusive ownership across processes", () => { const bound = yield* runOrdinaryDocument(document, { root, cwd: checkout.root }); expect(String(bound).trim()).toBe(slot.checkout); - // A real second process then takes it, and finds the same checkout. - const later = yield* elsewhere(root, checkout.root, document); - expect(later.kind).toBe("selected"); - expect(later.bound).toBe(slot.checkout); - expect(yield* readSidecar(slot)).toMatchObject({ kind: "worktree", name: "serial" }); + yield* scoped(function* () { + if (artifacts !== undefined) { + yield* API.Env.around({ + *env([variable], next) { + return variable === "XMD_TEST_ARTIFACTS" ? artifacts : yield* next(variable); + }, + }); + } + const diagnostics = yield* useTestDiagnostics(process.stderr, { + owner: OWNER, + suite: ORC12_SUITE, + name, + }); + yield* withFailureJournal( + diagnostics.execution("child", "").journal(() => false), + function* (buffer) { + // The real second process takes the same checkout. Its result is available after exit. + const later = yield* elsewhere(root, checkout.root, document, true); + for (const event of later.events) { + yield* buffer.append(event); + } + expect(later.kind).toBe("selected"); + expect(later.bound).toBe(slot.checkout); + yield* check(slot, later.events); + }, + ); + }); + } + + const normalCase = "hands a slot on after a normal release, with the checkout intact"; + it(normalCase, () => normalRelease(normalCase, checkSerialSidecar)); + + const witness = "attributes the child journal when the post-exit sidecar assertion fails"; + it(witness, function* () { + const root = yield* useTempDirectory("xmd-orc12-failure-"); + const success = join(root, "passed", ".xmd", "test-artifacts"); + yield* normalRelease(witness, checkSerialSidecar, success); + expect(yield* exists(success)).toBe(false); + const artifacts = join(root, ".xmd", "test-artifacts"); + let received: readonly DurableEvent[] = []; + let assertion: unknown; + let caught: unknown; + try { + yield* normalRelease( + witness, + function* (slot, records) { + received = records; + yield* rm(slot.metadata); + try { + yield* checkSerialSidecar(slot); + } catch (error) { + assertion = error; + throw error; + } + }, + artifacts, + ); + } catch (error) { + caught = error; + } + expect(assertion).toBeInstanceOf(Error); + expect(caught).toBe(assertion); + const invocations = yield* readdir(artifacts); + expect(invocations).toHaveLength(1); + const directory = join(artifacts, invocations[0]); + expect((yield* readdir(directory)).sort()).toEqual(["child-1.case.json", "child-1.jsonl"]); + expect(JSON.parse(yield* readTextFile(join(directory, "child-1.case.json")))).toEqual({ + owner: OWNER, + suite: ORC12_SUITE, + name: witness, + kind: "child", + ordinal: 1, + source: "", + }); + const lines = (yield* readTextFile(join(directory, "child-1.jsonl"))).trimEnd().split("\n"); + const events = parseJournal(lines); + expect(events).toEqual(received); + expect(events.at(-1)).toMatchObject({ type: "close", coroutineId: "root" }); }); }); diff --git a/packages/git/tests/support/run-composition-child.ts b/packages/git/tests/support/run-composition-child.ts index f894dbea5..5cb9e57e5 100644 --- a/packages/git/tests/support/run-composition-child.ts +++ b/packages/git/tests/support/run-composition-child.ts @@ -13,7 +13,8 @@ import { main } from "effection"; import process from "node:process"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import { Buffer } from "node:buffer"; +import { InMemoryStream, serializeDurableEvent } from "@executablemd/durable-streams"; import { collect, execute, inlineSource } from "@executablemd/core"; import { API, useHostFiles } from "@executablemd/runtime"; import { useCompositionComponents } from "../../src/composition/installation.ts"; @@ -28,14 +29,16 @@ export interface ChildOutcome { /** The fixed word a managed-checkout refusal is reported under. */ readonly reason?: string; readonly message?: string; + readonly journal?: readonly string[]; } await main(function* () { - const [root, cwd, source] = process.argv.slice(2); + const [root, cwd, source, capture] = process.argv.slice(2); if (root === undefined || cwd === undefined || source === undefined) { throw new Error("the child needs a managed root, a starting directory and a document"); } + const stream = new InMemoryStream(); let outcome: ChildOutcome; try { const rendered = yield* (function* () { @@ -51,9 +54,7 @@ await main(function* () { yield* useHostFiles(); yield* useCompositionComponents(); yield* useRunComposition({ root, cwd }); - return yield* collect( - yield* execute({ ...inlineSource(source), stream: new InMemoryStream() }), - ); + return yield* collect(yield* execute({ ...inlineSource(source), stream })); })(); outcome = { kind: "selected", bound: String(rendered).trim() }; } catch (error) { @@ -64,7 +65,15 @@ await main(function* () { : { kind: "refused", reason: refusal.reason, message: refusal.message }; } - process.stdout.write(`${JSON.stringify(outcome)}\n`); + let line = `${JSON.stringify(outcome)}\n`; + if (capture === "--capture-journal") { + const journal = (yield* stream.readAll()).map(serializeDurableEvent); + const enriched = `${JSON.stringify({ ...outcome, journal })}\n`; + if (Buffer.byteLength(enriched) <= 64 * 1024) { + line = enriched; + } + } + process.stdout.write(line); }); /** The managed-checkout refusal in this error's chain, if there is one. */ From d6398b9b86ecc34fe709c025194766c35ea61738 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 13:53:23 -0500 Subject: [PATCH 06/78] test: attribute journals in ordinary Git execution cases --- .../git/tests/git-observations-deno.test.ts | 208 ++--- packages/git/tests/git-observations.test.ts | 834 +++++++++--------- .../git/tests/run-composition-ambient.test.ts | 615 +++++++------ .../git/tests/run-composition-managed.test.ts | 284 +++--- .../git/tests/run-composition-remote.test.ts | 150 ++-- packages/git/tests/support/run-composition.ts | 26 +- 6 files changed, 1124 insertions(+), 993 deletions(-) diff --git a/packages/git/tests/git-observations-deno.test.ts b/packages/git/tests/git-observations-deno.test.ts index 67a29ba03..58d4ede7a 100644 --- a/packages/git/tests/git-observations-deno.test.ts +++ b/packages/git/tests/git-observations-deno.test.ts @@ -36,7 +36,7 @@ import process from "node:process"; import type { Json } from "@executablemd/durable-streams"; import { capturingProbe, writeFixtureFile } from "./support/observations.ts"; import { - runOrdinaryDocument, + ordinaryDocumentCases, useHostCheckout, useManagedRoot, useOriginlessCheckout, @@ -44,6 +44,8 @@ import { import { useBareRemote } from "./support/git-remotes.ts"; import { REMOTE } from "./support/run-composition-tier.ts"; import { denoRepositoryHost } from "../src/deno/composition/host.ts"; + +const ordinaryCase = ordinaryDocumentCases("packages/git/tests/git-observations-deno.test.ts"); import type { GitBytes, GitInvocation, @@ -68,58 +70,61 @@ function paths(value: Json | undefined): string[] { } describe("GO9 — which checkout answers, through a managed selection", () => { - it("reads the ambient checkout, a lexical Repository, a Worktree and a Dir inside one", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const ambient = yield* useHostCheckout(remote.locator); - yield* writeFixtureFile(ambient.root, "only-here.txt", "ambient\n"); - ambient.run("add", "--", "only-here.txt"); - ambient.run("commit", "-m", "ambient only"); - const seen: Json[] = []; + ordinaryCase( + "reads the ambient checkout, a lexical Repository, a Worktree and a Dir inside one", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const ambient = yield* useHostCheckout(remote.locator); + yield* writeFixtureFile(ambient.root, "only-here.txt", "ambient\n"); + ambient.run("add", "--", "only-here.txt"); + ambient.run("commit", "-m", "ambient only"); + const seen: Json[] = []; - yield* runOrdinaryDocument( - [ - '', - "", - "", - "", - ``, - "", - '', - "", - "", - "", - '', - "", - '', - "", - "", - "", - '', - "", - '', - "", - "", - "", - "", - "", - "", - "", - "", - "", - ].join("\n"), - { root, cwd: ambient.root, components: [capturingProbe(seen)] }, - ); + yield* runFresh( + [ + '', + "", + "", + "", + ``, + "", + '', + "", + "", + "", + '', + "", + '', + "", + "", + "", + '', + "", + '', + "", + "", + "", + "", + "", + "", + "", + "", + "", + ].join("\n"), + { root, cwd: ambient.root, components: [capturingProbe(seen)] }, + ); - // The ambient checkout holds a path the managed clone never received, which - // is how a read that answered from the wrong one would say so. - expect(paths(seen[0])).toContain("only-here.txt"); - expect(paths(seen[1])).toEqual(["which.txt"]); - expect(object(seen[2]).changes).toEqual([]); - // A `` beneath a Worktree stays inside that checkout, and the answer - // is still relative to its repository root. - expect(paths(seen[3])).toEqual(["which.txt"]); - }); + // The ambient checkout holds a path the managed clone never received, which + // is how a read that answered from the wrong one would say so. + expect(paths(seen[0])).toContain("only-here.txt"); + expect(paths(seen[1])).toEqual(["which.txt"]); + expect(object(seen[2]).changes).toEqual([]); + // A `` beneath a Worktree stays inside that checkout, and the answer + // is still relative to its repository root. + expect(paths(seen[3])).toEqual(["which.txt"]); + }, + ); }); /** What a watched `git` child reported about its own lifetime. */ @@ -222,57 +227,60 @@ function watchingHost( } describe("GO9 — what an interrupted native read leaves behind", () => { - it("joins the read's own child and removes its scratch before settling", function* () { - const checkout = yield* useOriginlessCheckout(); - const root = yield* useManagedRoot(); - yield* writeFixtureFile(checkout.root, "src/a.ts", "export const a = 1;\n"); - checkout.run("add", "--", "src/a.ts"); - checkout.run("commit", "-m", "a"); - yield* writeFixtureFile(checkout.root, "src/a.ts", "export const a = 11;\n"); + ordinaryCase( + "joins the read's own child and removes its scratch before settling", + function* (runFresh) { + const checkout = yield* useOriginlessCheckout(); + const root = yield* useManagedRoot(); + yield* writeFixtureFile(checkout.root, "src/a.ts", "export const a = 1;\n"); + checkout.run("add", "--", "src/a.ts"); + checkout.run("commit", "-m", "a"); + yield* writeFixtureFile(checkout.root, "src/a.ts", "export const a = 11;\n"); - const watched = watchChildren(); - const scratch: string[] = []; - const marker = join(checkout.home, "read-ran"); - const script = join(checkout.home, "waiting-fsmonitor"); - yield* waitingScript(script, marker); + const watched = watchChildren(); + const scratch: string[] = []; + const marker = join(checkout.home, "read-ran"); + const script = join(checkout.home, "waiting-fsmonitor"); + yield* waitingScript(script, marker); - // The comparison refreshes the index before it answers, and a file-system - // monitor is consulted while it does. This one reports that it ran and then - // waits, holding the pipes the parent inherited — which is what makes the - // cut land on a real child rather than between commands. - const intercept = (invocation: GitInvocation): Partial | undefined => - invocation.args.includes("diff") - ? { - args: ["-c", `core.fsmonitor=${script}`, ...invocation.args], - observe: watched.observe, - } - : undefined; + // The comparison refreshes the index before it answers, and a file-system + // monitor is consulted while it does. This one reports that it ran and then + // waits, holding the pipes the parent inherited — which is what makes the + // cut land on a real child rather than between commands. + const intercept = (invocation: GitInvocation): Partial | undefined => + invocation.args.includes("diff") + ? { + args: ["-c", `core.fsmonitor=${script}`, ...invocation.args], + observe: watched.observe, + } + : undefined; - yield* scoped(function* () { - const task = yield* spawn(() => - runOrdinaryDocument( - [ - '', - 'sentinel', - ].join("\n"), - { root, cwd: checkout.root, host: watchingHost(scratch, intercept) }, - ), - ); - // The marker says the descendant really ran and is holding the pipes. - yield* appears(marker); - yield* watched.spawned; - yield* task.halt(); - }); + yield* scoped(function* () { + const task = yield* spawn(() => + runFresh( + [ + '', + 'sentinel', + ].join("\n"), + { root, cwd: checkout.root, host: watchingHost(scratch, intercept) }, + ), + ); + // The marker says the descendant really ran and is holding the pipes. + yield* appears(marker); + yield* watched.spawned; + yield* task.halt(); + }); - // The child is gone and both its pipes have ended; the scratch the read - // owned is gone with it; and nothing after the read ran. - expect(watched.observed() > 0).toBe(true); - expect(watched.closed()).toBe(true); - expect(watched.alive()).toBe(false); - expect(scratch.length > 0).toBe(true); - for (const directory of scratch) { - expect(yield* exists(directory)).toBe(false); - } - expect(yield* exists(join(checkout.root, "sentinel.md"))).toBe(false); - }); + // The child is gone and both its pipes have ended; the scratch the read + // owned is gone with it; and nothing after the read ran. + expect(watched.observed() > 0).toBe(true); + expect(watched.closed()).toBe(true); + expect(watched.alive()).toBe(false); + expect(scratch.length > 0).toBe(true); + for (const directory of scratch) { + expect(yield* exists(directory)).toBe(false); + } + expect(yield* exists(join(checkout.root, "sentinel.md"))).toBe(false); + }, + ); }); diff --git a/packages/git/tests/git-observations.test.ts b/packages/git/tests/git-observations.test.ts index 78fb83332..802fad39e 100644 --- a/packages/git/tests/git-observations.test.ts +++ b/packages/git/tests/git-observations.test.ts @@ -56,6 +56,7 @@ import { writeFixtureFile, } from "./support/observations.ts"; import { + ordinaryDocumentCases, commonDirectoryOf, countingOrdinaryHost, raised, @@ -95,6 +96,8 @@ import type { import { denoRepositoryHost } from "../src/deno/composition/host.ts"; import type { GitInvocation, RepositoryHost } from "../src/deno/composition/host.ts"; import { performGitObservation } from "../src/deno/composition/observations.ts"; + +const ordinaryCase = ordinaryDocumentCases("packages/git/tests/git-observations.test.ts"); import type { ObservationPlace } from "../src/deno/composition/observations.ts"; /** @@ -387,12 +390,12 @@ function paths(value: Json | undefined): string[] { } describe("GO1 — discovery addresses the chosen repository", () => { - it("lists the tracked index paths and nothing else", function* () { + ordinaryCase("lists the tracked index paths and nothing else", function* (runFresh) { const root = yield* useManagedRoot(); const fixture = yield* useObservationFixture(); const seen: Json[] = []; - yield* runOrdinaryDocument( + yield* runFresh( ['', "", "", ""].join("\n"), { root, cwd: fixture.root, components: [capturingProbe(seen)] }, ); @@ -417,56 +420,62 @@ describe("GO1 — discovery addresses the chosen repository", () => { }); describe("GO2 — discovery excludes what the index does not hold", () => { - it("excludes untracked files, a nested checkout's contents and a sibling checkout", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useObservationFixture(); - yield* writeFixtureFile(fixture.root, "untracked.md", "not tracked\n"); - const seen: Json[] = []; - - yield* runOrdinaryDocument( - ['', "", "", ""].join("\n"), - { root, cwd: fixture.root, components: [capturingProbe(seen)] }, - ); + ordinaryCase( + "excludes untracked files, a nested checkout's contents and a sibling checkout", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useObservationFixture(); + yield* writeFixtureFile(fixture.root, "untracked.md", "not tracked\n"); + const seen: Json[] = []; + + yield* runFresh( + ['', "", "", ""].join("\n"), + { root, cwd: fixture.root, components: [capturingProbe(seen)] }, + ); - const listed = paths(seen[0]); - expect(listed).not.toContain("untracked.md"); - // The tracked gitlink is one path. Nothing beneath it, and nothing in the - // untracked checkout beside it, is a path this repository's index holds. - expect(listed).toContain("nested"); - expect(listed.filter((path) => path.startsWith("nested/"))).toEqual([]); - expect(listed.filter((path) => path.startsWith("scratch-repo"))).toEqual([]); - }); + const listed = paths(seen[0]); + expect(listed).not.toContain("untracked.md"); + // The tracked gitlink is one path. Nothing beneath it, and nothing in the + // untracked checkout beside it, is a path this repository's index holds. + expect(listed).toContain("nested"); + expect(listed.filter((path) => path.startsWith("nested/"))).toEqual([]); + expect(listed.filter((path) => path.startsWith("scratch-repo"))).toEqual([]); + }, + ); - it("matches prefix literally and answers root-relative paths from a subdirectory", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useObservationFixture(); - const seen: Json[] = []; + ordinaryCase( + "matches prefix literally and answers root-relative paths from a subdirectory", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useObservationFixture(); + const seen: Json[] = []; - yield* runOrdinaryDocument( - [ - '', - "", - '', - "", - "", - "", - "", - "", - ].join("\n"), - { root, cwd: fixture.root, components: [capturingProbe(seen)] }, - ); + yield* runFresh( + [ + '', + "", + '', + "", + "", + "", + "", + "", + ].join("\n"), + { root, cwd: fixture.root, components: [capturingProbe(seen)] }, + ); - // An incomplete final segment is a prefix, and the answer is relative to - // the repository root rather than to the directory the element was in. - expect(paths(seen[0])).toEqual(["src/a.ts", "src/added.ts"]); - }); + // An incomplete final segment is a prefix, and the answer is relative to + // the repository root rather than to the directory the element was in. + expect(paths(seen[0])).toEqual(["src/a.ts", "src/added.ts"]); + }, + ); - it("reads a prefix holding glob characters as those characters", function* () { + ordinaryCase("reads a prefix holding glob characters as those characters", function* (runFresh) { const root = yield* useManagedRoot(); const fixture = yield* useObservationFixture(); const seen: Json[] = []; - yield* runOrdinaryDocument( + yield* runFresh( [ ``, "", @@ -481,12 +490,12 @@ describe("GO2 — discovery excludes what the index does not hold", () => { }); describe("GO3 — the three comparisons", () => { - it("compares two commits with every status the fixture produces", function* () { + ordinaryCase("compares two commits with every status the fixture produces", function* (runFresh) { const root = yield* useManagedRoot(); const fixture = yield* useObservationFixture(); const seen: Json[] = []; - yield* runOrdinaryDocument( + yield* runFresh( [ ``, "", @@ -514,38 +523,41 @@ describe("GO3 — the three comparisons", () => { expect(result.next).toBe(null); }); - it("compares the index with the working tree, and HEAD with the index", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useObservationFixture(); - yield* writeFixtureFile(fixture.root, "src/a.ts", "export const a = 2;\n"); - yield* writeFixtureFile(fixture.root, "staged.ts", "export const staged = true;\n"); - fixture.run("add", "--", "staged.ts"); - yield* writeFixtureFile(fixture.root, "untracked.md", "not tracked\n"); - const seen: Json[] = []; - - yield* runOrdinaryDocument( - [ - '', - "", - "", - "", - '', - "", - "", - "", - ].join("\n"), - { root, cwd: fixture.root, components: [capturingProbe(seen)] }, - ); + ordinaryCase( + "compares the index with the working tree, and HEAD with the index", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useObservationFixture(); + yield* writeFixtureFile(fixture.root, "src/a.ts", "export const a = 2;\n"); + yield* writeFixtureFile(fixture.root, "staged.ts", "export const staged = true;\n"); + fixture.run("add", "--", "staged.ts"); + yield* writeFixtureFile(fixture.root, "untracked.md", "not tracked\n"); + const seen: Json[] = []; + + yield* runFresh( + [ + '', + "", + "", + "", + '', + "", + "", + "", + ].join("\n"), + { root, cwd: fixture.root, components: [capturingProbe(seen)] }, + ); - const unstaged = object(seen[0]); - expect(unstaged.comparison).toEqual({ compare: "unstaged" }); - // The untracked file is not a tracked change, so it is not here. - expect(unstaged.changes).toEqual([{ path: "src/a.ts", status: "M", previousPath: null }]); + const unstaged = object(seen[0]); + expect(unstaged.comparison).toEqual({ compare: "unstaged" }); + // The untracked file is not a tracked change, so it is not here. + expect(unstaged.changes).toEqual([{ path: "src/a.ts", status: "M", previousPath: null }]); - const staged = object(seen[1]); - expect(staged.comparison).toEqual({ compare: "staged", base: fixture.c2 }); - expect(staged.changes).toEqual([{ path: "staged.ts", status: "A", previousPath: null }]); - }); + const staged = object(seen[1]); + expect(staged.comparison).toEqual({ compare: "staged", base: fixture.c2 }); + expect(staged.changes).toEqual([{ path: "staged.ts", status: "A", previousPath: null }]); + }, + ); // Driven at the native performer rather than through a document, because no // installed provider can select an unborn repository: a selection's identity @@ -577,114 +589,123 @@ describe("GO3 — the three comparisons", () => { }); describe("GO4 — the patch a comparison produces", () => { - it("answers the comparison's own unified text, with Git's binary and mode metadata", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useObservationFixture(); - const seen: Json[] = []; - - yield* runOrdinaryDocument( - [ - ``, - "", - "", - "", - ].join("\n"), - { root, cwd: fixture.root, components: [capturingProbe(seen)] }, - ); + ordinaryCase( + "answers the comparison's own unified text, with Git's binary and mode metadata", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useObservationFixture(); + const seen: Json[] = []; + + yield* runFresh( + [ + ``, + "", + "", + "", + ].join("\n"), + { root, cwd: fixture.root, components: [capturingProbe(seen)] }, + ); - const result = object(seen[0]); - const patch = String(result.text); - expect(result.comparison).toEqual({ compare: "commits", base: fixture.c1, head: fixture.c2 }); - // Every shape the fixture produces, as patch text rather than as a summary. - expect(patch).toContain("rename from doc/orig.md"); - expect(patch).toContain("rename to doc/renamed.md"); - expect(patch).toContain("Binary files a/src/bin.dat and b/src/bin.dat differ"); - expect(patch).toContain("old mode 100644"); - expect(patch).toContain("new mode 100755"); - expect(patch).toContain("new file mode 100644"); - expect(patch).toContain("deleted file mode 100644"); - expect(patch).toContain("Subproject commit"); - expect(result.offset).toBe(0); - expect(result.length).toBe([...patch].length); - expect(result.next).toBe(null); - }); + const result = object(seen[0]); + const patch = String(result.text); + expect(result.comparison).toEqual({ compare: "commits", base: fixture.c1, head: fixture.c2 }); + // Every shape the fixture produces, as patch text rather than as a summary. + expect(patch).toContain("rename from doc/orig.md"); + expect(patch).toContain("rename to doc/renamed.md"); + expect(patch).toContain("Binary files a/src/bin.dat and b/src/bin.dat differ"); + expect(patch).toContain("old mode 100644"); + expect(patch).toContain("new mode 100755"); + expect(patch).toContain("new file mode 100644"); + expect(patch).toContain("deleted file mode 100644"); + expect(patch).toContain("Subproject commit"); + expect(result.offset).toBe(0); + expect(result.length).toBe([...patch].length); + expect(result.next).toBe(null); + }, + ); - it("narrows to literal files and directories, matching a rename on either side", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useObservationFixture(); - const seen: Json[] = []; + ordinaryCase( + "narrows to literal files and directories, matching a rename on either side", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useObservationFixture(); + const seen: Json[] = []; - yield* runOrdinaryDocument( - [ - ``, - "", - "", - "", - ``, - "", - "", - "", - ``, - "", - "", - "", - ``, - "", - "", - "", - ``, - "", - "", - "", - ].join("\n"), - { root, cwd: fixture.root, components: [capturingProbe(seen)] }, - ); + yield* runFresh( + [ + ``, + "", + "", + "", + ``, + "", + "", + "", + ``, + "", + "", + "", + ``, + "", + "", + "", + ``, + "", + "", + "", + ].join("\n"), + { root, cwd: fixture.root, components: [capturingProbe(seen)] }, + ); - expect(object(seen[0]).changes).toEqual([ - { path: "src/added.ts", status: "A", previousPath: null }, - { path: "src/bin.dat", status: "M", previousPath: null }, - ]); - // The old path selects the whole rename record, not half of it. - expect(object(seen[1]).changes).toEqual([ - { path: "doc/renamed.md", status: "R", previousPath: "doc/orig.md" }, - ]); - expect(String(object(seen[2]).text)).toContain("rename from doc/orig.md"); - // An empty selector is a thing a document says, and it selects nothing. - expect(object(seen[3]).changes).toEqual([]); - expect(object(seen[4]).text).toBe(""); - expect(object(seen[4]).length).toBe(0); - expect(object(seen[4]).next).toBe(null); - }); + expect(object(seen[0]).changes).toEqual([ + { path: "src/added.ts", status: "A", previousPath: null }, + { path: "src/bin.dat", status: "M", previousPath: null }, + ]); + // The old path selects the whole rename record, not half of it. + expect(object(seen[1]).changes).toEqual([ + { path: "doc/renamed.md", status: "R", previousPath: "doc/orig.md" }, + ]); + expect(String(object(seen[2]).text)).toContain("rename from doc/orig.md"); + // An empty selector is a thing a document says, and it selects nothing. + expect(object(seen[3]).changes).toEqual([]); + expect(object(seen[4]).text).toBe(""); + expect(object(seen[4]).length).toBe(0); + expect(object(seen[4]).next).toBe(null); + }, + ); - it("keeps a tracked gitlink's moved pointer without reading inside it", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useObservationFixture(); - const seen: Json[] = []; + ordinaryCase( + "keeps a tracked gitlink's moved pointer without reading inside it", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useObservationFixture(); + const seen: Json[] = []; - yield* runOrdinaryDocument( - [ - ``, - "", - "", - "", - ].join("\n"), - { root, cwd: fixture.root, components: [capturingProbe(seen)] }, - ); + yield* runFresh( + [ + ``, + "", + "", + "", + ].join("\n"), + { root, cwd: fixture.root, components: [capturingProbe(seen)] }, + ); - const patch = String(object(seen[0]).text); - expect(patch).toContain(`-Subproject commit ${fixture.gitlink.before}`); - expect(patch).toContain(`+Subproject commit ${fixture.gitlink.after}`); - // One path and one pointer. Nothing beneath the gitlink is read, so the - // nested repository's own file never appears. - expect(patch).not.toContain("inner.txt"); - }); + const patch = String(object(seen[0]).text); + expect(patch).toContain(`-Subproject commit ${fixture.gitlink.before}`); + expect(patch).toContain(`+Subproject commit ${fixture.gitlink.after}`); + // One path and one pointer. Nothing beneath the gitlink is read, so the + // nested repository's own file never appears. + expect(patch).not.toContain("inner.txt"); + }, + ); - it("collapses an unmerged path to one record", function* () { + ordinaryCase("collapses an unmerged path to one record", function* (runFresh) { const root = yield* useManagedRoot(); const conflicted = yield* useConflictedCheckout(); const seen: Json[] = []; - yield* runOrdinaryDocument( + yield* runFresh( [ '', "", @@ -749,7 +770,7 @@ describe("GO5 — pages are bounded, complete, and about one observation", () => expect(object(whole[0]).next).toBe(null); }); - it("pages changes at a limit of one and at the default", function* () { + ordinaryCase("pages changes at a limit of one and at the default", function* (runFresh) { const root = yield* useManagedRoot(); const fixture = yield* useGeneratedFixture(1002); for (const path of fixture.paths) { @@ -757,7 +778,7 @@ describe("GO5 — pages are bounded, complete, and about one observation", () => } const seen: Json[] = []; - yield* runOrdinaryDocument( + yield* runFresh( [ '', "", @@ -890,12 +911,12 @@ describe("GO5 — pages are bounded, complete, and about one observation", () => }); describe("GO6 — a changed observation cannot be paged over", () => { - it("refuses a file listing whose paths changed between pages", function* () { + ordinaryCase("refuses a file listing whose paths changed between pages", function* (runFresh) { const root = yield* useManagedRoot(); const fixture = yield* useGeneratedFixture(150); const raised_ = yield* raised( - runOrdinaryDocument( + runFresh( [ '', "", @@ -927,114 +948,123 @@ describe("GO6 — a changed observation cannot be paged over", () => { // editing a path already reported as modified leaves the normalized listing // identical, and a read that restarted for that would refuse a page it could // honestly answer. So this adds a record the first page never described. - it("refuses a changes listing whose records changed between pages", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useGeneratedFixture(150); - for (const path of fixture.paths.slice(0, 120)) { - yield* writeFixtureFile(fixture.root, path, "changed\n"); - } + ordinaryCase( + "refuses a changes listing whose records changed between pages", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useGeneratedFixture(150); + for (const path of fixture.paths.slice(0, 120)) { + yield* writeFixtureFile(fixture.root, path, "changed\n"); + } - const raised_ = yield* raised( - runOrdinaryDocument( - [ - '', - "", - "", - "", - '', - "", - ].join("\n"), - { - root, - cwd: fixture.root, - components: [ - actionProbe("Mutates", function* () { - yield* writeFixtureFile(fixture.root, fixture.paths[149] ?? "", "changed too\n"); - }), - ], - }, - ), - ); + const raised_ = yield* raised( + runFresh( + [ + '', + "", + "", + "", + '', + "", + ].join("\n"), + { + root, + cwd: fixture.root, + components: [ + actionProbe("Mutates", function* () { + yield* writeFixtureFile(fixture.root, fixture.paths[149] ?? "", "changed too\n"); + }), + ], + }, + ), + ); - expect(reasonOf(raised_)).toBe("stale-continuation"); - expect(messageOf(raised_)).toBe( - "The Git observation changed. Restart without cursor.", - ); - }); + expect(reasonOf(raised_)).toBe("stale-continuation"); + expect(messageOf(raised_)).toBe( + "The Git observation changed. Restart without cursor.", + ); + }, + ); + + ordinaryCase( + "refuses a patch whose text changed between windows, and names offset zero", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useGeneratedFixture(150); + for (const path of fixture.paths) { + yield* writeFixtureFile(fixture.root, path, "changed\n"); + } - it("refuses a patch whose text changed between windows, and names offset zero", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useGeneratedFixture(150); - for (const path of fixture.paths) { - yield* writeFixtureFile(fixture.root, path, "changed\n"); - } + const raised_ = yield* raised( + runFresh( + [ + '', + "", + "", + "", + '', + "", + ].join("\n"), + { + root, + cwd: fixture.root, + components: [ + actionProbe("Mutates", function* () { + yield* writeFixtureFile(fixture.root, fixture.paths[0] ?? "", "changed again\n"); + }), + ], + }, + ), + ); - const raised_ = yield* raised( - runOrdinaryDocument( + expect(reasonOf(raised_)).toBe("stale-continuation"); + expect(messageOf(raised_)).toBe( + "The Git observation changed. Restart without cursor and offset={0}.", + ); + }, + ); + + ordinaryCase( + "follows a continuation unchanged when the repository changed elsewhere", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useGeneratedFixture(150); + const seen: Json[] = []; + + yield* runFresh( [ - '', + '', "", "", "", - '', + '', + "", + "", "", ].join("\n"), { root, cwd: fixture.root, components: [ + capturingProbe(seen), actionProbe("Mutates", function* () { - yield* writeFixtureFile(fixture.root, fixture.paths[0] ?? "", "changed again\n"); + // Outside the selected observation: an untracked file changes no + // tracked path, so this page is still a page of the same answer. + yield* writeFixtureFile(fixture.root, "untracked-elsewhere.txt", "elsewhere\n"); }), ], }, - ), - ); - - expect(reasonOf(raised_)).toBe("stale-continuation"); - expect(messageOf(raised_)).toBe( - "The Git observation changed. Restart without cursor and offset={0}.", - ); - }); - - it("follows a continuation unchanged when the repository changed elsewhere", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useGeneratedFixture(150); - const seen: Json[] = []; - - yield* runOrdinaryDocument( - [ - '', - "", - "", - "", - '', - "", - "", - "", - ].join("\n"), - { - root, - cwd: fixture.root, - components: [ - capturingProbe(seen), - actionProbe("Mutates", function* () { - // Outside the selected observation: an untracked file changes no - // tracked path, so this page is still a page of the same answer. - yield* writeFixtureFile(fixture.root, "untracked-elsewhere.txt", "elsewhere\n"); - }), - ], - }, - ); + ); - expect(paths(seen[0])).toEqual([ - "gen/file-00005.txt", - "gen/file-00006.txt", - "gen/file-00007.txt", - "gen/file-00008.txt", - "gen/file-00009.txt", - ]); - }); + expect(paths(seen[0])).toEqual([ + "gen/file-00005.txt", + "gen/file-00006.txt", + "gen/file-00007.txt", + "gen/file-00008.txt", + "gen/file-00009.txt", + ]); + }, + ); it("refuses a cursor that is malformed, for another read, or for another checkout", function* () { const root = yield* useManagedRoot(); @@ -1156,55 +1186,58 @@ describe("GO7 — a file is read as one commit holds it", () => { expect(windows.join("")).toBe(LONG_BLOB); }); - it("answers a middle window, an empty window past the end, and an empty file", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useFileFixture(); - const seen: Json[] = []; - const total = [...LONG_BLOB].length; - - yield* runOrdinaryDocument( - [ - ``, - "", - "", - "", - ``, - "", - "", - "", - ``, - "", - "", - "", - ``, - "", - "", - "", - ].join("\n"), - { root, cwd: fixture.root, components: [capturingProbe(seen)] }, - ); + ordinaryCase( + "answers a middle window, an empty window past the end, and an empty file", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useFileFixture(); + const seen: Json[] = []; + const total = [...LONG_BLOB].length; - expect(object(seen[0]).text).toBe("aaaaa"); - expect(object(seen[0]).next).toEqual({ - commit: fixture.f1, - path: "big.txt", - offset: 15, - limit: 5, - }); + yield* runFresh( + [ + ``, + "", + "", + "", + ``, + "", + "", + "", + ``, + "", + "", + "", + ``, + "", + "", + "", + ].join("\n"), + { root, cwd: fixture.root, components: [capturingProbe(seen)] }, + ); - for (const past of [object(seen[1]), object(seen[2])]) { - expect(past.text).toBe(""); - expect(past.length).toBe(total); - expect(past.next).toBe(null); - } - expect(object(seen[1]).offset).toBe(total); - expect(object(seen[2]).offset).toBe(total + 500); + expect(object(seen[0]).text).toBe("aaaaa"); + expect(object(seen[0]).next).toEqual({ + commit: fixture.f1, + path: "big.txt", + offset: 15, + limit: 5, + }); + + for (const past of [object(seen[1]), object(seen[2])]) { + expect(past.text).toBe(""); + expect(past.length).toBe(total); + expect(past.next).toBe(null); + } + expect(object(seen[1]).offset).toBe(total); + expect(object(seen[2]).offset).toBe(total + 500); - const empty = object(seen[3]); - expect(empty.text).toBe(""); - expect(empty.length).toBe(0); - expect(empty.next).toBe(null); - }); + const empty = object(seen[3]); + expect(empty.text).toBe(""); + expect(empty.length).toBe(0); + expect(empty.next).toBe(null); + }, + ); it("refuses an unusable revision, an absent path, a tree, a gitlink and a nontext blob", function* () { const root = yield* useManagedRoot(); @@ -1268,12 +1301,12 @@ describe("GO7 — a file is read as one commit holds it", () => { } }); - it("still reads a directory's own child by its exact path", function* () { + ordinaryCase("still reads a directory's own child by its exact path", function* (runFresh) { const root = yield* useManagedRoot(); const fixture = yield* useFileFixture(); const seen: Json[] = []; - yield* runOrdinaryDocument( + yield* runFresh( [ ``, "", @@ -1289,25 +1322,28 @@ describe("GO7 — a file is read as one commit holds it", () => { expect(object(seen[0]).text).toBe("inside\n"); }); - it("answers a symbolic link's own stored text rather than what it points at", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useFileFixture(); - const seen: Json[] = []; + ordinaryCase( + "answers a symbolic link's own stored text rather than what it points at", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useFileFixture(); + const seen: Json[] = []; - yield* runOrdinaryDocument( - [ - ``, - "", - "", - "", - ].join("\n"), - { root, cwd: fixture.root, components: [capturingProbe(seen)] }, - ); + yield* runFresh( + [ + ``, + "", + "", + "", + ].join("\n"), + { root, cwd: fixture.root, components: [capturingProbe(seen)] }, + ); - // The link's target, as the blob holds it. Nothing followed it. - expect(object(seen[0]).text).toBe("big.txt"); - expect(object(seen[0]).length).toBe(7); - }); + // The link's target, as the blob holds it. Nothing followed it. + expect(object(seen[0]).text).toBe("big.txt"); + expect(object(seen[0]).length).toBe(7); + }, + ); }); describe("GO8 — a read runs no repository-defined program and changes nothing", () => { @@ -1361,45 +1397,48 @@ describe("GO8 — a read runs no repository-defined program and changes nothing" } }); - it("reads a linked checkout's own split index and leaves all three untouched", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useObservationFixture(); - const linked = yield* useLinkedWorktree(fixture); - fixture.run("update-index", "--split-index"); - linked.run("update-index", "--split-index"); - yield* writeFixtureFile(linked.root, "src/a.ts", "export const a = 9;\n"); + ordinaryCase( + "reads a linked checkout's own split index and leaves all three untouched", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useObservationFixture(); + const linked = yield* useLinkedWorktree(fixture); + fixture.run("update-index", "--split-index"); + linked.run("update-index", "--split-index"); + yield* writeFixtureFile(linked.root, "src/a.ts", "export const a = 9;\n"); - const indexes = yield* indexFingerprints(fixture, linked); - const seen: Json[] = []; + const indexes = yield* indexFingerprints(fixture, linked); + const seen: Json[] = []; - yield* runOrdinaryDocument( - [ - '', - "", - "", - "", - '', - "", - "", - "", - '', - "", - "", - "", - ].join("\n"), - { root, cwd: linked.root, components: [capturingProbe(seen)] }, - ); + yield* runFresh( + [ + '', + "", + "", + "", + '', + "", + "", + "", + '', + "", + "", + "", + ].join("\n"), + { root, cwd: linked.root, components: [capturingProbe(seen)] }, + ); - // The linked checkout's own index answered: its working tree holds the - // edit, and the primary checkout's does not. - expect(paths(seen[0])).toContain("src/a.ts"); - expect(object(seen[1]).changes).toEqual([ - { path: "src/a.ts", status: "M", previousPath: null }, - ]); - expect(String(object(seen[2]).text)).toContain("+export const a = 9;"); + // The linked checkout's own index answered: its working tree holds the + // edit, and the primary checkout's does not. + expect(paths(seen[0])).toContain("src/a.ts"); + expect(object(seen[1]).changes).toEqual([ + { path: "src/a.ts", status: "M", previousPath: null }, + ]); + expect(String(object(seen[2]).text)).toContain("+export const a = 9;"); - expect(yield* indexFingerprints(fixture, linked)).toEqual(indexes); - }); + expect(yield* indexFingerprints(fixture, linked)).toEqual(indexes); + }, + ); }); describe("GO9 — which checkout answers, and what cannot choose one", () => { @@ -1482,39 +1521,42 @@ describe("GO9 — which checkout answers, and what cannot choose one", () => { }); describe("GO10 — the comparison sees an edit the index's own times would hide", () => { - it("reports a modification whose size and recorded time match the index entry", function* () { - const root = yield* useManagedRoot(); - const fixture = yield* useObservationFixture(); - const indexPath = join(fixture.root, ".git", "index"); - const indexTimes = yield* lstat(indexPath); - // The same length, and the index's own modification time. This is exactly - // the state Git calls racily clean: the cached stat data matches, so the - // only way to see the change is to compare content — and the only reason - // Git does is that the entry is no older than the index holding it. A - // private copy stamped with the current time destroys that relationship. - yield* writeFixtureFile(fixture.root, "src/a.ts", "export const a = 7;\n"); - yield* until(utimes(join(fixture.root, "src", "a.ts"), indexTimes.mtime, indexTimes.mtime)); - const seen: Json[] = []; - - yield* runOrdinaryDocument( - [ - '', - "", - "", - "", - '', - "", - "", - "", - ].join("\n"), - { root, cwd: fixture.root, components: [capturingProbe(seen)] }, - ); + ordinaryCase( + "reports a modification whose size and recorded time match the index entry", + function* (runFresh) { + const root = yield* useManagedRoot(); + const fixture = yield* useObservationFixture(); + const indexPath = join(fixture.root, ".git", "index"); + const indexTimes = yield* lstat(indexPath); + // The same length, and the index's own modification time. This is exactly + // the state Git calls racily clean: the cached stat data matches, so the + // only way to see the change is to compare content — and the only reason + // Git does is that the entry is no older than the index holding it. A + // private copy stamped with the current time destroys that relationship. + yield* writeFixtureFile(fixture.root, "src/a.ts", "export const a = 7;\n"); + yield* until(utimes(join(fixture.root, "src", "a.ts"), indexTimes.mtime, indexTimes.mtime)); + const seen: Json[] = []; + + yield* runFresh( + [ + '', + "", + "", + "", + '', + "", + "", + "", + ].join("\n"), + { root, cwd: fixture.root, components: [capturingProbe(seen)] }, + ); - expect(object(seen[0]).changes).toEqual([ - { path: "src/a.ts", status: "M", previousPath: null }, - ]); - expect(String(object(seen[1]).text)).toContain("+export const a = 7;"); - }); + expect(object(seen[0]).changes).toEqual([ + { path: "src/a.ts", status: "M", previousPath: null }, + ]); + expect(String(object(seen[1]).text)).toContain("+export const a = 7;"); + }, + ); }); describe("GO11 — the authored contract, before a provider is reached", () => { diff --git a/packages/git/tests/run-composition-ambient.test.ts b/packages/git/tests/run-composition-ambient.test.ts index 772158508..e14f4b930 100644 --- a/packages/git/tests/run-composition-ambient.test.ts +++ b/packages/git/tests/run-composition-ambient.test.ts @@ -33,6 +33,7 @@ import { UnresolvedGitIdentityError } from "../src/deno/run-composition/errors.t import { useBareRemote } from "./support/git-remotes.ts"; import { gitHubSource } from "../src/deno/composition/github.ts"; import { + ordinaryDocumentCases, causedBy, commonDirectoryOf, countingOrdinaryHost, @@ -54,27 +55,32 @@ import { reviewRoutes, } from "./support/run-composition-tier.ts"; -describe("ORC3 — the ambient primary checkout", () => { - it("switches, stages and commits in the repository the command was run in", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); +const ordinaryCase = ordinaryDocumentCases("packages/git/tests/run-composition-ambient.test.ts"); - yield* runOrdinaryDocument( - [ - ``, - `ordinary`, - ``, - ``, - ].join("\n"), - { root, cwd: checkout.root }, - ); +describe("ORC3 — the ambient primary checkout", () => { + ordinaryCase( + "switches, stages and commits in the repository the command was run in", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); + + yield* runFresh( + [ + ``, + `ordinary`, + ``, + ``, + ].join("\n"), + { root, cwd: checkout.root }, + ); - // The person's own checkout moved, and it is what a later `git` sees. - expect(checkout.run("rev-parse", "--abbrev-ref", "HEAD")).toBe("feature"); - expect(checkout.run("log", "-1", "--pretty=%s")).toBe("Write notes"); - expect(checkout.run("show", "--pretty=", "--name-only", "HEAD")).toContain("notes.md"); - }); + // The person's own checkout moved, and it is what a later `git` sees. + expect(checkout.run("rev-parse", "--abbrev-ref", "HEAD")).toBe("feature"); + expect(checkout.run("log", "-1", "--pretty=%s")).toBe("Write notes"); + expect(checkout.run("show", "--pretty=", "--name-only", "HEAD")).toContain("notes.md"); + }, + ); it("refuses every root element that needs a repository outside a Git checkout", function* () { const root = yield* useManagedRoot(); @@ -113,32 +119,35 @@ describe("ORC3 — the ambient primary checkout", () => { }); describe("ORC4 — the ambient linked worktree", () => { - it("follows the common directory for identity and the worktree root for work", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const primary = yield* useHostCheckout(remote.locator); - // A linked worktree made by hand, exactly as a person would. - const linked = `${primary.root}-linked`; - primary.run("worktree", "add", "-b", "sidecar", linked); - - const before = primary.run("rev-parse", "HEAD"); - - yield* scoped(function* () { - yield* runOrdinaryDocument( - [ - `here`, - ``, - ``, - ].join("\n"), - // The command is run *in the linked worktree*. - { root, cwd: linked }, - ); - }); - - // The worktree advanced; the primary checkout did not. - expect(primary.run("rev-parse", "HEAD")).toBe(before); - expect(primary.run("log", "-1", "--pretty=%s", "sidecar")).toBe("In the worktree"); - }); + ordinaryCase( + "follows the common directory for identity and the worktree root for work", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const primary = yield* useHostCheckout(remote.locator); + // A linked worktree made by hand, exactly as a person would. + const linked = `${primary.root}-linked`; + primary.run("worktree", "add", "-b", "sidecar", linked); + + const before = primary.run("rev-parse", "HEAD"); + + yield* scoped(function* () { + yield* runFresh( + [ + `here`, + ``, + ``, + ].join("\n"), + // The command is run *in the linked worktree*. + { root, cwd: linked }, + ); + }); + + // The worktree advanced; the primary checkout did not. + expect(primary.run("rev-parse", "HEAD")).toBe(before); + expect(primary.run("log", "-1", "--pretty=%s", "sidecar")).toBe("In the worktree"); + }, + ); }); describe("ORC5 — origin is not local admission", () => { @@ -196,25 +205,28 @@ describe("ORC5 — origin is not local admission", () => { } }); - it("opens a session and transports when there is an origin, so the counters can fail", function* () { - // The same counters, on a repository that *does* have an origin. Without - // this, every assertion above would pass on a counter that can never be - // incremented — which is the one way "nothing was reached" lies. - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); - const counting = countingOrdinaryHost(); + ordinaryCase( + "opens a session and transports when there is an origin, so the counters can fail", + function* (runFresh) { + // The same counters, on a repository that *does* have an origin. Without + // this, every assertion above would pass on a counter that can never be + // incremented — which is the one way "nothing was reached" lies. + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); + const counting = countingOrdinaryHost(); - yield* runOrdinaryDocument([``, ``].join("\n"), { - root, - cwd: checkout.root, - host: counting.host, - }); + yield* runFresh([``, ``].join("\n"), { + root, + cwd: checkout.root, + host: counting.host, + }); - expect(counting.counters.sessions).toEqual([remote.locator]); - expect(subcommands(counting.counters)).toContain("ls-remote"); - expect(subcommands(counting.counters)).toContain("push"); - }); + expect(counting.counters.sessions).toEqual([remote.locator]); + expect(subcommands(counting.counters)).toContain("ls-remote"); + expect(subcommands(counting.counters)).toContain("push"); + }, + ); it("reaches a Git host when one is configured, so those counters can fail too", function* () { const remote = yield* useBareRemote(REMOTE); @@ -241,53 +253,56 @@ describe("ORC5 — origin is not local admission", () => { }); describe("ORC6 — lexical working directories", () => { - it("restores the enclosing directory after a Worktree body and a Dir body", function* () { - yield* Permissions.around( - { files: ([operation], next) => (operation === "absolute" ? true : next(operation)) }, - { at: "min" }, - ); - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); - - // A relative `` path resolves against the contextual working - // directory, so where each one lands is where the document was standing. - const common = commonDirectoryOf(checkout); - yield* runOrdinaryDocument( - [ - `outer`, - ``, - ``, - `within`, - "", - "", - `bound`, - "", - `after`, - ].join("\n"), - { root, cwd: checkout.root }, - ); + ordinaryCase( + "restores the enclosing directory after a Worktree body and a Dir body", + function* (runFresh) { + yield* Permissions.around( + { files: ([operation], next) => (operation === "absolute" ? true : next(operation)) }, + { at: "min" }, + ); + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); + + // A relative `` path resolves against the contextual working + // directory, so where each one lands is where the document was standing. + const common = commonDirectoryOf(checkout); + yield* runFresh( + [ + `outer`, + ``, + ``, + `within`, + "", + "", + `bound`, + "", + `after`, + ].join("\n"), + { root, cwd: checkout.root }, + ); - const lexical = worktreeSlotOf(root, common, "lexical"); - const bound = worktreeSlotOf(root, common, "inner"); - expect(yield* exists(`${checkout.root}/outer.md`)).toBe(true); - // Each body observed its own checkout. - expect(yield* exists(`${lexical.checkout}/within.md`)).toBe(true); - expect(yield* exists(`${bound.checkout}/bound.md`)).toBe(true); - // Restored: the sibling after both is back in the enclosing directory. - expect(yield* exists(`${checkout.root}/after.md`)).toBe(true); - expect(yield* exists(`${lexical.checkout}/after.md`)).toBe(false); - expect(yield* exists(`${bound.checkout}/after.md`)).toBe(false); - }); + const lexical = worktreeSlotOf(root, common, "lexical"); + const bound = worktreeSlotOf(root, common, "inner"); + expect(yield* exists(`${checkout.root}/outer.md`)).toBe(true); + // Each body observed its own checkout. + expect(yield* exists(`${lexical.checkout}/within.md`)).toBe(true); + expect(yield* exists(`${bound.checkout}/bound.md`)).toBe(true); + // Restored: the sibling after both is back in the enclosing directory. + expect(yield* exists(`${checkout.root}/after.md`)).toBe(true); + expect(yield* exists(`${lexical.checkout}/after.md`)).toBe(false); + expect(yield* exists(`${bound.checkout}/after.md`)).toBe(false); + }, + ); - it("restores the enclosing directory when the body fails", function* () { + ordinaryCase("restores the enclosing directory when the body fails", function* (runFresh) { const remote = yield* useBareRemote(REMOTE); const root = yield* useManagedRoot(); const checkout = yield* useHostCheckout(remote.locator); // The refusal is printed rather than fatal, so the document goes on — and // what it goes on in is the directory the Worktree body was installed over. - yield* runOrdinaryDocument( + yield* runFresh( [ "", ``, @@ -339,28 +354,31 @@ describe("ORC6 — lexical working directories", () => { }); describe("ORC13 — live local Git", () => { - it("makes real, non-transactional changes and claims no rollback on failure", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); + ordinaryCase( + "makes real, non-transactional changes and claims no rollback on failure", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); - const failure = yield* raised( - runOrdinaryDocument( - [ - ``, - `staged before the failure`, - ``, - ``, - ].join("\n"), - { root, cwd: checkout.root }, - ), - ); - expect(failure).toBeInstanceOf(Error); + const failure = yield* raised( + runFresh( + [ + ``, + `staged before the failure`, + ``, + ``, + ].join("\n"), + { root, cwd: checkout.root }, + ), + ); + expect(failure).toBeInstanceOf(Error); - // The switch and the first Add really happened, and nothing took them back. - expect(checkout.run("rev-parse", "--abbrev-ref", "HEAD")).toBe("partway"); - expect(checkout.run("diff", "--cached", "--name-only")).toContain("staged.md"); - }); + // The switch and the first Add really happened, and nothing took them back. + expect(checkout.run("rev-parse", "--abbrev-ref", "HEAD")).toBe("partway"); + expect(checkout.run("diff", "--cached", "--name-only")).toContain("staged.md"); + }, + ); it("keeps what a cancelled document had already done, and claims no rollback", function* () { const remote = yield* useBareRemote(REMOTE); @@ -385,12 +403,12 @@ describe("ORC13 — live local Git", () => { expect(checkout.run("log", "-1", "--pretty=%s")).not.toBe("never reached"); }); - it("commits as the invoking user, not as the workflow identity", function* () { + ordinaryCase("commits as the invoking user, not as the workflow identity", function* (runFresh) { const remote = yield* useBareRemote(REMOTE); const root = yield* useManagedRoot(); const checkout = yield* useHostCheckout(remote.locator); - yield* runOrdinaryDocument( + yield* runFresh( [ `mine`, ``, @@ -409,85 +427,94 @@ describe("ORC13 — live local Git", () => { expect(checkout.run("log", "-1", "--pretty=%an")).not.toBe("Executable.md workflow"); }); - it("takes author and committer separately when the host resolves them apart", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); + ordinaryCase( + "takes author and committer separately when the host resolves them apart", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); - yield* runOrdinaryDocument( - [ - `pair`, - ``, - ``, - ].join("\n"), - { - root, - cwd: checkout.root, - identity: statedIdentity( - "Ada Lovelace 1 +0000", - "Grace Hopper 1 +0000", + yield* runFresh( + [ + `pair`, + ``, + ``, + ].join("\n"), + { + root, + cwd: checkout.root, + identity: statedIdentity( + "Ada Lovelace 1 +0000", + "Grace Hopper 1 +0000", + ), + }, + ); + + expect(checkout.run("log", "-1", "--pretty=%an|%ae|%cn|%ce")).toBe( + "Ada Lovelace|ada@example.test|Grace Hopper|grace@example.test", + ); + }, + ); + + ordinaryCase( + "refuses to commit when the host cannot say who the commit is by", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); + const before = checkout.run("rev-parse", "HEAD"); + + const failure = yield* raised( + runFresh( + [ + `orphan`, + ``, + ``, + ].join("\n"), + { root, cwd: checkout.root, identity: statedIdentity(undefined) }, ), - }, - ); + ); - expect(checkout.run("log", "-1", "--pretty=%an|%ae|%cn|%ce")).toBe( - "Ada Lovelace|ada@example.test|Grace Hopper|grace@example.test", - ); - }); + expect(failure).toBeInstanceOf(UnresolvedGitIdentityError); + expect(String(failure)).toContain("git config --global user.name"); + // Nothing was committed, and no identity was substituted. + expect(checkout.run("rev-parse", "HEAD")).toBe(before); + // The staging that came before it still happened: this refuses the commit, + // not the document that led to it. + expect(checkout.run("diff", "--cached", "--name-only")).toContain("orphan.md"); + }, + ); - it("refuses to commit when the host cannot say who the commit is by", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); - const before = checkout.run("rev-parse", "HEAD"); + ordinaryCase( + "leaves every other component usable when no identity resolves", + function* (runFresh) { + yield* Permissions.around( + { files: ([operation], next) => (operation === "absolute" ? true : next(operation)) }, + { at: "min" }, + ); + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); - const failure = yield* raised( - runOrdinaryDocument( + // Repository, Worktree, Dir, Switch and Add all work: none of them writes a + // commit object, so none of them needs to know who anybody is. + const rendered = yield* runFresh( [ - `orphan`, - ``, - ``, + ``, + ``, + "", + ``, + `fine`, + ``, + "", + "", + "ran", ].join("\n"), { root, cwd: checkout.root, identity: statedIdentity(undefined) }, - ), - ); - - expect(failure).toBeInstanceOf(UnresolvedGitIdentityError); - expect(String(failure)).toContain("git config --global user.name"); - // Nothing was committed, and no identity was substituted. - expect(checkout.run("rev-parse", "HEAD")).toBe(before); - // The staging that came before it still happened: this refuses the commit, - // not the document that led to it. - expect(checkout.run("diff", "--cached", "--name-only")).toContain("orphan.md"); - }); - - it("leaves every other component usable when no identity resolves", function* () { - yield* Permissions.around( - { files: ([operation], next) => (operation === "absolute" ? true : next(operation)) }, - { at: "min" }, - ); - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); - - // Repository, Worktree, Dir, Switch and Add all work: none of them writes a - // commit object, so none of them needs to know who anybody is. - const rendered = yield* runOrdinaryDocument( - [ - ``, - ``, - "", - ``, - `fine`, - ``, - "", - "", - "ran", - ].join("\n"), - { root, cwd: checkout.root, identity: statedIdentity(undefined) }, - ); - expect(String(rendered)).toContain("ran"); - }); + ); + expect(String(rendered)).toContain("ran"); + }, + ); it("keeps hooks, monitors, signing and repository helpers disabled", function* () { const remote = yield* useBareRemote(REMOTE); @@ -571,86 +598,89 @@ function selectionProbe(seen: (RepositorySelection | undefined)[]): ComponentReg describe("ORC6 — Dir makes the directory it names", () => { // ORC6: the ordering claim and the two path rules, in one document. - it("ORC6: creates missing parents, keeps an absolute path, and finishes before content", function* () { - yield* Permissions.around( - { files: ([operation], next) => (operation === "absolute" ? true : next(operation)) }, - { at: "min" }, - ); - const root = yield* useManagedRoot(); - const checkout = (yield* useOriginlessCheckout()).root; - const elsewhere = yield* useTempDirectory("xmd-orc6-absolute-"); - - // The ordering probe. A nested `` proves nothing about ordering, - // because a write creates its own parents recursively — it would land - // whether or not the ensure had finished. This runs *first* inside the - // region and records what it finds: whether the directory is already there, - // and what the contextual working directory is at that moment. - const observed: { exists: boolean; cwd: string }[] = []; - const probe: ComponentRegistration = { - name: "Observes", - origin: "test://observes", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn(): Operation { - const here = yield* cwd(); - observed.push({ exists: yield* exists(here), cwd: here }); - return ""; - }, - }; - - yield* runOrdinaryDocument( - [ - '', - "", - "", - "", - 'landed', - "", - "", - "", - ``, - "", - "", - "", - 'also landed', - "", - "", - "", - ].join("\n"), - { root, cwd: checkout, components: [probe] }, - ); + ordinaryCase( + "ORC6: creates missing parents, keeps an absolute path, and finishes before content", + function* (runFresh) { + yield* Permissions.around( + { files: ([operation], next) => (operation === "absolute" ? true : next(operation)) }, + { at: "min" }, + ); + const root = yield* useManagedRoot(); + const checkout = (yield* useOriginlessCheckout()).root; + const elsewhere = yield* useTempDirectory("xmd-orc6-absolute-"); + + // The ordering probe. A nested `` proves nothing about ordering, + // because a write creates its own parents recursively — it would land + // whether or not the ensure had finished. This runs *first* inside the + // region and records what it finds: whether the directory is already there, + // and what the contextual working directory is at that moment. + const observed: { exists: boolean; cwd: string }[] = []; + const probe: ComponentRegistration = { + name: "Observes", + origin: "test://observes", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn(): Operation { + const here = yield* cwd(); + observed.push({ exists: yield* exists(here), cwd: here }); + return ""; + }, + }; - // Before any other content ran, the directory already existed and was the - // contextual working directory. That is the ordering claim, observed rather - // than inferred. - expect(observed).toHaveLength(2); - expect(observed[0]).toEqual({ exists: true, cwd: join(checkout, "made", "deep") }); - expect(observed[1]).toEqual({ - exists: true, - cwd: join(elsewhere, "written", "here"), - }); + yield* runFresh( + [ + '', + "", + "", + "", + 'landed', + "", + "", + "", + ``, + "", + "", + "", + 'also landed', + "", + "", + "", + ].join("\n"), + { root, cwd: checkout, components: [probe] }, + ); - // Every missing parent, and the file that landed after them. - expect(yield* readTextFile(join(checkout, "made", "deep", "inside.md"))).toBe("landed"); - // The absolute target names exactly that place — not a rebase beneath cwd. - expect(yield* readTextFile(join(elsewhere, "written", "here", "outside.md"))).toBe( - "also landed", - ); - expect(yield* exists(join(checkout, elsewhere.replace(/^\//, "")))).toBe(false); - }); + // Before any other content ran, the directory already existed and was the + // contextual working directory. That is the ordering claim, observed rather + // than inferred. + expect(observed).toHaveLength(2); + expect(observed[0]).toEqual({ exists: true, cwd: join(checkout, "made", "deep") }); + expect(observed[1]).toEqual({ + exists: true, + cwd: join(elsewhere, "written", "here"), + }); + + // Every missing parent, and the file that landed after them. + expect(yield* readTextFile(join(checkout, "made", "deep", "inside.md"))).toBe("landed"); + // The absolute target names exactly that place — not a rebase beneath cwd. + expect(yield* readTextFile(join(elsewhere, "written", "here", "outside.md"))).toBe( + "also landed", + ); + expect(yield* exists(join(checkout, elsewhere.replace(/^\//, "")))).toBe(false); + }, + ); // ORC6a: an existing directory is adopted. Asserted on the bytes and on the // entry list, because a provider that removed and recreated it would pass a // test that only checked the directory exists. - it("ORC6a: an existing directory keeps its contents", function* () { + ordinaryCase("ORC6a: an existing directory keeps its contents", function* (runFresh) { const root = yield* useManagedRoot(); const checkout = (yield* useOriginlessCheckout()).root; yield* ensureDir(join(checkout, "kept", "sub")); yield* writeTextFile(join(checkout, "kept", "planted.txt"), "the bytes that were here"); - yield* runOrdinaryDocument( - '\n\nadded\n\n\n', - { root, cwd: checkout }, - ); + yield* runFresh('\n\nadded\n\n\n', { + root, + cwd: checkout, + }); expect(yield* readTextFile(join(checkout, "kept", "planted.txt"))).toBe( "the bytes that were here", @@ -791,35 +821,38 @@ describe("ORC6 — Dir makes the directory it names", () => { // ORC6d: the operation is about a directory. The Repository selection in // scope, and every member of its identity, is the same inside the region and // after it. - it("ORC6d: Repository selection and identity are unchanged by Dir", function* () { - const root = yield* useManagedRoot(); - const remote = yield* useBareRemote(REMOTE); - const checkout = (yield* useHostCheckout(remote.locator)).root; - const seen: (RepositorySelection | undefined)[] = []; - - yield* runOrdinaryDocument( - [ - '', - '', - "", - '', - "", - "", - "", - '', - "", - ].join("\n"), - { root, cwd: checkout, components: [selectionProbe(seen)] }, - ); + ordinaryCase( + "ORC6d: Repository selection and identity are unchanged by Dir", + function* (runFresh) { + const root = yield* useManagedRoot(); + const remote = yield* useBareRemote(REMOTE); + const checkout = (yield* useHostCheckout(remote.locator)).root; + const seen: (RepositorySelection | undefined)[] = []; + + yield* runFresh( + [ + '', + '', + "", + '', + "", + "", + "", + '', + "", + ].join("\n"), + { root, cwd: checkout, components: [selectionProbe(seen)] }, + ); - expect(seen).toHaveLength(3); - // The whole selection, member by member: identifier, name, checkout path - // and every member of the identity. A Dir that had re-selected anything - // would differ in one of them. - expect(seen[0]).toBeDefined(); - expect(seen[1]).toEqual(seen[0]); - expect(seen[2]).toEqual(seen[0]); - }); + expect(seen).toHaveLength(3); + // The whole selection, member by member: identifier, name, checkout path + // and every member of the identity. A Dir that had re-selected anything + // would differ in one of them. + expect(seen[0]).toBeDefined(); + expect(seen[1]).toEqual(seen[0]); + expect(seen[2]).toEqual(seen[0]); + }, + ); // ORC6e: creation is persistent. A directory made inside a region whose // content then fails is still there, and so is one made in a run that was diff --git a/packages/git/tests/run-composition-managed.test.ts b/packages/git/tests/run-composition-managed.test.ts index 6329d9397..ff03522da 100644 --- a/packages/git/tests/run-composition-managed.test.ts +++ b/packages/git/tests/run-composition-managed.test.ts @@ -30,6 +30,7 @@ import { spawn, withResolvers } from "effection"; import { registerComponents } from "@executablemd/core"; import type { ChildOutcome } from "./support/run-composition-child.ts"; import { + ordinaryDocumentCases, causedBy, commonDirectoryOf, countingOrdinaryHost, @@ -50,86 +51,97 @@ import { } from "./support/run-composition.ts"; import { CHILD, REMOTE, entriesOf, isManagedRefusal } from "./support/run-composition-tier.ts"; -describe("ORC8 — managed checkouts are persistent", () => { - it("leaves the checkout, its metadata and its working files after the run", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); - const common = commonDirectoryOf(checkout); - const slot = worktreeSlotOf(root, common, "kept"); - - yield* runOrdinaryDocument( - [ - ``, - `unfinished`, - "", - ].join("\n"), - { root, cwd: checkout.root }, - ); - - expect(yield* exists(slot.checkout)).toBe(true); - expect(yield* exists(`${slot.checkout}/draft.md`)).toBe(true); - const sidecar = yield* readSidecar(slot); - expect(sidecar).toMatchObject({ - kind: "worktree", - version: 1, - name: "kept", - requestedBranch: "kept", - requestedBase: null, - owner: common, - }); - }); - - it("leaves a managed Repository, its metadata and its files after the run", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); - const slot = repositorySlotOf(root, remote.locator, "project"); - - yield* runOrdinaryDocument( - [ - ``, - `unfinished`, - "", - ].join("\n"), - { root, cwd: checkout.root }, - ); +const ordinaryCase = ordinaryDocumentCases("packages/git/tests/run-composition-managed.test.ts"); - expect(yield* exists(`${slot.checkout}/draft.md`)).toBe(true); - expect(yield* readSidecar(slot)).toMatchObject({ - kind: "repository", - version: 1, - name: "project", - locator: remote.locator, - requestedBase: null, - }); - }); +describe("ORC8 — managed checkouts are persistent", () => { + ordinaryCase( + "leaves the checkout, its metadata and its working files after the run", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); + const common = commonDirectoryOf(checkout); + const slot = worktreeSlotOf(root, common, "kept"); + + yield* runFresh( + [ + ``, + `unfinished`, + "", + ].join("\n"), + { root, cwd: checkout.root }, + ); - it("issues no Git or delete command for a checkout while tearing down", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); - const counting = countingOrdinaryHost(); + expect(yield* exists(slot.checkout)).toBe(true); + expect(yield* exists(`${slot.checkout}/draft.md`)).toBe(true); + const sidecar = yield* readSidecar(slot); + expect(sidecar).toMatchObject({ + kind: "worktree", + version: 1, + name: "kept", + requestedBranch: "kept", + requestedBase: null, + owner: common, + }); + }, + ); + + ordinaryCase( + "leaves a managed Repository, its metadata and its files after the run", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); + const slot = repositorySlotOf(root, remote.locator, "project"); + + yield* runFresh( + [ + ``, + `unfinished`, + "", + ].join("\n"), + { root, cwd: checkout.root }, + ); - yield* runOrdinaryDocument( - [ - ``, - ``, - ].join("\n"), - { root, cwd: checkout.root, host: counting.host }, - ); + expect(yield* exists(`${slot.checkout}/draft.md`)).toBe(true); + expect(yield* readSidecar(slot)).toMatchObject({ + kind: "repository", + version: 1, + name: "project", + locator: remote.locator, + requestedBase: null, + }); + }, + ); + + ordinaryCase( + "issues no Git or delete command for a checkout while tearing down", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); + const counting = countingOrdinaryHost(); + + yield* runFresh( + [ + ``, + ``, + ].join("\n"), + { root, cwd: checkout.root, host: counting.host }, + ); - // Nothing that could undo a checkout ever ran — not while the document was - // expanding, and not on the way out. - const issued = subcommands(counting.counters); - for (const undoing of ["reset", "clean", "restore", "prune", "gc", "fetch"]) { - expect(`${undoing} ${issued.includes(undoing)}`).toBe(`${undoing} false`); - } - expect(counting.counters.commands.some((args) => args.includes("--force"))).toBe(false); - expect( - counting.counters.commands.some((args) => args[0] === "worktree" && args[1] === "remove"), - ).toBe(false); - }); + // Nothing that could undo a checkout ever ran — not while the document was + // expanding, and not on the way out. + const issued = subcommands(counting.counters); + for (const undoing of ["reset", "clean", "restore", "prune", "gc", "fetch"]) { + expect(`${undoing} ${issued.includes(undoing)}`).toBe(`${undoing} false`); + } + expect(counting.counters.commands.some((args) => args.includes("--force"))).toBe(false); + expect( + counting.counters.commands.some((args) => args[0] === "worktree" && args[1] === "remove"), + ).toBe(false); + }, + ); it("keeps both kinds of checkout after a cancellation", function* () { const remote = yield* useBareRemote(REMOTE); @@ -156,66 +168,72 @@ describe("ORC8 — managed checkouts are persistent", () => { expect(yield* exists(`${worktree.checkout}/in-flight.md`)).toBe(true); }); - it("keeps a managed Repository after an authored failure inside its body", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); - const slot = repositorySlotOf(root, remote.locator, "surviving"); + ordinaryCase( + "keeps a managed Repository after an authored failure inside its body", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); + const slot = repositorySlotOf(root, remote.locator, "surviving"); - yield* raised( - runOrdinaryDocument( - [ - ``, - `written before the failure`, - ``, - ``, - ``, - "", - ].join("\n"), - { root, cwd: checkout.root }, - ), - ); - - // The path, the sidecar, the Git state and the working file all survive. - expect(yield* exists(slot.checkout)).toBe(true); - expect(yield* readSidecar(slot)).toMatchObject({ - kind: "repository", - version: 1, - name: "surviving", - locator: remote.locator, - }); - expect(yield* readTextFile(`${slot.checkout}/kept.md`)).toBe("written before the failure"); - // The branch the document switched to and the staging it did are both still - // there: nothing rolled back, and nothing was cleaned up on the way out. - expect(git(["rev-parse", "--abbrev-ref", "HEAD"], slot.checkout, checkout.home)).toBe( - "in-progress", - ); - expect(git(["diff", "--cached", "--name-only"], slot.checkout, checkout.home)).toContain( - "kept.md", - ); - }); - - it("keeps the checkout after an authored failure inside the Worktree body", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); - const slot = worktreeSlotOf(root, commonDirectoryOf(checkout), "survivor"); + yield* raised( + runFresh( + [ + ``, + `written before the failure`, + ``, + ``, + ``, + "", + ].join("\n"), + { root, cwd: checkout.root }, + ), + ); - yield* raised( - runOrdinaryDocument( - [ - ``, - `written before the failure`, - ``, - "", - ].join("\n"), - { root, cwd: checkout.root }, - ), - ); + // The path, the sidecar, the Git state and the working file all survive. + expect(yield* exists(slot.checkout)).toBe(true); + expect(yield* readSidecar(slot)).toMatchObject({ + kind: "repository", + version: 1, + name: "surviving", + locator: remote.locator, + }); + expect(yield* readTextFile(`${slot.checkout}/kept.md`)).toBe("written before the failure"); + // The branch the document switched to and the staging it did are both still + // there: nothing rolled back, and nothing was cleaned up on the way out. + expect(git(["rev-parse", "--abbrev-ref", "HEAD"], slot.checkout, checkout.home)).toBe( + "in-progress", + ); + expect(git(["diff", "--cached", "--name-only"], slot.checkout, checkout.home)).toContain( + "kept.md", + ); + }, + ); + + ordinaryCase( + "keeps the checkout after an authored failure inside the Worktree body", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); + const slot = worktreeSlotOf(root, commonDirectoryOf(checkout), "survivor"); + + yield* raised( + runFresh( + [ + ``, + `written before the failure`, + ``, + "", + ].join("\n"), + { root, cwd: checkout.root }, + ), + ); - expect(yield* exists(`${slot.checkout}/kept.md`)).toBe(true); - expect(yield* readSidecar(slot)).toMatchObject({ kind: "worktree" }); - }); + expect(yield* exists(`${slot.checkout}/kept.md`)).toBe(true); + expect(yield* readSidecar(slot)).toMatchObject({ kind: "worktree" }); + }, + ); }); describe("ORC9 — compatible reuse", () => { diff --git a/packages/git/tests/run-composition-remote.test.ts b/packages/git/tests/run-composition-remote.test.ts index a3753204a..07ecc9366 100644 --- a/packages/git/tests/run-composition-remote.test.ts +++ b/packages/git/tests/run-composition-remote.test.ts @@ -33,6 +33,7 @@ import { patches, } from "./support/github.ts"; import { + ordinaryDocumentCases, causedBy, countingOrdinaryHost, fingerprintTree, @@ -56,34 +57,39 @@ import { isAdmissionFailure, } from "./support/run-composition-tier.ts"; +const ordinaryCase = ordinaryDocumentCases("packages/git/tests/run-composition-remote.test.ts"); + describe("ORC14 — live Push evidence", () => { - it("records a performed publication and lets exactly that head be authorized", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); + ordinaryCase( + "records a performed publication and lets exactly that head be authorized", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); - const failure = yield* raised( - runOrdinaryDocument( - [ - ``, - `published`, - ``, - ``, - ``, - ``, - ].join("\n"), - { root, cwd: checkout.root }, - ), - ); + const failure = yield* raised( + runFresh( + [ + ``, + `published`, + ``, + ``, + ``, + ``, + ].join("\n"), + { root, cwd: checkout.root }, + ), + ); - // The branch really is at the remote, at the commit this execution made. - expect(remoteBranch(remote, "published")).toBe(checkout.run("rev-parse", "HEAD")); - // And the pull request got past the evidence gate: what stopped it is the - // adapter declining a locator that is not a github.com repository, which is - // the step *after* the local authorization this criterion is about. - expect(String(failure)).toContain("only for repositories on github.com"); - expect(String(failure)).not.toContain("holds no successful result"); - }); + // The branch really is at the remote, at the commit this execution made. + expect(remoteBranch(remote, "published")).toBe(checkout.run("rev-parse", "HEAD")); + // And the pull request got past the evidence gate: what stopped it is the + // adapter declining a locator that is not a github.com repository, which is + // the step *after* the local authorization this criterion is about. + expect(String(failure)).toContain("only for repositories on github.com"); + expect(String(failure)).not.toContain("holds no successful result"); + }, + ); it("records an already-equal publication the same way it records a performed one", function* () { const remote = yield* useBareRemote(REMOTE); @@ -225,7 +231,7 @@ describe("ORC14 — live Push evidence", () => { expect((stale as LivePushEvidenceError).reason).toBe("conflicting-push-evidence"); }); - it("lets the latest publication of a destination decide", function* () { + ordinaryCase("lets the latest publication of a destination decide", function* (runFresh) { const remote = yield* useBareRemote(REMOTE); const root = yield* useManagedRoot(); const checkout = yield* useHostCheckout(remote.locator); @@ -233,7 +239,7 @@ describe("ORC14 — live Push evidence", () => { // Two publications of one destination, at successive commits, and then a // third commit nothing published. const failure = yield* raised( - runOrdinaryDocument( + runFresh( [ ``, `one`, @@ -258,49 +264,55 @@ describe("ORC14 — live Push evidence", () => { expect(remoteBranch(remote, "moving")).toBe(checkout.run("rev-parse", "HEAD~1")); }); - it("authorizes at the second publication's commit, not the first's", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); + ordinaryCase( + "authorizes at the second publication's commit, not the first's", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); - const failure = yield* raised( - runOrdinaryDocument( - [ - ``, - `one`, - ``, - ``, - ``, - `two`, - ``, - ``, - ``, - ``, - ].join("\n"), - { root, cwd: checkout.root }, - ), - ); - // Past the gate: the latest publication names the head the pull request - // would open from. - expect(String(failure)).toContain("only for repositories on github.com"); - expect(remoteBranch(remote, "latest")).toBe(checkout.run("rev-parse", "HEAD")); - }); + const failure = yield* raised( + runFresh( + [ + ``, + `one`, + ``, + ``, + ``, + `two`, + ``, + ``, + ``, + ``, + ].join("\n"), + { root, cwd: checkout.root }, + ), + ); + // Past the gate: the latest publication names the head the pull request + // would open from. + expect(String(failure)).toContain("only for repositories on github.com"); + expect(remoteBranch(remote, "latest")).toBe(checkout.run("rev-parse", "HEAD")); + }, + ); }); describe("ORC15 — evidence cannot cross runs", () => { - it("refuses a PullRequest in an execution that published nothing", function* () { - const remote = yield* useBareRemote(REMOTE); - const root = yield* useManagedRoot(); - const checkout = yield* useHostCheckout(remote.locator); + ordinaryCase( + "refuses a PullRequest in an execution that published nothing", + function* (runFresh) { + const remote = yield* useBareRemote(REMOTE); + const root = yield* useManagedRoot(); + const checkout = yield* useHostCheckout(remote.locator); - const failure = yield* raised( - runOrdinaryDocument(``, { - root, - cwd: checkout.root, - }), - ); - expect(String(failure)).toContain("holds no successful result"); - }); + const failure = yield* raised( + runFresh(``, { + root, + cwd: checkout.root, + }), + ); + expect(String(failure)).toContain("holds no successful result"); + }, + ); it("does not let one execution's real publication authorize the next", function* () { const remote = yield* useBareRemote(REMOTE); @@ -554,13 +566,13 @@ describe("ORC16 — live Issues", () => { expect(store.requests).toHaveLength(0); }); - it("installs no matching provider when nothing is configured", function* () { + ordinaryCase("installs no matching provider when nothing is configured", function* (runFresh) { const remote = yield* useBareRemote(REMOTE); const root = yield* useManagedRoot(); const checkout = yield* useHostCheckout(remote.locator); const failure = yield* raised( - runOrdinaryDocument(``, { + runFresh(``, { root, cwd: checkout.root, }), @@ -972,7 +984,7 @@ describe("checkout admission is the whole repository identity", () => { * at the end is the ordinary provider's own. */ describe("ORC18 — the authored Git vocabulary", () => { - it("reaches Repository and Git middleware, and still publishes", function* () { + ordinaryCase("reaches Repository and Git middleware, and still publishes", function* (runFresh) { const remote = yield* useBareRemote(REMOTE); const root = yield* useManagedRoot(); const here = yield* useHostCheckout(remote.locator); @@ -980,7 +992,7 @@ describe("ORC18 — the authored Git vocabulary", () => { const selections: string[] = []; const transitions: string[] = []; - yield* runOrdinaryDocument( + yield* runFresh( [ ``, ``, diff --git a/packages/git/tests/support/run-composition.ts b/packages/git/tests/support/run-composition.ts index e1ac9b684..328a415e9 100644 --- a/packages/git/tests/support/run-composition.ts +++ b/packages/git/tests/support/run-composition.ts @@ -8,8 +8,8 @@ * the user's own `~/.xmd/repositories`, and the Git subprocess where a suite * counts invocations. * - * There is no database, no journal and no WorkflowRun anywhere in this file. - * That is the point of the profile: an ordinary run has none of them. + * The ordinary profile installs no run store. The test owns any diagnostic + * snapshot around the execution. */ import { scoped, spawn, suspend, until, withResolvers, type Operation } from "effection"; @@ -25,6 +25,8 @@ import { API, useHostFiles } from "@executablemd/runtime"; import { InMemoryStream } from "@executablemd/durable-streams"; import type { Json } from "@executablemd/durable-streams"; import { useTempDirectory } from "@executablemd/test-support/temp"; +import { it } from "@executablemd/test-support/bdd"; +import { captureTestJournal } from "../../../test-support/failure-journal.ts"; import { useCompositionComponents } from "../../src/composition/installation.ts"; import { RepositoryContext } from "../../src/composition/context.ts"; import type { RepositorySelection } from "../../src/composition/selection.ts"; @@ -236,7 +238,11 @@ export interface RunOptions extends Omit * green on a developer's laptop, red on every shard. A case that is *about* * identity resolution passes its own `identity` and overrides this. */ -export function runOrdinaryDocument(source: string, options: RunOptions): Operation { +export function runOrdinaryDocument( + source: string, + options: RunOptions, + stream = new InMemoryStream(), +): Operation { return scoped(function* () { yield* API.Env.around( { @@ -267,13 +273,25 @@ export function runOrdinaryDocument(source: string, options: RunOptions): Operat return yield* collect( yield* execute({ ...inlineSource(source), - stream: new InMemoryStream(), + stream, ...(options.props === undefined ? {} : { props: options.props }), }), ); }); } +type RunOrdinary = (source: string, options: RunOptions) => Operation; + +export function ordinaryDocumentCases(owner: string) { + return (name: string, body: (run: RunOrdinary) => Operation): void => { + it(name, () => + captureTestJournal({ owner, name }, "", (stream) => + body((source, options) => runOrdinaryDocument(source, options, stream)), + ), + ); + }; +} + /** What a suite reads back about one managed slot. */ export interface ManagedSlot { readonly slot: string; From 78360b837d37045e8ce3314129ec8d3fa333e963 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 13:54:46 -0500 Subject: [PATCH 07/78] test: attribute journals in direct Core document cases --- packages/core/tests/each.test.ts | 162 ++--- packages/core/tests/eval-bindings.test.ts | 58 +- packages/core/tests/eval-error-mode.test.ts | 627 +++++++++--------- packages/core/tests/eval-return.test.ts | 24 +- packages/core/tests/eval-scope.test.ts | 12 +- packages/core/tests/eval-timeout.test.ts | 121 ++-- packages/core/tests/if.test.ts | 110 +-- packages/core/tests/let.test.ts | 156 +++-- packages/core/tests/loop.test.ts | 94 +-- packages/core/tests/sample-component.test.ts | 273 ++++---- packages/core/tests/switch.test.ts | 99 +-- .../core/tests/validation-integration.test.ts | 150 +++-- packages/test-support/journal-cases.ts | 15 + 13 files changed, 1013 insertions(+), 888 deletions(-) create mode 100644 packages/test-support/journal-cases.ts diff --git a/packages/core/tests/each.test.ts b/packages/core/tests/each.test.ts index 819dfd901..c3ec7923f 100644 --- a/packages/core/tests/each.test.ts +++ b/packages/core/tests/each.test.ts @@ -7,11 +7,13 @@ import { expandSegments } from "../src/expand.ts"; import { Component } from "../src/component-api.ts"; import { scanSegments } from "../src/scanner.ts"; import { renderSegments } from "../src/render.ts"; -import { InMemoryStream } from "@executablemd/durable-streams"; import { useStubFs, useEchoExec } from "@executablemd/runtime/test"; import { execute } from "../src/execute.ts"; import { collect } from "../src/collect.ts"; import type { CodeBlockResult, Segment } from "../src/types.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/each.test.ts"); interface EachRun { segments: Segment[]; @@ -217,31 +219,33 @@ describe("Tier Each — native iteration directive", () => { describe("Tier Each — eval in the loop body", () => { beforeAll(() => useTempFileCompiler()); - it("E18: a body eval block reads the current item binding", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "test.md": [ - "```js eval", - "const items = [{ name: 'alpha' }, { name: 'beta' }];", - "```", - '', - "```js eval", - "output('got:' + item.name);", - "```", - "", - ].join("\n"), - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "test.md", stream })); - - expect(output).toContain("got:alpha"); - expect(output).toContain("got:beta"); - expect(output).not.toContain("ERROR"); - }); - - it("E19: renders a table row per item end to end", function* () { - const stream = new InMemoryStream(); + journalCase( + "E18: a body eval block reads the current item binding", + "test.md", + function* (stream) { + yield* useStubFs({ + "test.md": [ + "```js eval", + "const items = [{ name: 'alpha' }, { name: 'beta' }];", + "```", + '', + "```js eval", + "output('got:' + item.name);", + "```", + "", + ].join("\n"), + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "test.md", stream })); + + expect(output).toContain("got:alpha"); + expect(output).toContain("got:beta"); + expect(output).not.toContain("ERROR"); + }, + ); + + journalCase("E19: renders a table row per item end to end", "test.md", function* (stream) { yield* useStubFs({ "test.md": [ "```js eval", @@ -261,54 +265,60 @@ describe("Tier Each — eval in the loop body", () => { expect(output).not.toContain("ERROR"); }); - it("E22: each iteration's eval env is fresh — body bindings do not carry over", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "test.md": [ - "```js eval", - "const items = [1, 2];", - "```", - '', - "```js eval", - "output('iter' + n + ':' + ('carry' in env ? env.carry : 'absent'));", - "env.carry = 'from-' + n;", - "```", - "", - "```js eval", - "output('final:' + (typeof carry === 'undefined' ? 'absent' : carry));", - "```", - ].join("\n"), - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "test.md", stream })); - - expect(output).toContain("iter1:absent"); - expect(output).toContain("iter2:absent"); - expect(output).toContain("final:absent"); - expect(output).not.toContain("ERROR"); - }); - - it("E21: an projected through resolves caller bindings", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": "", - "test.md": [ - "```js eval", - "const items = [{ n: 1 }, { n: 2 }];", - "const label = 'L';", - "```", - "", - '[{label}:{item.n}]', - "", - ].join("\n"), - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "test.md", stream })); - - expect(output).toContain("[L:1]"); - expect(output).toContain("[L:2]"); - expect(output).not.toContain("ERROR"); - }); + journalCase( + "E22: each iteration's eval env is fresh — body bindings do not carry over", + "test.md", + function* (stream) { + yield* useStubFs({ + "test.md": [ + "```js eval", + "const items = [1, 2];", + "```", + '', + "```js eval", + "output('iter' + n + ':' + ('carry' in env ? env.carry : 'absent'));", + "env.carry = 'from-' + n;", + "```", + "", + "```js eval", + "output('final:' + (typeof carry === 'undefined' ? 'absent' : carry));", + "```", + ].join("\n"), + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "test.md", stream })); + + expect(output).toContain("iter1:absent"); + expect(output).toContain("iter2:absent"); + expect(output).toContain("final:absent"); + expect(output).not.toContain("ERROR"); + }, + ); + + journalCase( + "E21: an projected through resolves caller bindings", + "test.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": "", + "test.md": [ + "```js eval", + "const items = [{ n: 1 }, { n: 2 }];", + "const label = 'L';", + "```", + "", + '[{label}:{item.n}]', + "", + ].join("\n"), + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "test.md", stream })); + + expect(output).toContain("[L:1]"); + expect(output).toContain("[L:2]"); + expect(output).not.toContain("ERROR"); + }, + ); }); diff --git a/packages/core/tests/eval-bindings.test.ts b/packages/core/tests/eval-bindings.test.ts index c11817c84..08f35155f 100644 --- a/packages/core/tests/eval-bindings.test.ts +++ b/packages/core/tests/eval-bindings.test.ts @@ -17,12 +17,14 @@ import { asText, completion, failureMessage } from "./helpers.ts"; import type { Json } from "../src/types.ts"; import type { DurableEvent } from "@executablemd/durable-streams"; import type { Operation } from "effection"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/eval-bindings.test.ts"); describe("Tier T5 — Binding environment", () => { beforeAll(() => useTempFileCompiler()); // T38: Block 2 reads binding exported by Block 1 via env preamble - it("T38: block 2 reads binding from block 1", function* () { - const stream = new InMemoryStream(); + journalCase("T38: block 2 reads binding from block 1", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js eval\nconst port = 8080;\n```\n\n```js eval\nconst url = 'http://localhost:' + port;\n```\n", @@ -46,30 +48,32 @@ describe("Tier T5 — Binding environment", () => { }); // T39: Block 3 shadowing Block 1's binding — downstream sees Block 3's value - it("T39: shadowing — later block overrides earlier binding", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "test.md": - "```js eval\nconst x = 1;\n```\n\n```js eval\nconst x = 2;\n```\n\n```js eval\nconst y = x;\n```\n", - }); - yield* useEchoExec(); - - // Should succeed — x is 2 in block 3 (shadowed by block 2) - const output = asText( - yield* collect( - yield* execute({ - path: "test.md", - stream, - }), - ), - ); - - expect(output).not.toContain("ERROR"); - }); + journalCase( + "T39: shadowing — later block overrides earlier binding", + "test.md", + function* (stream) { + yield* useStubFs({ + "test.md": + "```js eval\nconst x = 1;\n```\n\n```js eval\nconst x = 2;\n```\n\n```js eval\nconst y = x;\n```\n", + }); + yield* useEchoExec(); + + // Should succeed — x is 2 in block 3 (shadowed by block 2) + const output = asText( + yield* collect( + yield* execute({ + path: "test.md", + stream, + }), + ), + ); + + expect(output).not.toContain("ERROR"); + }, + ); // T40: Empty block — no exports, no error - it("T40: empty eval block — no exports, no error", function* () { - const stream = new InMemoryStream(); + journalCase("T40: empty eval block — no exports, no error", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js eval\n\n```\n", }); @@ -89,8 +93,7 @@ describe("Tier T5 — Binding environment", () => { // T41: Block referencing undeclared binding not in env — nothing recovers it, // so the run's outcome is that failure. - it("T41: undeclared reference → the run fails", function* () { - const stream = new InMemoryStream(); + journalCase("T41: undeclared reference → the run fails", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js eval\nconst y = undeclaredVar + 1;\n```\n", }); @@ -103,8 +106,7 @@ describe("Tier T5 — Binding environment", () => { }); // T42: Syntax error in block — parse-time error before execution - it("T42: syntax error → the run fails", function* () { - const stream = new InMemoryStream(); + journalCase("T42: syntax error → the run fails", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js eval\nconst x = ;\n```\n", }); diff --git a/packages/core/tests/eval-error-mode.test.ts b/packages/core/tests/eval-error-mode.test.ts index c57dd6c42..0555a1d51 100644 --- a/packages/core/tests/eval-error-mode.test.ts +++ b/packages/core/tests/eval-error-mode.test.ts @@ -9,14 +9,16 @@ * the block projects. */ -import { beforeAll, describe, it } from "@executablemd/test-support/bdd"; +import { beforeAll, describe } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { InMemoryStream } from "@executablemd/durable-streams"; import { useEchoExec, useStubFs } from "@executablemd/runtime/test"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import { execute } from "../src/execute.ts"; import { collect } from "../src/collect.ts"; import { DocumentationError } from "../src/errors.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/eval-error-mode.test.ts"); const PROJECTING_BLOCK = [ "```ts persist eval", @@ -30,332 +32,365 @@ describe("Tier O — Eval scope hierarchy", () => { // O23: the block sits in documentation, so its projection settles under the // throwing error mode — the failure aborts the body instead of rendering. - it("O23: a persistent projection in documentation settles under the throwing error mode", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": [...PROJECTING_BLOCK, "", "", "done", ""].join("\n"), - "doc.md": "\n\n", - }); - yield* useEchoExec(); - - let failure: unknown; - try { - yield* collect(yield* execute({ path: "doc.md", stream })); - } catch (error) { - failure = error; - } - - // Documentation fail-fast: the projected error aborts the body rather than - // rendering, which a printing error mode would never do. - expect(failure).toBeInstanceOf(DocumentationError); - expect(String(failure)).toContain("Missing"); - }); + journalCase( + "O23: a persistent projection in documentation settles under the throwing error mode", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": [...PROJECTING_BLOCK, "", "", "done", ""].join("\n"), + "doc.md": "\n\n", + }); + yield* useEchoExec(); + + let failure: unknown; + try { + yield* collect(yield* execute({ path: "doc.md", stream })); + } catch (error) { + failure = error; + } + + // Documentation fail-fast: the projected error aborts the body rather than + // rendering, which a printing error mode would never do. + expect(failure).toBeInstanceOf(DocumentationError); + expect(String(failure)).toContain("Missing"); + }, + ); // O28: a claimed in a documentation region settles under the // throwing error mode — the projected error stops the body instead of being // printed and then discarded with the region's rendered output. - it("O28: Markdown in documentation fails fast on a projected error", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": ["", "", "", "done", ""].join("\n"), - "doc.md": "\n\n", - }); - yield* useEchoExec(); - - let failure: unknown; - try { - yield* collect(yield* execute({ path: "doc.md", stream })); - } catch (error) { - failure = error; - } - - expect(failure).toBeInstanceOf(DocumentationError); - expect(String(failure)).toContain("Missing"); - }); + journalCase( + "O28: Markdown in documentation fails fast on a projected error", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": ["", "", "", "done", ""].join("\n"), + "doc.md": "\n\n", + }); + yield* useEchoExec(); + + let failure: unknown; + try { + yield* collect(yield* execute({ path: "doc.md", stream })); + } catch (error) { + failure = error; + } + + expect(failure).toBeInstanceOf(DocumentationError); + expect(String(failure)).toContain("Missing"); + }, + ); // O29: the same projection inside carries the region's error mode, // so the projected error fails the region and nothing after it renders. - it("O29: Markdown inside fails the region on a projected error", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": ["", "", "", "done", ""].join("\n"), - "doc.md": "\n\n", - }); - yield* useEchoExec(); - - let failure: unknown; - try { - yield* collect(yield* execute({ path: "doc.md", stream })); - } catch (error) { - failure = error; - } - - expect(String(failure)).toContain("Missing"); - }); + journalCase( + "O29: Markdown inside fails the region on a projected error", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": ["", "", "", "done", ""].join("\n"), + "doc.md": "\n\n", + }); + yield* useEchoExec(); + + let failure: unknown; + try { + yield* collect(yield* execute({ path: "doc.md", stream })); + } catch (error) { + failure = error; + } + + expect(String(failure)).toContain("Missing"); + }, + ); // O30: value-component documentation carries the same error mode, so a claimed // that projects an error fails fast instead of being discarded // along with the documentation's rendered output. - it("O30: a projected error in value-component documentation fails fast", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Value.md": [ - "---", - "returns:", - " ok: { type: boolean }", - "---", - "", - "", - "", - '', - ].join("\n"), - "doc.md": '\n\n\n\nafter', - }); - yield* useEchoExec(); - - let failure: unknown; - try { - yield* collect(yield* execute({ path: "doc.md", stream })); - } catch (error) { - failure = error; - } - - expect(failure).toBeInstanceOf(DocumentationError); - expect(String(failure)).toContain("Missing"); - }); + journalCase( + "O30: a projected error in value-component documentation fails fast", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Value.md": [ + "---", + "returns:", + " ok: { type: boolean }", + "---", + "", + "", + "", + '', + ].join("\n"), + "doc.md": '\n\n\n\nafter', + }); + yield* useEchoExec(); + + let failure: unknown; + try { + yield* collect(yield* execute({ path: "doc.md", stream })); + } catch (error) { + failure = error; + } + + expect(failure).toBeInstanceOf(DocumentationError); + expect(String(failure)).toContain("Missing"); + }, + ); // O25: an evaluation sees the bindings that existed when it started, and its // declared exports become shared once it completes. - it("O25: exports are committed to the shared bindings for later blocks", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "doc.md": [ - "```js eval", - "const port = 4321;", - // A function is not JSON, so the journal cannot carry it: only the - // explicit commit makes it reachable from the next block. - "const describe = (n) => `port-${n}`;", - "```", - "", - "```js eval", - "output(`port=${port} ${describe(port)}`);", - "```", - ].join("\n"), - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "doc.md", stream })); - - // `describe` is a function — `serializeExports` drops it, so reaching it - // from the next block proves the commit publishes live values. - expect(output).toContain("port=4321 port-4321"); - }); + journalCase( + "O25: exports are committed to the shared bindings for later blocks", + "doc.md", + function* (stream) { + yield* useStubFs({ + "doc.md": [ + "```js eval", + "const port = 4321;", + // A function is not JSON, so the journal cannot carry it: only the + // explicit commit makes it reachable from the next block. + "const describe = (n) => `port-${n}`;", + "```", + "", + "```js eval", + "output(`port=${port} ${describe(port)}`);", + "```", + ].join("\n"), + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "doc.md", stream })); + + // `describe` is a function — `serializeExports` drops it, so reaching it + // from the next block proves the commit publishes live values. + expect(output).toContain("port=4321 port-4321"); + }, + ); // O26: persistent work keeps the values and the mode-bound capabilities it // captured; a later evaluation gets its own snapshot and cannot reach in. - it("O26: a later evaluation cannot alter an earlier block's captured bindings", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": [ - "```js persist eval", - "const captured = { seen: null };", - "const renderer = renderChildren;", - "yield* spawn(function*() {", - " yield* sleep(5);", - " captured.seen = typeof renderer;", - "});", - "```", - "", - "```js eval", - "const renderer = null;", - "```", - "", - "```js eval", - "yield* when(function*() {", - ' if (captured.seen === null) throw new Error("not yet");', - "});", - "output(`seen=${captured.seen}`);", - "```", - ].join("\n"), - "doc.md": "\ncontent\n", - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "doc.md", stream })); - - // The middle block rebinding `renderer` did not reach the closure the - // persistent task captured from its own snapshot. - expect(output).toContain("seen=function"); - }); + journalCase( + "O26: a later evaluation cannot alter an earlier block's captured bindings", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": [ + "```js persist eval", + "const captured = { seen: null };", + "const renderer = renderChildren;", + "yield* spawn(function*() {", + " yield* sleep(5);", + " captured.seen = typeof renderer;", + "});", + "```", + "", + "```js eval", + "const renderer = null;", + "```", + "", + "```js eval", + "yield* when(function*() {", + ' if (captured.seen === null) throw new Error("not yet");', + "});", + "output(`seen=${captured.seen}`);", + "```", + ].join("\n"), + "doc.md": "\ncontent\n", + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "doc.md", stream })); + + // The middle block rebinding `renderer` did not reach the closure the + // persistent task captured from its own snapshot. + expect(output).toContain("seen=function"); + }, + ); // O27: an explicit import shadows the injected binding without the preamble // declaring it twice — the module would not compile otherwise. - it("O27: an explicitly imported useContent compiles alongside the injected one", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": [ - "```ts eval", - 'import { useContent } from "@executablemd/core";', - "const kind = typeof useContent;", - "output(`imported=${kind}`);", - "```", - ].join("\n"), - "doc.md": "\ncontent\n", - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "doc.md", stream })); - - expect(output).toContain("imported=function"); - expect(output).not.toContain("ERROR"); - }); + journalCase( + "O27: an explicitly imported useContent compiles alongside the injected one", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": [ + "```ts eval", + 'import { useContent } from "@executablemd/core";', + "const kind = typeof useContent;", + "output(`imported=${kind}`);", + "```", + ].join("\n"), + "doc.md": "\ncontent\n", + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "doc.md", stream })); + + expect(output).toContain("imported=function"); + expect(output).not.toContain("ERROR"); + }, + ); // O24: the same block inside an region settles under `output`, so // the projected error fails the run rather than rendering as a comment. - it("O24: a persistent projection inside settles under the output error mode", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": ["", ...PROJECTING_BLOCK, ""].join("\n"), - "doc.md": "\n\n", - }); - yield* useEchoExec(); - - let failure: unknown; - try { - yield* collect(yield* execute({ path: "doc.md", stream })); - } catch (error) { - failure = error; - } - - expect(String(failure)).toContain("Missing"); - }); + journalCase( + "O24: a persistent projection inside settles under the output error mode", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": ["", ...PROJECTING_BLOCK, ""].join("\n"), + "doc.md": "\n\n", + }); + yield* useEchoExec(); + + let failure: unknown; + try { + yield* collect(yield* execute({ path: "doc.md", stream })); + } catch (error) { + failure = error; + } + + expect(String(failure)).toContain("Missing"); + }, + ); // O31: the same printing projection, captured — the string rendered the // error away, so the capture is refused (§6.5) and the recorded segment // returns to the caller instead of hiding inside the bound string. - it("O31: a captured markdown projection refuses the binding on a projected error", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": [ - "", - "", - ...PROJECTING_BLOCK, - "", - "", - ].join("\n"), - "doc.md": '\n\n\n\nvalue:{cap}:end', - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "doc.md", stream })); - - expect(output).toContain("ERROR"); - // The binding stays unset, so the interpolation stays literal and the - // sibling text still renders under the printing error mode. - expect(output).toContain("value:{cap}:end"); - // Reported once on the way out, not again when it crosses back. - expect(String(output).split("Cannot resolve component: Missing").length - 1).toBe(1); - }); + journalCase( + "O31: a captured markdown projection refuses the binding on a projected error", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": [ + "", + "", + ...PROJECTING_BLOCK, + "", + "", + ].join("\n"), + "doc.md": '\n\n\n\nvalue:{cap}:end', + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "doc.md", stream })); + + expect(output).toContain("ERROR"); + // The binding stays unset, so the interpolation stays literal and the + // sibling text still renders under the printing error mode. + expect(output).toContain("value:{cap}:end"); + // Reported once on the way out, not again when it crosses back. + expect(String(output).split("Cannot resolve component: Missing").length - 1).toBe(1); + }, + ); // O32: a caught DocumentationError is explicit recovery. The throw-bound // projection fails before anything is recorded for the capture refusal, so // the recovered component completes and the capture succeeds. - it("O32: a caught projection error recovers without a later capture refusal", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": [ - "```ts eval", - "const projected = yield* call(function* () {", - " try {", - " return yield* renderChildren();", - " } catch (error) {", - ' return "recovered";', - " }", - "});", - "```", - "", - "", - "```ts eval", - "output(projected);", - "```", - "", - ].join("\n"), - "doc.md": '\n\n\n\nvalue:{cap}:end', - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "doc.md", stream })); - - // The caught error is not reasserted: the binding holds the recovered - // output and no error segment reaches the caller. - expect(output).toContain("recovered"); - expect(output).not.toContain("{cap}"); - expect(output).not.toContain("ERROR"); - }); + journalCase( + "O32: a caught projection error recovers without a later capture refusal", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": [ + "```ts eval", + "const projected = yield* call(function* () {", + " try {", + " return yield* renderChildren();", + " } catch (error) {", + ' return "recovered";', + " }", + "});", + "```", + "", + "", + "```ts eval", + "output(projected);", + "```", + "", + ].join("\n"), + "doc.md": '\n\n\n\nvalue:{cap}:end', + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "doc.md", stream })); + + // The caught error is not reasserted: the binding holds the recovered + // output and no error segment reaches the caller. + expect(output).toContain("recovered"); + expect(output).not.toContain("{cap}"); + expect(output).not.toContain("ERROR"); + }, + ); // O33: work the projected content started is torn down with its scope, not // leaked past the invocation because the projection's error was caught. - it("O33: projection-owned work does not escape a caught projection error", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": [ - "```ts eval", - "const projected = yield* call(function* () {", - " try {", - " return yield* renderChildren();", - " } catch (error) {", - ' return "recovered";', - " }", - "});", - "```", - "", - "", - "```ts eval", - "output(projected);", - "```", - "", - ].join("\n"), - "doc.md": [ - "```js eval", - "const probe = { started: false, halted: false };", - "```", - "", - '', - "```js persist eval", - "yield* spawn(function*() {", - " probe.started = true;", - " try {", - " yield* suspend();", - " } finally {", - " probe.halted = true;", - " }", - "});", - "```", - "", - "```js eval", - "yield* when(function*() {", - ' if (!probe.started) throw new Error("not yet");', - "});", - "```", - "", - "", - "", - "", - "value:{cap}:end", - "", - "```js eval", - "output(`halted=${probe.halted}`);", - "```", - ].join("\n"), - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "doc.md", stream })); - - // The suspended task the children spawned is gone by the time the sibling - // runs: recovery completed, and catching the error leaked nothing. - expect(output).toContain("recovered"); - expect(output).toContain("halted=true"); - expect(output).not.toContain("ERROR"); - }); + journalCase( + "O33: projection-owned work does not escape a caught projection error", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": [ + "```ts eval", + "const projected = yield* call(function* () {", + " try {", + " return yield* renderChildren();", + " } catch (error) {", + ' return "recovered";', + " }", + "});", + "```", + "", + "", + "```ts eval", + "output(projected);", + "```", + "", + ].join("\n"), + "doc.md": [ + "```js eval", + "const probe = { started: false, halted: false };", + "```", + "", + '', + "```js persist eval", + "yield* spawn(function*() {", + " probe.started = true;", + " try {", + " yield* suspend();", + " } finally {", + " probe.halted = true;", + " }", + "});", + "```", + "", + "```js eval", + "yield* when(function*() {", + ' if (!probe.started) throw new Error("not yet");', + "});", + "```", + "", + "", + "", + "", + "value:{cap}:end", + "", + "```js eval", + "output(`halted=${probe.halted}`);", + "```", + ].join("\n"), + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "doc.md", stream })); + + // The suspended task the children spawned is gone by the time the sibling + // runs: recovery completed, and catching the error leaked nothing. + expect(output).toContain("recovered"); + expect(output).toContain("halted=true"); + expect(output).not.toContain("ERROR"); + }, + ); }); diff --git a/packages/core/tests/eval-return.test.ts b/packages/core/tests/eval-return.test.ts index 6db39cdbb..f23f11600 100644 --- a/packages/core/tests/eval-return.test.ts +++ b/packages/core/tests/eval-return.test.ts @@ -12,12 +12,14 @@ import { InMemoryStream } from "@executablemd/durable-streams"; import { useStubFs, useEchoExec } from "@executablemd/runtime/test"; import { execute } from "../src/execute.ts"; import { collect } from "../src/collect.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/eval-return.test.ts"); describe("Eval block return value", () => { beforeAll(() => useTempFileCompiler()); // ER1: return string → rendered output - it("ER1: return string → rendered output", function* () { - const stream = new InMemoryStream(); + journalCase("ER1: return string → rendered output", "test.md", function* (stream) { yield* useStubFs({ "test.md": '```js eval\nreturn "hello from eval";\n```\n', }); @@ -34,8 +36,7 @@ describe("Eval block return value", () => { }); // ER2: return number → coerced to string - it("ER2: return number → coerced to string", function* () { - const stream = new InMemoryStream(); + journalCase("ER2: return number → coerced to string", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js eval\nreturn 42;\n```\n", }); @@ -52,8 +53,7 @@ describe("Eval block return value", () => { }); // ER3: return null → no output - it("ER3: return null → no output", function* () { - const stream = new InMemoryStream(); + journalCase("ER3: return null → no output", "test.md", function* (stream) { yield* useStubFs({ "test.md": "before\n```js eval\nreturn null;\n```\nafter", }); @@ -71,8 +71,7 @@ describe("Eval block return value", () => { }); // ER4: return undefined → no output - it("ER4: return undefined → no output", function* () { - const stream = new InMemoryStream(); + journalCase("ER4: return undefined → no output", "test.md", function* (stream) { yield* useStubFs({ "test.md": "before\n```js eval\nreturn undefined;\n```\nafter", }); @@ -89,8 +88,7 @@ describe("Eval block return value", () => { }); // ER5: output() takes precedence over return - it("ER5: output() takes precedence over return", function* () { - const stream = new InMemoryStream(); + journalCase("ER5: output() takes precedence over return", "test.md", function* (stream) { yield* useStubFs({ "test.md": '```js eval\noutput("explicit");\nreturn "ignored";\n```\n', }); @@ -108,8 +106,7 @@ describe("Eval block return value", () => { }); // ER6: return in persist eval → works same as normal - it("ER6: return in persist eval → works same as normal", function* () { - const stream = new InMemoryStream(); + journalCase("ER6: return in persist eval → works same as normal", "test.md", function* (stream) { yield* useStubFs({ "test.md": '```js persist eval\nreturn "persisted output";\n```\n', }); @@ -126,8 +123,7 @@ describe("Eval block return value", () => { }); // ER7: no return → no output (existing behavior) - it("ER7: no return → no output (existing behavior)", function* () { - const stream = new InMemoryStream(); + journalCase("ER7: no return → no output (existing behavior)", "test.md", function* (stream) { yield* useStubFs({ "test.md": "before\n```js eval\nconst x = 42;\n```\nafter", }); diff --git a/packages/core/tests/eval-scope.test.ts b/packages/core/tests/eval-scope.test.ts index 14f937f5a..7dc8f9285 100644 --- a/packages/core/tests/eval-scope.test.ts +++ b/packages/core/tests/eval-scope.test.ts @@ -4,21 +4,22 @@ * Tests that eval scopes are properly scoped to components and * that child/parent scope relationships work correctly. */ -import { describe, it, beforeAll } from "@executablemd/test-support/bdd"; +import { describe, beforeAll } from "@executablemd/test-support/bdd"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import { expect } from "@executablemd/test-support/expect"; -import { InMemoryStream } from "@executablemd/durable-streams"; import { Stdio } from "@effectionx/process"; import { useStubFs, useEchoExec } from "@executablemd/runtime/test"; import { execute } from "../src/execute.ts"; import { collect } from "../src/collect.ts"; import { asText } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/eval-scope.test.ts"); describe("Tier T10 — eval-scope hierarchy", () => { beforeAll(() => useTempFileCompiler()); // T61: Document with eval blocks — scope created per document - it("T61: eval blocks run within document scope", function* () { - const stream = new InMemoryStream(); + journalCase("T61: eval blocks run within document scope", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js eval\nconst a = 1;\n```\n\n```js eval\nconst b = a + 1;\n```\n", }); @@ -40,8 +41,7 @@ describe("Tier T10 — eval-scope hierarchy", () => { }); // T62: Eval blocks coexist with exec blocks - it("T62: eval and exec blocks coexist", function* () { - const stream = new InMemoryStream(); + journalCase("T62: eval and exec blocks coexist", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js eval\nconst x = 42;\n```\n\n```bash exec\necho hello\n```\n\n```js eval\nconst y = x + 1;\n```\n", diff --git a/packages/core/tests/eval-timeout.test.ts b/packages/core/tests/eval-timeout.test.ts index 4e01570d9..6c6bb6e16 100644 --- a/packages/core/tests/eval-timeout.test.ts +++ b/packages/core/tests/eval-timeout.test.ts @@ -10,18 +10,19 @@ import { describe, it, beforeAll } from "@executablemd/test-support/bdd"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import { expect } from "@executablemd/test-support/expect"; -import { InMemoryStream } from "@executablemd/durable-streams"; import { Config } from "@executablemd/runtime"; import { useStubFs, useEchoExec } from "@executablemd/runtime/test"; import { execute } from "../src/execute.ts"; import { collect } from "../src/collect.ts"; import { completion, failureMessage } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/eval-timeout.test.ts"); describe("Tier T7 — timeout modifier", () => { beforeAll(() => useTempFileCompiler()); - it("T49: block completes before timeout → success", function* () { - const stream = new InMemoryStream(); + journalCase("T49: block completes before timeout → success", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js timeout=30s eval\nconst x = 42;\n```\n", }); @@ -38,60 +39,72 @@ describe("Tier T7 — timeout modifier", () => { expect(output).not.toContain("ERROR"); }); - it("T50: a bare timeout boxes the block at the run's exec default", function* () { - const stream = new InMemoryStream(); - yield* Config.around({ timeoutExec: () => 30_000 }, { at: "min" }); - yield* useStubFs({ - "test.md": "```js timeout eval\nconst x = 1;\n```\n", - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "test.md", stream })); - - expect(output).not.toContain("timed out"); - }); - - it("T50a: a bare timeout with no exec default refuses instead of running unbounded", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "test.md": "```js timeout eval\nconst x = 1;\n```\n", - }); - - const result = yield* completion({ path: "test.md", stream }); - - expect(result.ok).toBe(false); - expect(failureMessage(result)).toContain("names no duration"); - }); + journalCase( + "T50: a bare timeout boxes the block at the run's exec default", + "test.md", + function* (stream) { + yield* Config.around({ timeoutExec: () => 30_000 }, { at: "min" }); + yield* useStubFs({ + "test.md": "```js timeout eval\nconst x = 1;\n```\n", + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "test.md", stream })); + + expect(output).not.toContain("timed out"); + }, + ); + + journalCase( + "T50a: a bare timeout with no exec default refuses instead of running unbounded", + "test.md", + function* (stream) { + yield* useStubFs({ + "test.md": "```js timeout eval\nconst x = 1;\n```\n", + }); + + const result = yield* completion({ path: "test.md", stream }); + + expect(result.ok).toBe(false); + expect(failureMessage(result)).toContain("names no duration"); + }, + ); /** * The timebox itself, at the value the run configured: an eval block that * sleeps past it is cancelled, and the message names the duration used. */ - it("T57: the timebox of a bare timeout is the run's exec default", function* () { - const stream = new InMemoryStream(); - yield* Config.around({ timeoutExec: () => 25 }, { at: "min" }); - yield* useStubFs({ - "test.md": '```ts timeout eval\nyield* sleep(300);\noutput("SLEPT");\n```\n', - }); - - const result = yield* completion({ path: "test.md", stream }); - - expect(result.ok).toBe(false); - expect(failureMessage(result)).toContain("eval block timed out after 25ms"); - expect(failureMessage(result)).not.toContain("SLEPT"); - }); - - it("T58: a declared duration boxes the block at what it declared", function* () { - const stream = new InMemoryStream(); - yield* Config.around({ timeoutExec: () => 60_000 }, { at: "min" }); - yield* useStubFs({ - "test.md": '```ts timeout=25ms eval\nyield* sleep(300);\noutput("SLEPT");\n```\n', - }); - - const result = yield* completion({ path: "test.md", stream }); - - expect(result.ok).toBe(false); - expect(failureMessage(result)).toContain("eval block timed out after 25ms"); - expect(failureMessage(result)).not.toContain("SLEPT"); - }); + journalCase( + "T57: the timebox of a bare timeout is the run's exec default", + "test.md", + function* (stream) { + yield* Config.around({ timeoutExec: () => 25 }, { at: "min" }); + yield* useStubFs({ + "test.md": '```ts timeout eval\nyield* sleep(300);\noutput("SLEPT");\n```\n', + }); + + const result = yield* completion({ path: "test.md", stream }); + + expect(result.ok).toBe(false); + expect(failureMessage(result)).toContain("eval block timed out after 25ms"); + expect(failureMessage(result)).not.toContain("SLEPT"); + }, + ); + + journalCase( + "T58: a declared duration boxes the block at what it declared", + "test.md", + function* (stream) { + yield* Config.around({ timeoutExec: () => 60_000 }, { at: "min" }); + yield* useStubFs({ + "test.md": '```ts timeout=25ms eval\nyield* sleep(300);\noutput("SLEPT");\n```\n', + }); + + const result = yield* completion({ path: "test.md", stream }); + + expect(result.ok).toBe(false); + expect(failureMessage(result)).toContain("eval block timed out after 25ms"); + expect(failureMessage(result)).not.toContain("SLEPT"); + }, + ); }); diff --git a/packages/core/tests/if.test.ts b/packages/core/tests/if.test.ts index 696e75d11..a3cccc579 100644 --- a/packages/core/tests/if.test.ts +++ b/packages/core/tests/if.test.ts @@ -21,6 +21,9 @@ import { Sample } from "../src/sample-api.ts"; import { readTextFile } from "@effectionx/fs"; import type { ComponentElement, FunctionComponentDefinition, Segment } from "../src/types.ts"; import { asText } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/if.test.ts"); interface IfRun { segments: Segment[]; @@ -478,41 +481,47 @@ describe("Tier IF — document execution", () => { expect(evaluated).not.toContain("UNSELECTED_RAN"); }); - it("IF40: an effect in the unselected branch never happens", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "test.md": [ - "", - "```js eval", - "throw new Error('UNSELECTED_EFFECT');", - "```", - "selected", - "", - ].join("\n"), - }); - yield* useEchoExec(); + journalCase( + "IF40: an effect in the unselected branch never happens", + "test.md", + function* (stream) { + yield* useStubFs({ + "test.md": [ + "", + "```js eval", + "throw new Error('UNSELECTED_EFFECT');", + "```", + "selected", + "", + ].join("\n"), + }); + yield* useEchoExec(); - const output = yield* collect(yield* execute({ path: "test.md", stream })); + const output = yield* collect(yield* execute({ path: "test.md", stream })); - expect(output).toContain("selected"); - expect(output).not.toContain("UNSELECTED_EFFECT"); - expect(output).not.toContain("ERROR"); - }); + expect(output).toContain("selected"); + expect(output).not.toContain("UNSELECTED_EFFECT"); + expect(output).not.toContain("ERROR"); + }, + ); - it("IF41: a component in the unselected branch is never imported", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Boom.md": "```js eval\noutput('BOOM_RAN');\n```\n", - "test.md": "alt", - }); - yield* useEchoExec(); + journalCase( + "IF41: a component in the unselected branch is never imported", + "test.md", + function* (stream) { + yield* useStubFs({ + "components/Boom.md": "```js eval\noutput('BOOM_RAN');\n```\n", + "test.md": "alt", + }); + yield* useEchoExec(); - const output = yield* collect(yield* execute({ path: "test.md", stream })); + const output = yield* collect(yield* execute({ path: "test.md", stream })); - expect(output).toContain("alt"); - expect(output).not.toContain("BOOM_RAN"); - expect(output).not.toContain("ERROR"); - }); + expect(output).toContain("alt"); + expect(output).not.toContain("BOOM_RAN"); + expect(output).not.toContain("ERROR"); + }, + ); it("IF42: selects the same branch from a restored binding on partial replay", function* () { const REPLAY_DOC = [ @@ -561,27 +570,30 @@ describe("Tier IF — document execution", () => { expect(evaluated).not.toContain("CLEAN_RAN"); }); - it("IF43: an projected through resolves the caller's binding", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Wrap.md": "", - "test.md": [ - "```js eval", - "const ready = false;", - "```", - "", - "READYWAITING", - "", - ].join("\n"), - }); - yield* useEchoExec(); + journalCase( + "IF43: an projected through resolves the caller's binding", + "test.md", + function* (stream) { + yield* useStubFs({ + "components/Wrap.md": "", + "test.md": [ + "```js eval", + "const ready = false;", + "```", + "", + "READYWAITING", + "", + ].join("\n"), + }); + yield* useEchoExec(); - const output = yield* collect(yield* execute({ path: "test.md", stream })); + const output = yield* collect(yield* execute({ path: "test.md", stream })); - expect(output).toContain("WAITING"); - expect(output).not.toContain("READY"); - expect(output).not.toContain("ERROR"); - }); + expect(output).toContain("WAITING"); + expect(output).not.toContain("READY"); + expect(output).not.toContain("ERROR"); + }, + ); }); /** diff --git a/packages/core/tests/let.test.ts b/packages/core/tests/let.test.ts index c6cd810ea..1b42963d7 100644 --- a/packages/core/tests/let.test.ts +++ b/packages/core/tests/let.test.ts @@ -23,6 +23,9 @@ import { Component } from "../src/component-api.ts"; import { scanSegments } from "../src/scanner.ts"; import { renderSegments } from "../src/render.ts"; import { execute, executeInstalled } from "../src/execute.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/let.test.ts"); import type { HostExecution } from "../src/execute.ts"; import { inlineSource } from "../src/root-source.ts"; import { collect } from "../src/collect.ts"; @@ -454,46 +457,49 @@ describe("Tier LET — failure and overwrite", () => { describe("Tier LET — a whole document", () => { beforeAll(() => useTempFileCompiler()); - it("LET10: a direct binding reaches prose, an expression prop, and a later eval", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": [ - "```ts eval", - 'const settings = { title: "Release" };', - "```", - "", - '', - "", - '', - "", - "Prose reads {title}.", - "", - "", - "", - "```ts eval", - 'return alias === settings ? "identical" : "different";', - "```", - ].join("\n"), - "components/Note.md": [ - "---", - "props:", - " type: object", - " properties:", - " label:", - " type: string", - " additionalProperties: false", - "---", - "", - "Note says {props.label}.", - ].join("\n"), - }); + journalCase( + "LET10: a direct binding reaches prose, an expression prop, and a later eval", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": [ + "```ts eval", + 'const settings = { title: "Release" };', + "```", + "", + '', + "", + '', + "", + "Prose reads {title}.", + "", + "", + "", + "```ts eval", + 'return alias === settings ? "identical" : "different";', + "```", + ].join("\n"), + "components/Note.md": [ + "---", + "props:", + " type: object", + " properties:", + " label:", + " type: string", + " additionalProperties: false", + "---", + "", + "Note says {props.label}.", + ].join("\n"), + }); - const output = asText(yield* collect(yield* execute({ path: "README.md", stream }))); + const output = asText(yield* collect(yield* execute({ path: "README.md", stream }))); - expect(output).toContain("Prose reads Release."); - expect(output).toContain("Note says Release."); - expect(output).toContain("identical"); - }); + expect(output).toContain("Prose reads Release."); + expect(output).toContain("Note says Release."); + expect(output).toContain("identical"); + }, + ); it("LET11: a partial replay rebinds by reference and records nothing of its own", function* () { const document = [ @@ -542,19 +548,22 @@ describe("Tier LET — a whole document", () => { ]); }); - it("LET12: Let is the syntax; Capture is an ordinary component", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": ['', "", ""].join("\n"), - "components/Let.md": "A REPOSITORY FILE RAN\n", - "components/Capture.md": "an ordinary component ran.\n", - }); + journalCase( + "LET12: Let is the syntax; Capture is an ordinary component", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": ['', "", ""].join("\n"), + "components/Let.md": "A REPOSITORY FILE RAN\n", + "components/Capture.md": "an ordinary component ran.\n", + }); - const output = asText(yield* collect(yield* execute({ path: "README.md", stream }))); + const output = asText(yield* collect(yield* execute({ path: "README.md", stream }))); - expect(output).toContain("an ordinary component ran."); - expect(output).not.toContain("A REPOSITORY FILE RAN"); - }); + expect(output).toContain("an ordinary component ran."); + expect(output).not.toContain("A REPOSITORY FILE RAN"); + }, + ); }); /** @@ -729,29 +738,32 @@ describe("Tier LET — the ordinary inventory, and which values are eligible", ( expect(stream.snapshot().map(kindOf)).toEqual(["import_component", "eval", "close"]); }); - it("C7: the eligible data is the JSON subset of the same document's root", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ "README.md": EVERY_KIND }); - - const execution = yield* executeInstalled({ path: "README.md", stream }, []); - const settled = yield* execution; - expect(settled.ok).toBe(true); - - // The live bindings are unchanged — the document read every one of them - // above — and what crosses is decided by one strict JSON walk rather than - // by which construct produced the value. - const held = yield* readBindings(execution); - expect(held["nested"]).toEqual({ list: [1, { deep: true }], nothing: null }); - expect(held["nothing"]).toBe(null); - expect(held["rendered"]).toBe("plain text"); - // Omitted whole, never coerced: a value that is not plain JSON, a cycle, a - // sparse hole, a non-finite number, `undefined` and a function. - for (const omitted of ["notPlain", "cycle", "sparse", "infinite", "absent", "work"]) { - expect(Object.hasOwn(held, omitted)).toBe(false); - } - // `props` is each execution's own namespace and never crosses. - expect(Object.hasOwn(held, "props")).toBe(false); - }); + journalCase( + "C7: the eligible data is the JSON subset of the same document's root", + "README.md", + function* (stream) { + yield* useStubFs({ "README.md": EVERY_KIND }); + + const execution = yield* executeInstalled({ path: "README.md", stream }, []); + const settled = yield* execution; + expect(settled.ok).toBe(true); + + // The live bindings are unchanged — the document read every one of them + // above — and what crosses is decided by one strict JSON walk rather than + // by which construct produced the value. + const held = yield* readBindings(execution); + expect(held["nested"]).toEqual({ list: [1, { deep: true }], nothing: null }); + expect(held["nothing"]).toBe(null); + expect(held["rendered"]).toBe("plain text"); + // Omitted whole, never coerced: a value that is not plain JSON, a cycle, a + // sparse hole, a non-finite number, `undefined` and a function. + for (const omitted of ["notPlain", "cycle", "sparse", "infinite", "absent", "work"]) { + expect(Object.hasOwn(held, omitted)).toBe(false); + } + // `props` is each execution's own namespace and never crosses. + expect(Object.hasOwn(held, "props")).toBe(false); + }, + ); }); describe("Tier LET — the computed root data an execution hands back", () => { beforeAll(() => useTempFileCompiler()); diff --git a/packages/core/tests/loop.test.ts b/packages/core/tests/loop.test.ts index 08cac0564..ae8c95a14 100644 --- a/packages/core/tests/loop.test.ts +++ b/packages/core/tests/loop.test.ts @@ -19,6 +19,9 @@ import { collect } from "../src/collect.ts"; import { printErrors } from "../src/component-failures.ts"; import type { ComponentElement, FunctionComponent, Segment } from "../src/types.ts"; import { asText } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/loop.test.ts"); interface LoopRun { segments: Segment[]; @@ -744,8 +747,7 @@ describe("Tier LOOP — document execution", () => { expect(evalNames(stream.snapshot())).toHaveLength(1); }); - it("LOOP37: a binding accumulates across iterations", function* () { - const stream = new InMemoryStream(); + journalCase("LOOP37: a binding accumulates across iterations", "test.md", function* (stream) { yield* useHostFiles(); yield* useStubFs({ "test.md": [ @@ -773,19 +775,22 @@ describe("Tier LOOP — document execution", () => { expect(output).toContain("TALLY:0,1,2,3"); }); - it("LOOP38: a component in the loop body is imported once per iteration", function* () { - const stream = new InMemoryStream(); - yield* useHostFiles(); - yield* useStubFs({ - "components/Step.md": "step\n", - "test.md": "", - }); - yield* useEchoExec(); + journalCase( + "LOOP38: a component in the loop body is imported once per iteration", + "test.md", + function* (stream) { + yield* useHostFiles(); + yield* useStubFs({ + "components/Step.md": "step\n", + "test.md": "", + }); + yield* useEchoExec(); - const output = asText(yield* collect(yield* execute({ path: "test.md", stream }))); - expect(output.match(/step/g)).toHaveLength(3); - expect(output).not.toContain("ERROR"); - }); + const output = asText(yield* collect(yield* execute({ path: "test.md", stream }))); + expect(output.match(/step/g)).toHaveLength(3); + expect(output).not.toContain("ERROR"); + }, + ); it("LOOP39: a truncated journal replays one iteration and runs the rest live", function* () { const DOC = [ @@ -842,36 +847,39 @@ describe("Tier LOOP — document execution", () => { ]); }); - it("LOOP40: a chosen from a binding stops the document's loop", function* () { - const stream = new InMemoryStream(); - yield* useHostFiles(); - yield* useStubFs({ - "test.md": [ - "```js eval", - "const seen = [];", - "```", - "", - "", - "```js eval", - "seen.push('iteration');", - "```", - "", - "", - "", - "", - "", - "", - "```js eval", - "output(`ITERATIONS:${seen.length}`);", - "```", - ].join("\n"), - }); - yield* useEchoExec(); + journalCase( + "LOOP40: a chosen from a binding stops the document's loop", + "test.md", + function* (stream) { + yield* useHostFiles(); + yield* useStubFs({ + "test.md": [ + "```js eval", + "const seen = [];", + "```", + "", + "", + "```js eval", + "seen.push('iteration');", + "```", + "", + "", + "", + "", + "", + "", + "```js eval", + "output(`ITERATIONS:${seen.length}`);", + "```", + ].join("\n"), + }); + yield* useEchoExec(); - const output = asText(yield* collect(yield* execute({ path: "test.md", stream }))); - expect(output).toContain("ITERATIONS:2"); - expect(output).not.toContain("ERROR"); - }); + const output = asText(yield* collect(yield* execute({ path: "test.md", stream }))); + expect(output).toContain("ITERATIONS:2"); + expect(output).not.toContain("ERROR"); + }, + ); }); /** diff --git a/packages/core/tests/sample-component.test.ts b/packages/core/tests/sample-component.test.ts index 4dddc7f86..29c63eacc 100644 --- a/packages/core/tests/sample-component.test.ts +++ b/packages/core/tests/sample-component.test.ts @@ -23,6 +23,9 @@ import { ensureDir, readTextFile, writeTextFile } from "@effectionx/fs"; import { useTempDirectory } from "@executablemd/test-support/temp"; import type { Operation } from "effection"; import * as path from "node:path"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/sample-component.test.ts"); function* writeFiles(dir: string, files: Record): Operation { for (const [filePath, content] of Object.entries(files)) { @@ -415,8 +418,7 @@ describe("Tier SC — Sample component", () => { describe("Tier EO — eval output() function", () => { beforeAll(() => useTempFileCompiler()); // EO1: output() sets eval block output - it("EO1: output() produces eval block output", function* () { - const stream = new InMemoryStream(); + journalCase("EO1: output() produces eval block output", "test.md", function* (stream) { yield* useStubFs({ "test.md": '```js eval\noutput("hello from eval");\n```\n', }); @@ -462,8 +464,7 @@ describe("Tier EO — eval output() function", () => { }); // EO3: eval block without output() still returns empty - it("EO3: eval block without output() produces no output", function* () { - const stream = new InMemoryStream(); + journalCase("EO3: eval block without output() produces no output", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js eval\nconst x = 42;\n```\nafter-eval", }); @@ -482,8 +483,7 @@ describe("Tier EO — eval output() function", () => { }); // EO4: output() with multiline content - it("EO4: output() with multiline content", function* () { - const stream = new InMemoryStream(); + journalCase("EO4: output() with multiline content", "test.md", function* (stream) { yield* useStubFs({ "test.md": '```js eval\noutput("line1\\nline2\\nline3");\n```\n', }); @@ -500,8 +500,7 @@ describe("Tier EO — eval output() function", () => { }); // EO5: output() converts non-string to string - it("EO5: output() converts non-string to string", function* () { - const stream = new InMemoryStream(); + journalCase("EO5: output() converts non-string to string", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js eval\noutput(12345);\n```\n", }); @@ -521,37 +520,39 @@ describe("Tier EO — eval output() function", () => { describe("Tier RC — renderChildren and render closures", () => { beforeAll(() => useTempFileCompiler()); // RC1: renderChildren() returns empty string for self-closing component - it("RC1: renderChildren returns empty for self-closing component", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/TestComp.md": [ - "---", - "meta:", - " componentName: TestComp", - "---", - "", - "```js eval", - "const result = yield* renderChildren();", - "output('children:[' + result + ']');", - "```", - ].join("\n"), - "test.md": "", - }); - yield* useEchoExec(); - - const output = yield* collect( - yield* execute({ - path: "test.md", - stream, - }), - ); - - expect(output).toContain("children:[]"); - }); + journalCase( + "RC1: renderChildren returns empty for self-closing component", + "test.md", + function* (stream) { + yield* useStubFs({ + "components/TestComp.md": [ + "---", + "meta:", + " componentName: TestComp", + "---", + "", + "```js eval", + "const result = yield* renderChildren();", + "output('children:[' + result + ']');", + "```", + ].join("\n"), + "test.md": "", + }); + yield* useEchoExec(); + + const output = yield* collect( + yield* execute({ + path: "test.md", + stream, + }), + ); + + expect(output).toContain("children:[]"); + }, + ); // RC2: renderChildren() captures children text content - it("RC2: renderChildren captures children text", function* () { - const stream = new InMemoryStream(); + journalCase("RC2: renderChildren captures children text", "test.md", function* (stream) { yield* useStubFs({ "components/TestComp.md": [ "---", @@ -579,8 +580,7 @@ describe("Tier RC — renderChildren and render closures", () => { }); // RC3: render() expands arbitrary markdown string - it("RC3: render() expands arbitrary markdown string", function* () { - const stream = new InMemoryStream(); + journalCase("RC3: render() expands arbitrary markdown string", "test.md", function* (stream) { yield* useStubFs({ "components/TestComp.md": [ "---", @@ -607,99 +607,108 @@ describe("Tier RC — renderChildren and render closures", () => { expect(output).toContain("rendered:[arbitrary **markdown** content]"); }); - it("RC4: renderChildren(override) is visible to children and wins over the caller value", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/TestComp.md": [ - "---", - "meta:", - " componentName: TestComp", - "---", - "", - "```js eval", - "const result = yield* renderChildren({ item: 'injected', shadow: 'override-wins' });", - "output('r:[' + result.trim() + ']');", - "```", - ].join("\n"), - "test.md": [ - "```js eval", - "const shadow = 'caller-value';", - "```", - "", - "text item={item} shadow={shadow}", - "```js eval", - "output('child-eval:' + shadow + '/' + item);", - "```", - "", - ].join("\n"), - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "test.md", stream })); - - expect(output).toContain("text item=injected shadow=override-wins"); - expect(output).toContain("child-eval:override-wins/injected"); - expect(output).not.toContain("caller-value"); - }); - - it("RC5: renderChildren(override) does not leak into the caller env", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/TestComp.md": [ - "---", - "meta:", - " componentName: TestComp", - "---", - "", - "```js eval", - "yield* renderChildren({ item: 'injected' });", - "```", - ].join("\n"), - "test.md": [ - "x={item}", - "```js eval", - "output('caller-after:' + (typeof item === 'undefined' ? 'undefined' : item));", - "```", - ].join("\n"), - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "test.md", stream })); - - expect(output).toContain("caller-after:undefined"); - expect(output).not.toContain("ERROR"); - }); - - it("RC6: renderChildren(override) rejects null, arrays, primitives, and non-plain objects", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/TestComp.md": [ - "---", - "meta:", - " componentName: TestComp", - "---", - "", - "```js eval", - "const bad = [null, [1, 2, 3], 42, 'str', new Date(), new Map()];", - "let caught = 0;", - "for (const value of bad) {", - " try {", - " yield* renderChildren(value);", - " } catch (e) {", - " if (e.message === 'renderChildren(override) requires a plain object.') caught++;", - " }", - "}", - "output('caught:' + caught + '/' + bad.length);", - "```", - ].join("\n"), - "test.md": "body", - }); - yield* useEchoExec(); - - const output = yield* collect(yield* execute({ path: "test.md", stream })); - - expect(output).toContain("caught:6/6"); - }); + journalCase( + "RC4: renderChildren(override) is visible to children and wins over the caller value", + "test.md", + function* (stream) { + yield* useStubFs({ + "components/TestComp.md": [ + "---", + "meta:", + " componentName: TestComp", + "---", + "", + "```js eval", + "const result = yield* renderChildren({ item: 'injected', shadow: 'override-wins' });", + "output('r:[' + result.trim() + ']');", + "```", + ].join("\n"), + "test.md": [ + "```js eval", + "const shadow = 'caller-value';", + "```", + "", + "text item={item} shadow={shadow}", + "```js eval", + "output('child-eval:' + shadow + '/' + item);", + "```", + "", + ].join("\n"), + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "test.md", stream })); + + expect(output).toContain("text item=injected shadow=override-wins"); + expect(output).toContain("child-eval:override-wins/injected"); + expect(output).not.toContain("caller-value"); + }, + ); + + journalCase( + "RC5: renderChildren(override) does not leak into the caller env", + "test.md", + function* (stream) { + yield* useStubFs({ + "components/TestComp.md": [ + "---", + "meta:", + " componentName: TestComp", + "---", + "", + "```js eval", + "yield* renderChildren({ item: 'injected' });", + "```", + ].join("\n"), + "test.md": [ + "x={item}", + "```js eval", + "output('caller-after:' + (typeof item === 'undefined' ? 'undefined' : item));", + "```", + ].join("\n"), + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "test.md", stream })); + + expect(output).toContain("caller-after:undefined"); + expect(output).not.toContain("ERROR"); + }, + ); + + journalCase( + "RC6: renderChildren(override) rejects null, arrays, primitives, and non-plain objects", + "test.md", + function* (stream) { + yield* useStubFs({ + "components/TestComp.md": [ + "---", + "meta:", + " componentName: TestComp", + "---", + "", + "```js eval", + "const bad = [null, [1, 2, 3], 42, 'str', new Date(), new Map()];", + "let caught = 0;", + "for (const value of bad) {", + " try {", + " yield* renderChildren(value);", + " } catch (e) {", + " if (e.message === 'renderChildren(override) requires a plain object.') caught++;", + " }", + "}", + "output('caught:' + caught + '/' + bad.length);", + "```", + ].join("\n"), + "test.md": "body", + }); + yield* useEchoExec(); + + const output = yield* collect(yield* execute({ path: "test.md", stream })); + + expect(output).toContain("caught:6/6"); + }, + ); }); describe("Tier IN — Instruction component", () => { diff --git a/packages/core/tests/switch.test.ts b/packages/core/tests/switch.test.ts index 5a59b6cfc..6ebf803c3 100644 --- a/packages/core/tests/switch.test.ts +++ b/packages/core/tests/switch.test.ts @@ -22,6 +22,9 @@ import type { SourceOrigin } from "../src/scanner.ts"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import type { ComponentElement, FunctionComponentDefinition, Segment } from "../src/types.ts"; import { asText } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/switch.test.ts"); interface SwitchRun { segments: Segment[]; @@ -833,55 +836,59 @@ describe("Tier SWITCH / CASE — provider boundary", () => { describe("Tier SWITCH / CASE — document execution", () => { beforeAll(() => useTempFileCompiler()); - it("SW55: a in the selected case satisfies the value body that owns it", function* () { - yield* useStubFs({ - "Verdict.md": [ - "---", - "returns:", - " type: string", - "---", - "", - '', - '', - '', - "", - "", - ].join("\n"), - "test.md": '\n\nGot {v}\n', - }); - yield* useEchoExec(); + journalCase( + "SW55: a in the selected case satisfies the value body that owns it", + "test.md", + function* (journal) { + yield* useStubFs({ + "Verdict.md": [ + "---", + "returns:", + " type: string", + "---", + "", + '', + '', + '', + "", + "", + ].join("\n"), + "test.md": '\n\nGot {v}\n', + }); + yield* useEchoExec(); - const output = asText( - yield* collect(yield* execute({ path: "test.md", stream: new InMemoryStream() })), - ); - expect(output).toContain("Got picked"); - expect(output).not.toContain("held"); - }); + const output = asText(yield* collect(yield* execute({ path: "test.md", stream: journal }))); + expect(output).toContain("Got picked"); + expect(output).not.toContain("held"); + }, + ); - it("SW56: a projected through reads the caller's bindings", function* () { - yield* useStubFs({ - "components/Wrap.md": "", - "test.md": [ - "```js eval", - "const state = 'waiting';", - "```", - "", - "", - "READY", - "WAITING", - "", - "", - ].join("\n"), - }); - yield* useEchoExec(); + journalCase( + "SW56: a projected through reads the caller's bindings", + "test.md", + function* (journal) { + yield* useStubFs({ + "components/Wrap.md": "", + "test.md": [ + "```js eval", + "const state = 'waiting';", + "```", + "", + "", + "READY", + "WAITING", + "", + "", + ].join("\n"), + }); + yield* useEchoExec(); - const output = asText( - yield* collect(yield* execute({ path: "test.md", stream: new InMemoryStream() })), - ); - expect(output).toContain("WAITING"); - expect(output).not.toContain("READY"); - expect(output).not.toContain("ERROR"); - }); + const output = asText(yield* collect(yield* execute({ path: "test.md", stream: journal }))); + expect(output).toContain("WAITING"); + expect(output).not.toContain("READY"); + expect(output).not.toContain("ERROR"); + }, + ); it("SW57: only the selected case reaches the journal", function* () { const stream = new InMemoryStream(); diff --git a/packages/core/tests/validation-integration.test.ts b/packages/core/tests/validation-integration.test.ts index d37ec507b..4094e4198 100644 --- a/packages/core/tests/validation-integration.test.ts +++ b/packages/core/tests/validation-integration.test.ts @@ -2,7 +2,6 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { scoped } from "effection"; import type { Operation } from "effection"; -import { InMemoryStream } from "@executablemd/durable-streams"; import { useStubFs } from "@executablemd/runtime/test"; import { expandSegments } from "../src/expand.ts"; import { Component } from "../src/component-api.ts"; @@ -13,6 +12,9 @@ import { asText } from "./helpers.ts"; import { parseFrontmatter } from "../src/frontmatter.ts"; import { compilePropsSchema } from "../src/validate.ts"; import type { ComponentDefinition, EvalEnv, Json, Segment } from "../src/types.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/validation-integration.test.ts"); function markdownComponent(name: string, props: Record): ComponentDefinition { return { @@ -101,7 +103,7 @@ describe("prop-validation error segment", () => { // A full `inputs` schema parses — `inputs` lands in meta — so the failure // surfaces later, when a caller passes a prop the component does not declare. describe("`inputs` is not a compatibility alias for `props`", () => { - it("a component declaring `inputs` declares no props", function* () { + journalCase("a component declaring `inputs` declares no props", "README.md", function* (journal) { yield* useStubFs({ "README.md": '\n', "Legacy.md": [ @@ -118,9 +120,7 @@ describe("`inputs` is not a compatibility alias for `props`", () => { }); let message = ""; try { - message = asText( - yield* collect(yield* execute({ path: "README.md", stream: new InMemoryStream() })), - ); + message = asText(yield* collect(yield* execute({ path: "README.md", stream: journal }))); } catch (error) { message = error instanceof Error ? error.message : String(error); } @@ -129,75 +129,81 @@ describe("`inputs` is not a compatibility alias for `props`", () => { }); describe("definition-loading rejects invalid props schemas", () => { - it("rejects an async schema at the Markdown load boundary", function* () { - yield* useStubFs({ - "README.md": "\n", - "Bad.md": [ - "---", - "props:", - " $async: true", - " type: object", - " properties: {}", - " additionalProperties: false", - "---", - "body", - "", - ].join("\n"), - }); - let message = ""; - try { - message = asText( - yield* collect(yield* execute({ path: "README.md", stream: new InMemoryStream() })), - ); - } catch (error) { - message = error instanceof Error ? error.message : String(error); - } - expect(message).toContain("async"); - }); + journalCase( + "rejects an async schema at the Markdown load boundary", + "README.md", + function* (journal) { + yield* useStubFs({ + "README.md": "\n", + "Bad.md": [ + "---", + "props:", + " $async: true", + " type: object", + " properties: {}", + " additionalProperties: false", + "---", + "body", + "", + ].join("\n"), + }); + let message = ""; + try { + message = asText(yield* collect(yield* execute({ path: "README.md", stream: journal }))); + } catch (error) { + message = error instanceof Error ? error.message : String(error); + } + expect(message).toContain("async"); + }, + ); - it("rejects a reserved-name schema at the Markdown load boundary", function* () { - yield* useStubFs({ - "README.md": "\n", - "Bad.md": [ - "---", - "props:", - " type: object", - " properties:", - " slot: { type: string }", - " additionalProperties: false", - "---", - "body", - "", - ].join("\n"), - }); - let message = ""; - try { - message = asText( - yield* collect(yield* execute({ path: "README.md", stream: new InMemoryStream() })), - ); - } catch (error) { - message = error instanceof Error ? error.message : String(error); - } - expect(message).toContain("reserved"); - }); + journalCase( + "rejects a reserved-name schema at the Markdown load boundary", + "README.md", + function* (journal) { + yield* useStubFs({ + "README.md": "\n", + "Bad.md": [ + "---", + "props:", + " type: object", + " properties:", + " slot: { type: string }", + " additionalProperties: false", + "---", + "body", + "", + ].join("\n"), + }); + let message = ""; + try { + message = asText(yield* collect(yield* execute({ path: "README.md", stream: journal }))); + } catch (error) { + message = error instanceof Error ? error.message : String(error); + } + expect(message).toContain("reserved"); + }, + ); - it("rejects a reserved name declared through a props map", function* () { - yield* useStubFs({ - "README.md": "\n", - "Bad.md": ["---", "props:", " slot: { type: string }", "---", "body", ""].join("\n"), - }); - let message = ""; - try { - message = asText( - yield* collect(yield* execute({ path: "README.md", stream: new InMemoryStream() })), - ); - } catch (error) { - message = error instanceof Error ? error.message : String(error); - } - // Normalization runs first, so the contract still sees `slot` under - // `properties`. - expect(message).toContain("reserved"); - }); + journalCase( + "rejects a reserved name declared through a props map", + "README.md", + function* (journal) { + yield* useStubFs({ + "README.md": "\n", + "Bad.md": ["---", "props:", " slot: { type: string }", "---", "body", ""].join("\n"), + }); + let message = ""; + try { + message = asText(yield* collect(yield* execute({ path: "README.md", stream: journal }))); + } catch (error) { + message = error instanceof Error ? error.message : String(error); + } + // Normalization runs first, so the contract still sees `slot` under + // `properties`. + expect(message).toContain("reserved"); + }, + ); }); describe("the root-object contract applies to the normalized schema", () => { diff --git a/packages/test-support/journal-cases.ts b/packages/test-support/journal-cases.ts new file mode 100644 index 000000000..2fa110cfb --- /dev/null +++ b/packages/test-support/journal-cases.ts @@ -0,0 +1,15 @@ +import { it } from "./bdd.ts"; +import { captureTestJournal } from "./failure-journal.ts"; +import type { InMemoryStream } from "@executablemd/durable-streams"; +import type { Operation } from "effection"; + +/** Register a case that owns one fresh guarded document execution. */ +export function journalCases(owner: string) { + return ( + name: string, + source: string, + body: (stream: InMemoryStream) => Operation, + ): void => { + it(name, () => captureTestJournal({ owner, name }, source, body)); + }; +} From 2c56e878e174fbe139663129b3471f12928aea09 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 13:56:34 -0500 Subject: [PATCH 08/78] test: attribute failure journals for live synthetic REPL entries --- packages/cli/tests/repl-execution.test.ts | 427 ++++++++++++---------- 1 file changed, 227 insertions(+), 200 deletions(-) diff --git a/packages/cli/tests/repl-execution.test.ts b/packages/cli/tests/repl-execution.test.ts index 354b79465..9d3ef1335 100644 --- a/packages/cli/tests/repl-execution.test.ts +++ b/packages/cli/tests/repl-execution.test.ts @@ -243,9 +243,10 @@ function captureReferenceEntry( name: string, body: (holder: ReplExecution) => Operation, sink: DeliverySink = process.stderr, + suite = SUBMIT_SUITE, ): Operation { return captureTestJournal( - { owner: OWNER, suite: SUBMIT_SUITE, name }, + { owner: OWNER, suite, name }, REFERENCE_PATH, (stream) => body({ id: "kf39sla2", stream }), { @@ -264,6 +265,12 @@ function captureReferenceEntry( ); } +function referenceCases(suite: string) { + return (name: string, body: (holder: ReplExecution) => Operation): void => { + it(name, () => captureReferenceEntry(name, body, process.stderr, suite)); + }; +} + function admitReferenceEntry( name: string, check?: (holder: ReplExecution) => Operation, @@ -321,6 +328,7 @@ function admitReferenceEntry( describe(SUBMIT_SUITE, () => { beforeAll(() => useTempFileCompiler()); + const referenceCase = referenceCases(SUBMIT_SUITE); const admission = "X1: admits the exact source, binds, generates, asks, and settles"; it(admission, () => admitReferenceEntry(admission)); @@ -467,62 +475,68 @@ describe(SUBMIT_SUITE, () => { expect(lines).toHaveLength(1); }); - it("X1: the generated fragment is shown before it is admitted, and follows the binding", function* () { - const holder = execution(); - const source = yield* referenceSource(); - const session = opened(yield* submitReplEntry({ ...options(holder), source })); - (yield* nextQuestion(session)).submit({ decision: "decline" }); - yield* session.join(); + referenceCase( + "X1: the generated fragment is shown before it is admitted, and follows the binding", + function* (holder) { + const source = yield* referenceSource(); + const session = opened(yield* submitReplEntry({ ...options(holder), source })); + (yield* nextQuestion(session)).submit({ decision: "decline" }); + yield* session.join(); - const generated = session.model.entries[0]?.scope.generated[0]; - const fragment = session.model.entries[0]?.scope.scopes.find( - (scope) => scope.kind === "generated", - ); - expect(generated?.decision).toBe("admitted"); - // The value the durable evaluation published is what the fragment says, - // which is what makes it deterministic rather than merely repeatable. - expect(fragment?.source).toBe(''); - expect(session.model.terminal?.output).toContain("Decision: decline"); - }); + const generated = session.model.entries[0]?.scope.generated[0]; + const fragment = session.model.entries[0]?.scope.scopes.find( + (scope) => scope.kind === "generated", + ); + expect(generated?.decision).toBe("admitted"); + // The value the durable evaluation published is what the fragment says, + // which is what makes it deterministic rather than merely repeatable. + expect(fragment?.source).toBe(''); + expect(session.model.terminal?.output).toContain("Decision: decline"); + }, + ); - it("X1: shows the generated source before admitting it, then admits and evaluates it", function* () { - const holder = execution(); - const source = yield* referenceSource(); - const session = opened(yield* submitReplEntry({ ...options(holder), source })); - const fragment = ''; + referenceCase( + "X1: shows the generated source before admitting it, then admits and evaluates it", + function* (holder) { + const source = yield* referenceSource(); + const session = opened(yield* submitReplEntry({ ...options(holder), source })); + const fragment = ''; - // Stepped rather than inspected at the end: a terminal model shows that - // both things happened and says nothing about which came first. Pausing at - // each boundary is what lets the order itself be observed. - controlling(session).pause(); - let shownBeforeAdmission = false; - let admitted = false; - for (let step = 0; step < 500 && session.live && !admitted; step++) { - yield* pausedOrDone(session); - if (!session.live) { - break; - } - admitted = counted(yield* readAll(holder), "generated_xmd") > 0; - if (!admitted && session.overlay.output.includes(fragment)) { - shownBeforeAdmission = true; - } - controlling(session).resume(); + // Stepped rather than inspected at the end: a terminal model shows that + // both things happened and says nothing about which came first. Pausing at + // each boundary is what lets the order itself be observed. controlling(session).pause(); - } + let shownBeforeAdmission = false; + let admitted = false; + for (let step = 0; step < 500 && session.live && !admitted; step++) { + yield* pausedOrDone(session); + if (!session.live) { + break; + } + admitted = counted(yield* readAll(holder), "generated_xmd") > 0; + if (!admitted && session.overlay.output.includes(fragment)) { + shownBeforeAdmission = true; + } + controlling(session).resume(); + controlling(session).pause(); + } - expect(shownBeforeAdmission).toBe(true); - expect(admitted).toBe(true); + expect(shownBeforeAdmission).toBe(true); + expect(admitted).toBe(true); - controlling(session).resume(); - (yield* nextQuestion(session)).submit({ decision: "approve" }); - yield* session.join(); + controlling(session).resume(); + (yield* nextQuestion(session)).submit({ decision: "approve" }); + yield* session.join(); - // The admitted fragment then ran where it was written: its rendering - // follows the source it was rendered from. - const settled = session.model.terminal?.output ?? ""; - expect(settled.indexOf(fragment)).toBeGreaterThan(-1); - expect(settled.indexOf('"title": "Ship the REPL"')).toBeGreaterThan(settled.indexOf(fragment)); - }); + // The admitted fragment then ran where it was written: its rendering + // follows the source it was rendered from. + const settled = session.model.terminal?.output ?? ""; + expect(settled.indexOf(fragment)).toBeGreaterThan(-1); + expect(settled.indexOf('"title": "Ship the REPL"')).toBeGreaterThan( + settled.indexOf(fragment), + ); + }, + ); it("X1: an entry this environment cannot run leaves the history empty", function* () { const holder = execution(); @@ -537,31 +551,33 @@ describe(SUBMIT_SUITE, () => { expect(yield* holder.stream.readAll()).toEqual([]); }); - it("X1: a choice the form does not offer answers nothing and leaves the question open", function* () { - const holder = execution(); - const source = yield* referenceSource(); - const session = opened(yield* submitReplEntry({ ...options(holder), source })); + referenceCase( + "X1: a choice the form does not offer answers nothing and leaves the question open", + function* (holder) { + const source = yield* referenceSource(); + const session = opened(yield* submitReplEntry({ ...options(holder), source })); - const question = yield* nextQuestion(session); - // Not an offered value, so the schema rejects it: the question stays open and - // nothing is recorded. - expect(question.submit({ decision: "maybe" }).kind).toBe("invalid"); - yield* sleep(10); - - // An incomplete interaction, not a rejected answer. The provider never - // returned, so there is nothing for core to judge and nothing to record. - // The other case — a provider that really hands back a value the schema - // rejects — settles the durable operation `err` with no answer, and E1 - // proves that in `packages/core/tests/elicit-component.test.ts`. This case - // does not prove that one. - expect(session.elicitation.pending).toBe(question); - expect(counted(yield* readAll(holder), "elicit")).toBe(0); - expect(session.model.settled).toBe(false); - - question.submit({ decision: "approve" }); - yield* session.join(); - expect(counted(yield* readAll(holder), "elicit")).toBe(1); - }); + const question = yield* nextQuestion(session); + // Not an offered value, so the schema rejects it: the question stays open and + // nothing is recorded. + expect(question.submit({ decision: "maybe" }).kind).toBe("invalid"); + yield* sleep(10); + + // An incomplete interaction, not a rejected answer. The provider never + // returned, so there is nothing for core to judge and nothing to record. + // The other case — a provider that really hands back a value the schema + // rejects — settles the durable operation `err` with no answer, and E1 + // proves that in `packages/core/tests/elicit-component.test.ts`. This case + // does not prove that one. + expect(session.elicitation.pending).toBe(question); + expect(counted(yield* readAll(holder), "elicit")).toBe(0); + expect(session.model.settled).toBe(false); + + question.submit({ decision: "approve" }); + yield* session.join(); + expect(counted(yield* readAll(holder), "elicit")).toBe(1); + }, + ); it("X1: an entry is refused while the entry before it has not settled", function* () { // The reference history without its root close: an entry that never reached @@ -582,6 +598,7 @@ describe(SUBMIT_SUITE, () => { describe("REPL execution: reopening one history", () => { beforeAll(() => useTempFileCompiler()); + const referenceCase = referenceCases("REPL execution: reopening one history"); it("X2: replays what was recorded and goes live at the first unrecorded step", function* () { const settled = yield* referenceEvents(); @@ -614,26 +631,28 @@ describe("REPL execution: reopening one history", () => { expect(session.model.terminal?.output).toContain("Decision: approve"); }); - it("X2: the same counters do register the work a first run really performs", function* () { - const holder = execution(); - const source = yield* referenceSource(); - const performed = yield* countPerformed(); - const asked = yield* countAsked(); - const session = opened(yield* submitReplEntry({ ...options(holder), source })); + referenceCase( + "X2: the same counters do register the work a first run really performs", + function* (holder) { + const source = yield* referenceSource(); + const performed = yield* countPerformed(); + const asked = yield* countAsked(); + const session = opened(yield* submitReplEntry({ ...options(holder), source })); - (yield* nextQuestion(session)).submit({ decision: "approve" }); - yield* session.join(); + (yield* nextQuestion(session)).submit({ decision: "approve" }); + yield* session.join(); - // The positive control for every count the negatives rely on. Without it, a - // counter that never increments for any reason at all would read as proof - // of replay, or of a provider that was never reached. - expect(performed.reads.filter((path) => path.endsWith("Checklist.md")).length).toBeGreaterThan( - 0, - ); - expect(performed.compiles).toBeGreaterThan(0); - expect(asked.calls).toBe(1); - expect(session.elicitation.asked).toBe(1); - }); + // The positive control for every count the negatives rely on. Without it, a + // counter that never increments for any reason at all would read as proof + // of replay, or of a provider that was never reached. + expect( + performed.reads.filter((path) => path.endsWith("Checklist.md")).length, + ).toBeGreaterThan(0); + expect(performed.compiles).toBeGreaterThan(0); + expect(asked.calls).toBe(1); + expect(session.elicitation.asked).toBe(1); + }, + ); it("X2: a recorded answer is restored without the provider being reached", function* () { const settled = yield* referenceEvents(); @@ -795,79 +814,83 @@ describe("REPL execution: reopening one history", () => { describe("REPL execution: pausing expansion", () => { beforeAll(() => useTempFileCompiler()); + const referenceCase = referenceCases("REPL execution: pausing expansion"); - it("P1: stops at every boundary it crosses and continues past each one", function* () { - const holder = execution(); - const source = yield* referenceSource(); - const session = opened(yield* submitReplEntry({ ...options(holder), source })); + referenceCase( + "P1: stops at every boundary it crosses and continues past each one", + function* (holder) { + const source = yield* referenceSource(); + const session = opened(yield* submitReplEntry({ ...options(holder), source })); - // Held for the length of the test. The session stops *offering* the - // capability once nothing is expanding, which is what the cold control - // below is about; the controller this run owned is still the thing that - // released its holds. - const controller = controlling(session); - controller.pause(); - let stops = 0; - while (session.live && stops < 500) { - yield* pausedOrDone(session); - if (!session.live) { - break; + // Held for the length of the test. The session stops *offering* the + // capability once nothing is expanding, which is what the cold control + // below is about; the controller this run owned is still the thing that + // released its holds. + const controller = controlling(session); + controller.pause(); + let stops = 0; + while (session.live && stops < 500) { + yield* pausedOrDone(session); + if (!session.live) { + break; + } + expect(session.expansion.state).toBe("paused"); + stops++; + controller.resume(); + // Re-armed in the same turn as the release, so the continuation this + // released stops at the next boundary rather than running to the end. + controller.pause(); } - expect(session.expansion.state).toBe("paused"); - stops++; controller.resume(); - // Re-armed in the same turn as the release, so the continuation this - // released stops at the next boundary rather than running to the end. - controller.pause(); - } - controller.resume(); - yield* session.join(); + yield* session.join(); - expect(stops).toBeGreaterThan(5); - expect(controller.released).toBe(stops); - expect(session.model.settled).toBe(true); - expect(session.model.terminal?.output).toContain("Decision: approve"); - }); + expect(stops).toBeGreaterThan(5); + expect(controller.released).toBe(stops); + expect(session.model.settled).toBe(true); + expect(session.model.terminal?.output).toContain("Decision: approve"); + }, + ); - it("P1: the Journal advances after pause is requested and before it takes effect", function* () { - const holder = execution(); - const source = yield* referenceSource(); - const session = opened(yield* submitReplEntry({ ...options(holder), source })); - const controller = controlling(session); + referenceCase( + "P1: the Journal advances after pause is requested and before it takes effect", + function* (holder) { + const source = yield* referenceSource(); + const session = opened(yield* submitReplEntry({ ...options(holder), source })); + const controller = controlling(session); - // A question is work that has already started: the walk is suspended - // inside the provider, not held by the controller, so requesting a pause - // here cannot take effect until that operation finishes. - const question = yield* nextQuestion(session); - const before = (yield* readAll(holder)).length; + // A question is work that has already started: the walk is suspended + // inside the provider, not held by the controller, so requesting a pause + // here cannot take effect until that operation finishes. + const question = yield* nextQuestion(session); + const before = (yield* readAll(holder)).length; - controller.pause(); - expect(session.expansion.state).toBe("pausing"); + controller.pause(); + expect(session.expansion.state).toBe("pausing"); - // Answering lets the already-started operation settle. Its record reaches - // the Journal while the pause request is outstanding, which is the whole - // point: the expansion position and the Journal head are two positions. - question.submit({ decision: "approve" }); - yield* pausedOrDone(session); + // Answering lets the already-started operation settle. Its record reaches + // the Journal while the pause request is outstanding, which is the whole + // point: the expansion position and the Journal head are two positions. + question.submit({ decision: "approve" }); + yield* pausedOrDone(session); - const atPause = (yield* readAll(holder)).length; - expect(session.expansion.state).toBe("paused"); - expect(atPause).toBeGreaterThan(before); + const atPause = (yield* readAll(holder)).length; + expect(session.expansion.state).toBe("paused"); + expect(atPause).toBeGreaterThan(before); - // And once every walk is satisfied it goes no farther on its own. - yield* sleep(25); - expect((yield* readAll(holder)).length).toBe(atPause); - expect(session.expansion.state).toBe("paused"); + // And once every walk is satisfied it goes no farther on its own. + yield* sleep(25); + expect((yield* readAll(holder)).length).toBe(atPause); + expect(session.expansion.state).toBe("paused"); - // Only Continue moves it, and then it finishes. - controller.resume(); - yield* session.join(); - expect(session.model.settled).toBe(true); - expect((yield* readAll(holder)).length).toBeGreaterThan(atPause); - }); + // Only Continue moves it, and then it finishes. + controller.resume(); + yield* session.join(); + expect(session.model.settled).toBe(true); + expect((yield* readAll(holder)).length).toBeGreaterThan(atPause); + }, + ); - it("P1: continuing twice releases nothing the second time", function* () { - const holder = execution(); + referenceCase("P1: continuing twice releases nothing the second time", function* (holder) { const source = yield* referenceSource(); const session = opened(yield* submitReplEntry({ ...options(holder), source })); @@ -885,28 +908,29 @@ describe("REPL execution: pausing expansion", () => { yield* session.join(); }); - it("P1: a paused expansion is stopped, not cancelled, and the run is still there", function* () { - const holder = execution(); - const source = yield* referenceSource(); - const session = opened(yield* submitReplEntry({ ...options(holder), source })); + referenceCase( + "P1: a paused expansion is stopped, not cancelled, and the run is still there", + function* (holder) { + const source = yield* referenceSource(); + const session = opened(yield* submitReplEntry({ ...options(holder), source })); - controlling(session).pause(); - yield* pausedOrDone(session); - const frozen = (yield* readAll(holder)).length; - yield* sleep(25); + controlling(session).pause(); + yield* pausedOrDone(session); + const frozen = (yield* readAll(holder)).length; + yield* sleep(25); - expect(session.expansion.state).toBe("paused"); - expect(session.live).toBe(true); - expect((yield* readAll(holder)).length).toBe(frozen); + expect(session.expansion.state).toBe("paused"); + expect(session.live).toBe(true); + expect((yield* readAll(holder)).length).toBe(frozen); - controlling(session).resume(); - (yield* nextQuestion(session)).submit({ decision: "approve" }); - yield* session.join(); - expect(session.model.settled).toBe(true); - }); + controlling(session).resume(); + (yield* nextQuestion(session)).submit({ decision: "approve" }); + yield* session.join(); + expect(session.model.settled).toBe(true); + }, + ); - it("P1: tearing the owner down releases nothing that was held", function* () { - const holder = execution(); + referenceCase("P1: tearing the owner down releases nothing that was held", function* (holder) { const source = yield* referenceSource(); let held = -1; @@ -951,6 +975,7 @@ describe("REPL execution: pausing expansion", () => { describe("REPL execution: the boundary inventory", () => { beforeAll(() => useTempFileCompiler()); + const referenceCase = referenceCases("REPL execution: the boundary inventory"); it("P1: every member of every wrapped Api is a walk, a gate, or declared not to be one", function* () { const partitioned = (partition: BoundaryPartition): string[] => @@ -961,36 +986,38 @@ describe("REPL execution: the boundary inventory", () => { expect(partitioned(OUTPUT_BOUNDARIES)).toEqual(Object.keys(DocumentOutput.operations).sort()); }); - it("P1: the reference entry crosses the boundaries this controller accounts for", function* () { - const holder = execution(); - const source = yield* referenceSource(); - const session = opened(yield* submitReplEntry({ ...options(holder), source })); - // The controller, not a snapshot of its crossings: `crossings` answers - // with what has been crossed *so far*, and so far is nothing yet. - const controller = controlling(session); - (yield* nextQuestion(session)).submit({ decision: "approve" }); - yield* session.join(); - const crossings = controller.crossings; - - const controlled = [ - ...COMPONENT_BOUNDARIES.walks, - ...COMPONENT_BOUNDARIES.gates, - ...EXECUTION_BOUNDARIES.walks, - ...OUTPUT_BOUNDARIES.gates, - HOST_WALK, - ]; - const crossed = [...crossings.keys()].sort(); - for (const boundary of crossed) { - expect(controlled).toContain(boundary); - } - // The ones this document is written to reach. A boundary disappearing - // from it is what this list is here to notice. - expect(crossed).toContain("document"); - expect(crossed).toContain("importComponent"); - expect(crossed).toContain("applyModifiers"); - expect(crossed).toContain("output"); - expect(crossings.get("document")).toBe(1); - }); + referenceCase( + "P1: the reference entry crosses the boundaries this controller accounts for", + function* (holder) { + const source = yield* referenceSource(); + const session = opened(yield* submitReplEntry({ ...options(holder), source })); + // The controller, not a snapshot of its crossings: `crossings` answers + // with what has been crossed *so far*, and so far is nothing yet. + const controller = controlling(session); + (yield* nextQuestion(session)).submit({ decision: "approve" }); + yield* session.join(); + const crossings = controller.crossings; + + const controlled = [ + ...COMPONENT_BOUNDARIES.walks, + ...COMPONENT_BOUNDARIES.gates, + ...EXECUTION_BOUNDARIES.walks, + ...OUTPUT_BOUNDARIES.gates, + HOST_WALK, + ]; + const crossed = [...crossings.keys()].sort(); + for (const boundary of crossed) { + expect(controlled).toContain(boundary); + } + // The ones this document is written to reach. A boundary disappearing + // from it is what this list is here to notice. + expect(crossed).toContain("document"); + expect(crossed).toContain("importComponent"); + expect(crossed).toContain("applyModifiers"); + expect(crossed).toContain("output"); + expect(crossings.get("document")).toBe(1); + }, + ); }); describe("REPL execution: one execution's file", () => { From a633714e475d309bbe7e3b0f92e2abe269f2646e Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 13:59:19 -0500 Subject: [PATCH 09/78] test: attribute guarded ACP and TestAgent execution journals --- packages/acp/tests/acceptance.test.ts | 362 +++++++++--------- .../test-agent/tests/command-lazy.test.ts | 169 ++++---- 2 files changed, 264 insertions(+), 267 deletions(-) diff --git a/packages/acp/tests/acceptance.test.ts b/packages/acp/tests/acceptance.test.ts index 2350ed8b6..548d51f38 100644 --- a/packages/acp/tests/acceptance.test.ts +++ b/packages/acp/tests/acceptance.test.ts @@ -14,10 +14,11 @@ import { Agent } from "@executablemd/agent/api"; import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import { executeInstalled } from "@executablemd/core/host"; import type { AgentSessionRequest } from "@executablemd/agent/api"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { createAcpxProvider } from "../mod.ts"; import { createFakeRuntime, makeRegistry, makeStore, useFlatWorld } from "./helpers.ts"; +const OWNER = "packages/acp/tests/acceptance.test.ts"; const CWD = "/work"; const DOC = [ '', @@ -29,7 +30,8 @@ const DOC = [ ].join("\n"); describe("Tier XA — ACPX provider through the rootProvider seam", () => { - it("XA1: agent availability → session → normalized prompt → structured teardown", function* () { + const lifecycle = "XA1: agent availability → session → normalized prompt → structured teardown"; + it(lifecycle, function* () { const harness = createFakeRuntime(); const dir = path.join(os.tmpdir(), `xmd-acp-accept-${randomUUID()}`); yield* ensureDir(dir); @@ -38,45 +40,47 @@ describe("Tier XA — ACPX provider through the rootProvider seam", () => { const docPath = path.join(dir, "doc.md"); yield* writeTextFile(docPath, DOC); - const result = yield* scoped(function* () { - yield* useFlatWorld(CWD); - yield* installAgentComponents({ - rootProvider: { - factory: createAcpxProvider({ - createRuntime: harness.create, - sessionStore: makeStore(), - agentRegistry: makeRegistry({ gemini: "gemini-cmd" }), - }), - options: { defaultAgent: "gemini", permissionMode: "deny-all" }, - }, + yield* captureTestJournal({ owner: OWNER, name: lifecycle }, docPath, function* (stream) { + const result = yield* scoped(function* () { + yield* useFlatWorld(CWD); + yield* installAgentComponents({ + rootProvider: { + factory: createAcpxProvider({ + createRuntime: harness.create, + sessionStore: makeStore(), + agentRegistry: makeRegistry({ gemini: "gemini-cmd" }), + }), + options: { defaultAgent: "gemini", permissionMode: "deny-all" }, + }, + }); + + // `` names durable work after its own invocation, so the host + // declares it to the execution rather than registering it. + const execution = yield* executeInstalled({ path: docPath, stream }, [ + { components: agentIdentityComponents() }, + ]); + const subscription = yield* execution.output; + let next = yield* subscription.next(); + while (!next.done) { + next = yield* subscription.next(); + } + const output = next.value; + const outcome = yield* execution; + // Structured teardown: the handle is closed by the time the + // DocumentExecution completion settles (bridgeRootProvider resolves + // completion only after provider finalizers run). + const closedByCompletion = harness.closeCalls.length; + return { output, outcome, closedByCompletion }; }); - // `` names durable work after its own invocation, so the host - // declares it to the execution rather than registering it. - const execution = yield* executeInstalled({ path: docPath, stream: new InMemoryStream() }, [ - { components: agentIdentityComponents() }, - ]); - const subscription = yield* execution.output; - let next = yield* subscription.next(); - while (!next.done) { - next = yield* subscription.next(); - } - const output = next.value; - const outcome = yield* execution; - // Structured teardown: the handle is closed by the time the - // DocumentExecution completion settles (bridgeRootProvider resolves - // completion only after provider finalizers run). - const closedByCompletion = harness.closeCalls.length; - return { output, outcome, closedByCompletion }; + expect(harness.doctorCalls).toBeGreaterThan(0); + expect(harness.ensureCalls.length).toBeGreaterThan(0); + // Normalized prompt output — output-stream deltas only (thought hidden). + expect(result.output).toContain("hello world"); + expect(result.outcome.ok).toBe(true); + // Handle closed before completion settled. + expect(result.closedByCompletion).toBeGreaterThan(0); }); - - expect(harness.doctorCalls).toBeGreaterThan(0); - expect(harness.ensureCalls.length).toBeGreaterThan(0); - // Normalized prompt output — output-stream deltas only (thought hidden). - expect(result.output).toContain("hello world"); - expect(result.outcome.ok).toBe(true); - // Handle closed before completion settled. - expect(result.closedByCompletion).toBeGreaterThan(0); }); }); @@ -89,7 +93,9 @@ describe("Tier XA — ACPX provider through the rootProvider seam", () => { * through the coordinator delivered to this provider. */ describe("Tier WAP — same-named sibling Sessions", () => { - it('WAP7: two sibling sites name two identities the middleware cannot touch', function* () { + const siblings = + 'WAP7: two sibling sites name two identities the middleware cannot touch'; + it(siblings, function* () { const harness = createFakeRuntime(); const requests: Array<{ session: string | undefined; sessionIdentity?: string }> = []; /** The session keys this host was asked to retain, in order. */ @@ -115,86 +121,90 @@ describe("Tier WAP — same-named sibling Sessions", () => { ].join("\n"), ); - yield* scoped(function* () { - yield* useFlatWorld(CWD); - yield* installAgentComponents({ - rootProvider: { - factory: createAcpxProvider({ - createRuntime: harness.create, - sessionStore: makeStore(), - agentRegistry: makeRegistry({ gemini: "gemini-cmd" }), - sessions: { - // deno-lint-ignore require-yield - *requestSession(request) { - requests.push({ - session: request.session, - ...(request.sessionIdentity === undefined - ? {} - : { sessionIdentity: request.sessionIdentity }), - }); - return { - sessionKey: `session:${request.sessionIdentity ?? "none"}`, - cwd: "/sessions", - state: "new", - }; - }, - // A host that decides where sessions live retains what stands - // there. This one keeps the keys it was asked to retain, in - // order, which is how the test sees that each request became its - // own confirmed session rather than one shared by the name. - // deno-lint-ignore require-yield - *recordSessionIdentity(details) { - recorded.push(details.sessionKey); + yield* captureTestJournal({ owner: OWNER, name: siblings }, docPath, function* (stream) { + yield* scoped(function* () { + yield* useFlatWorld(CWD); + yield* installAgentComponents({ + rootProvider: { + factory: createAcpxProvider({ + createRuntime: harness.create, + sessionStore: makeStore(), + agentRegistry: makeRegistry({ gemini: "gemini-cmd" }), + sessions: { + // deno-lint-ignore require-yield + *requestSession(request) { + requests.push({ + session: request.session, + ...(request.sessionIdentity === undefined + ? {} + : { sessionIdentity: request.sessionIdentity }), + }); + return { + sessionKey: `session:${request.sessionIdentity ?? "none"}`, + cwd: "/sessions", + state: "new", + }; + }, + // A host that decides where sessions live retains what stands + // there. This one keeps the keys it was asked to retain, in + // order, which is how the test sees that each request became its + // own confirmed session rather than one shared by the name. + // deno-lint-ignore require-yield + *recordSessionIdentity(details) { + recorded.push(details.sessionKey); + }, }, - }, - }), - options: { defaultAgent: "gemini", permissionMode: "deny-all" }, - }, - }); - // Middleware that rewrites the descriptive name on its way through, which - // is exactly what the public chain is for. - yield* Agent.around({ - *session([routed], next) { - const renamed = - typeof routed === "string" || routed === undefined - ? "rewritten" - : routed.with({ name: "rewritten" }); - return yield* next(renamed); - }, + }), + options: { defaultAgent: "gemini", permissionMode: "deny-all" }, + }, + }); + // Middleware that rewrites the descriptive name on its way through, which + // is exactly what the public chain is for. + yield* Agent.around({ + *session([routed], next) { + const renamed = + typeof routed === "string" || routed === undefined + ? "rewritten" + : routed.with({ name: "rewritten" }); + return yield* next(renamed); + }, + }); + + // `` names durable work after its own invocation, so the host + // declares it to the execution rather than registering it. + const execution = yield* executeInstalled({ path: docPath, stream }, [ + { components: agentIdentityComponents() }, + ]); + const subscription = yield* execution.output; + let next = yield* subscription.next(); + while (!next.done) { + next = yield* subscription.next(); + } + yield* execution; }); - // `` names durable work after its own invocation, so the host - // declares it to the execution rather than registering it. - const execution = yield* executeInstalled({ path: docPath, stream: new InMemoryStream() }, [ - { components: agentIdentityComponents() }, - ]); - const subscription = yield* execution.output; - let next = yield* subscription.next(); - while (!next.done) { - next = yield* subscription.next(); - } - yield* execution; + expect(requests).toHaveLength(2); + // The middleware's rewrite reached the provider, because the name is the + // compositional half. + expect(requests.map((request) => request.session)).toEqual(["rewritten", "rewritten"]); + // The identities did not, and are two: same authored name, two elements, + // two sessions. + const identities = requests.map((request) => request.sessionIdentity); + expect(identities.every((identity) => typeof identity === "string")).toBe(true); + expect(new Set(identities).size).toBe(2); + expect(identities).not.toContain("rewritten"); + // And each request is its own session, not one shared by the name. + expect(new Set(harness.ensureCalls.map((call) => call.sessionKey)).size).toBe(2); + // The host was asked to retain both, in the order they were confirmed. A + // provider that skipped a host with nothing to skip would show up here as + // an empty list. + expect(recorded).toEqual(requests.map((request) => `session:${request.sessionIdentity}`)); }); - - expect(requests).toHaveLength(2); - // The middleware's rewrite reached the provider, because the name is the - // compositional half. - expect(requests.map((request) => request.session)).toEqual(["rewritten", "rewritten"]); - // The identities did not, and are two: same authored name, two elements, - // two sessions. - const identities = requests.map((request) => request.sessionIdentity); - expect(identities.every((identity) => typeof identity === "string")).toBe(true); - expect(new Set(identities).size).toBe(2); - expect(identities).not.toContain("rewritten"); - // And each request is its own session, not one shared by the name. - expect(new Set(harness.ensureCalls.map((call) => call.sessionKey)).size).toBe(2); - // The host was asked to retain both, in the order they were confirmed. A - // provider that skipped a host with nothing to skip would show up here as - // an empty list. - expect(recorded).toEqual(requests.map((request) => `session:${request.sessionIdentity}`)); }); - it("WAP7: a request kept from the first Session cannot be routed for the second", function* () { + const retainedRequest = + "WAP7: a request kept from the first Session cannot be routed for the second"; + it(retainedRequest, function* () { const harness = createFakeRuntime(); const requests: Array = []; /** The session keys this host was asked to retain, in order. */ @@ -221,72 +231,74 @@ describe("Tier WAP — same-named sibling Sessions", () => { ].join("\n"), ); - yield* scoped(function* () { - yield* useFlatWorld(CWD); - yield* installAgentComponents({ - rootProvider: { - factory: createAcpxProvider({ - createRuntime: harness.create, - sessionStore: makeStore(), - agentRegistry: makeRegistry({ gemini: "gemini-cmd" }), - sessions: { - // deno-lint-ignore require-yield - *requestSession(request) { - requests.push(request.sessionIdentity); - return { - sessionKey: `session:${request.sessionIdentity ?? "none"}`, - cwd: "/sessions", - state: "new", - }; - }, - // deno-lint-ignore require-yield - *recordSessionIdentity(details) { - recorded.push(details.sessionKey); + yield* captureTestJournal({ owner: OWNER, name: retainedRequest }, docPath, function* (stream) { + yield* scoped(function* () { + yield* useFlatWorld(CWD); + yield* installAgentComponents({ + rootProvider: { + factory: createAcpxProvider({ + createRuntime: harness.create, + sessionStore: makeStore(), + agentRegistry: makeRegistry({ gemini: "gemini-cmd" }), + sessions: { + // deno-lint-ignore require-yield + *requestSession(request) { + requests.push(request.sessionIdentity); + return { + sessionKey: `session:${request.sessionIdentity ?? "none"}`, + cwd: "/sessions", + state: "new", + }; + }, + // deno-lint-ignore require-yield + *recordSessionIdentity(details) { + recorded.push(details.sessionKey); + }, }, - }, - }), - options: { defaultAgent: "gemini", permissionMode: "deny-all" }, - }, - }); + }), + options: { defaultAgent: "gemini", permissionMode: "deny-all" }, + }, + }); - // The attack: keep the first element's real request and route it for - // the second. Reading it again would answer with the first element's - // identity, and both sessions would collapse into one. - let kept: string | AgentSessionRequest | undefined; - let keeping = false; - yield* Agent.around({ - *session([routed], next) { - if (!keeping) { - keeping = true; - kept = routed; - return yield* next(routed); - } - return yield* next(kept); - }, + // The attack: keep the first element's real request and route it for + // the second. Reading it again would answer with the first element's + // identity, and both sessions would collapse into one. + let kept: string | AgentSessionRequest | undefined; + let keeping = false; + yield* Agent.around({ + *session([routed], next) { + if (!keeping) { + keeping = true; + kept = routed; + return yield* next(routed); + } + return yield* next(kept); + }, + }); + + // `` names durable work after its own invocation, so the host + // declares it to the execution rather than registering it. + const execution = yield* executeInstalled({ path: docPath, stream }, [ + { components: agentIdentityComponents() }, + ]); + const subscription = yield* execution.output; + let next = yield* subscription.next(); + while (!next.done) { + next = yield* subscription.next(); + } + const outcome = yield* execution; + if (!outcome.ok) { + refusal = outcome.error.message; + } }); - // `` names durable work after its own invocation, so the host - // declares it to the execution rather than registering it. - const execution = yield* executeInstalled({ path: docPath, stream: new InMemoryStream() }, [ - { components: agentIdentityComponents() }, - ]); - const subscription = yield* execution.output; - let next = yield* subscription.next(); - while (!next.done) { - next = yield* subscription.next(); - } - const outcome = yield* execution; - if (!outcome.ok) { - refusal = outcome.error.message; - } + // Refused before the provider named anything for the second element: the + // issuance the first one opened closed when that element finished. + expect(refusal).toContain("already resolved its session"); + expect(requests).toHaveLength(1); + // One session was confirmed, so one identity was retained — the refused + // element contributed no mapping of its own. + expect(recorded).toEqual([`session:${requests[0]}`]); }); - - // Refused before the provider named anything for the second element: the - // issuance the first one opened closed when that element finished. - expect(refusal).toContain("already resolved its session"); - expect(requests).toHaveLength(1); - // One session was confirmed, so one identity was retained — the refused - // element contributed no mapping of its own. - expect(recorded).toEqual([`session:${requests[0]}`]); }); }); diff --git a/packages/test-agent/tests/command-lazy.test.ts b/packages/test-agent/tests/command-lazy.test.ts index e0189b6cf..42c2197e7 100644 --- a/packages/test-agent/tests/command-lazy.test.ts +++ b/packages/test-agent/tests/command-lazy.test.ts @@ -16,7 +16,7 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { API } from "@executablemd/runtime"; import { execute, useTempFileCompiler } from "@executablemd/core"; import { installAgentComponents } from "@executablemd/agent/host"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { useTesting } from "@executablemd/testing"; import type { TestResult } from "@executablemd/testing"; import { installTestAgentComponents } from "../src/components.ts"; @@ -44,109 +44,94 @@ function* refuseCommand(): Operation { }); } -function* runDoc( +const OWNER = "packages/test-agent/tests/command-lazy.test.ts"; +const SUITE = "Tier XL — lazy command resolution"; + +function* checkDocument( + name: string, doc: string, install: () => Operation, -): Operation<{ output: string; results: readonly TestResult[] }> { + check: (run: { output: string; results: readonly TestResult[] }) => void, + scenario = false, +): Operation { const dir = path.join(os.tmpdir(), `xmd-xl-${randomUUID()}`); - yield* ensureDir(dir); - return yield* scoped(function* () { - yield* ensure(() => rm(dir, { recursive: true, force: true })); - yield* writeTextFile(path.join(dir, "doc.md"), doc); - - return yield* scoped(function* () { - const testing = yield* useTesting(); - yield* install(); - yield* installTestAgentComponents(); - yield* installAgentComponents(); - const execution = yield* execute({ - path: path.join(dir, "doc.md"), - stream: new InMemoryStream(), - }); - const subscription = yield* execution.output; - let next = yield* subscription.next(); - while (!next.done) { - next = yield* subscription.next(); + const docPath = path.join(dir, "doc.md"); + yield* captureTestJournal({ owner: OWNER, suite: SUITE, name }, docPath, function* (stream) { + const result = yield* scoped(function* () { + yield* ensureDir(dir); + yield* ensure(() => rm(dir, { recursive: true, force: true })); + yield* writeTextFile(docPath, doc); + if (scenario) { + yield* writeTextFile( + path.join(dir, "agent.md"), + '\n\nhello there\n', + ); } - return { output: next.value, results: yield* testing.results }; + return yield* scoped(function* () { + const testing = yield* useTesting(); + yield* install(); + yield* installTestAgentComponents(); + yield* installAgentComponents(); + const execution = yield* execute({ path: docPath, stream }); + const subscription = yield* execution.output; + let next = yield* subscription.next(); + while (!next.done) { + next = yield* subscription.next(); + } + if (scenario) { + yield* execution; + } + return { output: next.value, results: yield* testing.results }; + }); }); + check(result); }); } -describe( - "Tier XL — lazy command resolution", - { sanitizeOps: false, sanitizeResources: false }, - () => { - beforeAll(() => useTempFileCompiler()); +describe(SUITE, { sanitizeOps: false, sanitizeResources: false }, () => { + beforeAll(() => useTempFileCompiler()); - it("XL1: installing the test-agent components does not ask for the command", function* () { - yield* refuseCommand(); - yield* installTestAgentComponents(); - }); + it("XL1: installing the test-agent components does not ask for the command", function* () { + yield* refuseCommand(); + yield* installTestAgentComponents(); + }); - it("XL2: `xmd test` on a document without runs where command throws", function* () { - const { output } = yield* runDoc("# plain\n\nno agents here\n", refuseCommand); + const withoutAgent = + "XL2: `xmd test` on a document without runs where command throws"; + it(withoutAgent, () => + checkDocument(withoutAgent, "# plain\n\nno agents here\n", refuseCommand, ({ output }) => { expect(output).toContain("no agents here"); expect(output).not.toContain("ERROR"); - }); + }), + ); - it("XL3: a document using asks for command(['test-agent'])", function* () { - const asked: Asked = { calls: [] }; - const doc = [ - "", - ' ', - ' ', - ' ', - " ", - "", - "", - ].join("\n"); - const { results } = yield* runDocWithScenario(doc, asked); - expect(results.map(({ status, error }) => ({ status, error }))).toEqual([ - { status: "pass", error: undefined }, - ]); - // One provider per isolation boundary — the scope and each - // lease — so the count tracks boundaries, not documents. What - // matters is that every request is for the worker subcommand and nothing - // else, and that each one appends it exactly once. - expect(asked.calls.length).toBeGreaterThan(0); - for (const args of asked.calls) { - expect(args).toEqual(["test-agent"]); - } - }); - }, -); - -function* runDocWithScenario( - doc: string, - asked: Asked, -): Operation<{ results: readonly TestResult[] }> { - const dir = path.join(os.tmpdir(), `xmd-xl-${randomUUID()}`); - yield* ensureDir(dir); - return yield* scoped(function* () { - yield* ensure(() => rm(dir, { recursive: true, force: true })); - yield* writeTextFile(path.join(dir, "doc.md"), doc); - yield* writeTextFile( - path.join(dir, "agent.md"), - '\n\nhello there\n', + const withAgent = "XL3: a document using asks for command(['test-agent'])"; + it(withAgent, function* () { + const asked: Asked = { calls: [] }; + const doc = [ + "", + ' ', + ' ', + ' ', + " ", + "", + "", + ].join("\n"); + yield* checkDocument( + withAgent, + doc, + () => recordCommand(asked), + ({ results }) => { + expect(results.map(({ status, error }) => ({ status, error }))).toEqual([ + { status: "pass", error: undefined }, + ]); + // Each isolation boundary requests the worker subcommand once. + expect(asked.calls.length).toBeGreaterThan(0); + for (const args of asked.calls) { + expect(args).toEqual(["test-agent"]); + } + }, + true, ); - - return yield* scoped(function* () { - const testing = yield* useTesting(); - yield* recordCommand(asked); - yield* installTestAgentComponents(); - yield* installAgentComponents(); - const execution = yield* execute({ - path: path.join(dir, "doc.md"), - stream: new InMemoryStream(), - }); - const subscription = yield* execution.output; - let next = yield* subscription.next(); - while (!next.done) { - next = yield* subscription.next(); - } - yield* execution; - return { results: yield* testing.results }; - }); }); -} +}); From 1be6fa0295fb35433ee9bd408d2e2a57187ca0cb Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:01:20 -0500 Subject: [PATCH 10/78] test: attribute safe Agent and nested Testing execution journals --- packages/agent/tests/agent-components.test.ts | 285 ++++++++++-------- .../testing/tests/execution-harness.test.ts | 68 +++-- 2 files changed, 196 insertions(+), 157 deletions(-) diff --git a/packages/agent/tests/agent-components.test.ts b/packages/agent/tests/agent-components.test.ts index b6a6eb06c..292ad70f8 100644 --- a/packages/agent/tests/agent-components.test.ts +++ b/packages/agent/tests/agent-components.test.ts @@ -28,6 +28,7 @@ import type { AgentProviderFactory } from "../src/provider-api.ts"; import { installAgentComponents } from "../src/components.ts"; import { Component } from "../../core/src/component-api.ts"; import type { Json } from "@executablemd/core"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; interface StubResponse { status?: "completed" | "failed" | "cancelled"; @@ -147,8 +148,8 @@ function* installStub(stub: Stub): Operation { function* runDoc( doc: string, stream: InMemoryStream, + dir = path.join(os.tmpdir(), `xmd-ac-test-${randomUUID()}`), ): Operation<{ output: string; result: Result }> { - const dir = path.join(os.tmpdir(), `xmd-ac-test-${randomUUID()}`); yield* ensureDir(dir); return yield* scoped(function* () { yield* ensure(() => rm(dir, { recursive: true, force: true })); @@ -170,36 +171,54 @@ function* runDoc( }); } -describe("Tier AC — agent components", () => { - it("AC1: wrapper always sends rendered children, untrimmed", function* () { - const stub = createStubProvider(); - yield* installStub(stub); - const { output, result } = yield* runDoc( - '\nSay hello\n\n', - new InMemoryStream(), +const SUITE = "Tier AC — agent components"; + +function agentCase( + name: string, + body: (run: (doc: string) => ReturnType) => Operation, +): void { + it(name, () => { + const dir = path.join(os.tmpdir(), `xmd-ac-test-${randomUUID()}`); + return captureTestJournal( + { owner: "packages/agent/tests/agent-components.test.ts", suite: SUITE, name }, + path.join(dir, "doc.md"), + (stream) => body((doc) => runDoc(doc, stream, dir)), ); - expect(result.ok).toBe(true); - expect(stub.promptCalls.length).toBe(1); - const sent = stub.promptCalls[0]!.content; - expect(sent).toContain("Say hello"); - expect(sent).not.toBe("fallback"); - expect(sent).not.toBe(sent.trim()); - expect(output).toContain("[stub-agent:stub:default:"); }); +} + +describe(SUITE, () => { + agentCase( + "AC1: wrapper always sends rendered children, untrimmed", + function* (runFresh) { + const stub = createStubProvider(); + yield* installStub(stub); + const { output, result } = yield* runFresh( + '\nSay hello\n\n', + ); + expect(result.ok).toBe(true); + expect(stub.promptCalls.length).toBe(1); + const sent = stub.promptCalls[0]!.content; + expect(sent).toContain("Say hello"); + expect(sent).not.toBe("fallback"); + expect(sent).not.toBe(sent.trim()); + expect(output).toContain("[stub-agent:stub:default:"); + }, + ); - it("AC2: empty wrapper children win over the text prop", function* () { + agentCase("AC2: empty wrapper children win over the text prop", function* (runFresh) { const stub = createStubProvider(); yield* installStub(stub); - const { result } = yield* runDoc('\n', new InMemoryStream()); + const { result } = yield* runFresh('\n'); expect(result.ok).toBe(true); expect(stub.promptCalls.length).toBe(1); expect(stub.promptCalls[0]!.content).toBe(""); }); - it("AC3: self-closing falls back to the text prop", function* () { + agentCase("AC3: self-closing falls back to the text prop", function* (runFresh) { const stub = createStubProvider(); yield* installStub(stub); - const { output, result } = yield* runDoc('\n', new InMemoryStream()); + const { output, result } = yield* runFresh('\n'); expect(result.ok).toBe(true); expect(stub.promptCalls[0]!.content).toBe("hello"); expect(output).toContain("[stub-agent:stub:default:hello]"); @@ -209,10 +228,10 @@ describe("Tier AC — agent components", () => { // function component: it names the component and lists the offending prop, // where the claimed handler built the same account behind a ` ` // prefix of its own. - it("AC19: the removed prompt prop is rejected as an unknown prop", function* () { + agentCase("AC19: the removed prompt prop is rejected as an unknown prop", function* (runFresh) { const stub = createStubProvider(); yield* installStub(stub); - const { result } = yield* runDoc('\n', new InMemoryStream()); + const { result } = yield* runFresh('\n'); expect(result.ok).toBe(false); expect(stub.promptCalls.length).toBe(0); const reported = result.ok ? "" : result.error.message; @@ -220,26 +239,28 @@ describe("Tier AC — agent components", () => { expect(reported).toContain("prompt"); }); - it("AC20: a component's own validation printed error is observed once", function* () { - const observed: string[] = []; - const stub = createStubProvider(); - yield* installStub(stub); - yield* Component.around({ - *raise([error], next) { - observed.push(error.message); - return yield* next(error); - }, - }); - // Written in a region that prints, because what this pins is that the - // diagnostic is observed once and rendered once — which needs it rendered. - const { output } = yield* runDoc( - '\n\n\n', - new InMemoryStream(), - ); - expect(observed).toHaveLength(1); - expect(observed[0]).toContain("Prop validation failed for "); - expect(output.match(//g)).toHaveLength(1); - }); + agentCase( + "AC20: a component's own validation printed error is observed once", + function* (runFresh) { + const observed: string[] = []; + const stub = createStubProvider(); + yield* installStub(stub); + yield* Component.around({ + *raise([error], next) { + observed.push(error.message); + return yield* next(error); + }, + }); + // Written in a region that prints, because what this pins is that the + // diagnostic is observed once and rendered once — which needs it rendered. + const { output } = yield* runFresh( + '\n\n\n', + ); + expect(observed).toHaveLength(1); + expect(observed[0]).toContain("Prop validation failed for "); + expect(output.match(//g)).toHaveLength(1); + }, + ); // The composition the whole component exists for, black box: a value bound by // ``, rendered by ``, consumed and retained by ``. Import @@ -273,109 +294,115 @@ describe("Tier AC — agent components", () => { } }); - it("AC4: as binding captures the response instead of emitting it", function* () { + agentCase("AC4: as binding captures the response instead of emitting it", function* (runFresh) { const stub = createStubProvider(); yield* installStub(stub); - const { output, result } = yield* runDoc( + const { output, result } = yield* runFresh( '\n\nCaptured: {answer}\n', - new InMemoryStream(), ); expect(result.ok).toBe(true); expect(output).toContain("Captured: [stub-agent:stub:default:hi]"); expect(output.indexOf("[stub-agent")).toBe(output.lastIndexOf("[stub-agent")); }); - it("AC5: agent and session scopes compose; per-prompt props override", function* () { - const stub = createStubProvider(); - yield* installStub(stub); - const doc = [ - '', - ' ', - ' ', - " ", - "", - "", - '', - "", - ].join("\n"); - const { result } = yield* runDoc(doc, new InMemoryStream()); - expect(result.ok).toBe(true); - expect(stub.promptCalls.length).toBe(2); - expect(stub.promptCalls[0]).toMatchObject({ - content: "one", - agent: "agent-two", - sessionKey: "stub:review", - }); - expect(stub.promptCalls[1]).toMatchObject({ - content: "two", - agent: "agent-three", - sessionKey: "stub:named", - timeout: 500, - }); - }); - - it("AC6: self-closing and validate without output", function* () { - const stub = createStubProvider(); - yield* installStub(stub); - const { output, result } = yield* runDoc( - '\n\nplain text\n', - new InMemoryStream(), - ); - expect(result.ok).toBe(true); - expect(stub.agentProbes).toContain("probe-me"); - expect(stub.promptCalls.length).toBe(0); - expect(output).toContain("plain text"); - expect(output).not.toContain("probe-me"); - }); - - it("AC7: failed prompts render partial text, later content runs, completion aggregates in order", function* () { - const stub = createStubProvider((content) => { - if (content.includes("first-fail")) { - return { status: "failed", stopReason: "max_tokens", deltas: ["partial-one "] }; - } - if (content.includes("second-fail")) { - return { status: "failed", stopReason: "refusal", deltas: [] }; - } - return {}; - }); - yield* installStub(stub); - const doc = [ - '', - "", - '', - "", - '', - "", - "after all prompts", - "", - ].join("\n"); - const { output, result } = yield* runDoc(doc, new InMemoryStream()); - expect(output).toContain("partial-one"); - expect(output).toContain("after all prompts"); - expect(result.ok).toBe(false); - if (!result.ok) { - expect(result.error).toBeInstanceOf(AggregateError); - if (result.error instanceof AggregateError) { - expect(result.error.message).toBe("2 agent prompt(s) failed"); - const [first, second] = result.error.errors; - expect(first).toBeInstanceOf(AgentPromptError); - expect(second).toBeInstanceOf(AgentPromptError); - if (first instanceof AgentPromptError && second instanceof AgentPromptError) { - expect(first.stopReason).toBe("max_tokens"); - expect(first.agent).toBe("stub-agent"); - expect(first.sessionKey).toBe("stub:default"); - expect(second.stopReason).toBe("refusal"); + agentCase( + "AC5: agent and session scopes compose; per-prompt props override", + function* (runFresh) { + const stub = createStubProvider(); + yield* installStub(stub); + const doc = [ + '', + ' ', + ' ', + " ", + "", + "", + '', + "", + ].join("\n"); + const { result } = yield* runFresh(doc); + expect(result.ok).toBe(true); + expect(stub.promptCalls.length).toBe(2); + expect(stub.promptCalls[0]).toMatchObject({ + content: "one", + agent: "agent-two", + sessionKey: "stub:review", + }); + expect(stub.promptCalls[1]).toMatchObject({ + content: "two", + agent: "agent-three", + sessionKey: "stub:named", + timeout: 500, + }); + }, + ); + + agentCase( + "AC6: self-closing and validate without output", + function* (runFresh) { + const stub = createStubProvider(); + yield* installStub(stub); + const { output, result } = yield* runFresh( + '\n\nplain text\n', + ); + expect(result.ok).toBe(true); + expect(stub.agentProbes).toContain("probe-me"); + expect(stub.promptCalls.length).toBe(0); + expect(output).toContain("plain text"); + expect(output).not.toContain("probe-me"); + }, + ); + + agentCase( + "AC7: failed prompts render partial text, later content runs, completion aggregates in order", + function* (runFresh) { + const stub = createStubProvider((content) => { + if (content.includes("first-fail")) { + return { status: "failed", stopReason: "max_tokens", deltas: ["partial-one "] }; + } + if (content.includes("second-fail")) { + return { status: "failed", stopReason: "refusal", deltas: [] }; + } + return {}; + }); + yield* installStub(stub); + const doc = [ + '', + "", + '', + "", + '', + "", + "after all prompts", + "", + ].join("\n"); + const { output, result } = yield* runFresh(doc); + expect(output).toContain("partial-one"); + expect(output).toContain("after all prompts"); + expect(result.ok).toBe(false); + if (!result.ok) { + expect(result.error).toBeInstanceOf(AggregateError); + if (result.error instanceof AggregateError) { + expect(result.error.message).toBe("2 agent prompt(s) failed"); + const [first, second] = result.error.errors; + expect(first).toBeInstanceOf(AgentPromptError); + expect(second).toBeInstanceOf(AgentPromptError); + if (first instanceof AgentPromptError && second instanceof AgentPromptError) { + expect(first.stopReason).toBe("max_tokens"); + expect(first.agent).toBe("stub-agent"); + expect(first.sessionKey).toBe("stub:default"); + expect(second.stopReason).toBe("refusal"); + } } } - } - }); + }, + ); - it("AC8: throwOnError aborts the document immediately", function* () { + agentCase("AC8: throwOnError aborts the document immediately", function* (runFresh) { const stub = createStubProvider(() => ({ status: "failed", stopReason: "refusal" })); yield* installStub(stub); - const { output, result } = yield* runDoc( + const { output, result } = yield* runFresh( '\n\nnever reached\n', - new InMemoryStream(), ); expect(result.ok).toBe(false); if (!result.ok) { diff --git a/packages/testing/tests/execution-harness.test.ts b/packages/testing/tests/execution-harness.test.ts index 2f159900b..ef14cfae9 100644 --- a/packages/testing/tests/execution-harness.test.ts +++ b/packages/testing/tests/execution-harness.test.ts @@ -305,36 +305,48 @@ describe(RUN_SUITE, () => { expect((yield* readdir(artifacts)).sort()).toEqual([...directories].sort()); }); - it("selects one target inside a document without component addressability", function* () { - const run = yield* runHarness({ - "README.md": doc( - '', - '', - '', - "", - "", - '', - "", - "", - ), - "guide.md": doc("# First", "", "first body", "", "# Second", "", "second body"), - }); - expect(only(run).status).toBe("pass"); - expect(run.output).not.toContain("first body"); + const selectedTarget = "selects one target inside a document without component addressability"; + it(selectedTarget, function* () { + yield* captureHarness( + selectedTarget, + { + "README.md": doc( + '', + '', + '', + "", + "", + '', + "", + "", + ), + "guide.md": doc("# First", "", "first body", "", "# Second", "", "second body"), + }, + (run) => { + expect(only(run).status).toBe("pass"); + expect(run.output).not.toContain("first body"); + }, + ); }); - it("carries a text root's rendered markdown as the settled value", function* () { - const run = yield* runHarness({ - "README.md": doc( - '', - '', - '', - "", - "", - ), - "child.md": doc("child body"), - }); - expect(only(run).status).toBe("pass"); + const textRoot = "carries a text root's rendered markdown as the settled value"; + it(textRoot, function* () { + yield* captureHarness( + textRoot, + { + "README.md": doc( + '', + '', + '', + "", + "", + ), + "child.md": doc("child body"), + }, + (run) => { + expect(only(run).status).toBe("pass"); + }, + ); }); const inline = "runs inline source under the identity, with no authored file"; From 576f139f207129ec18e3ac06b4e7ece9a6cf6003 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:04:00 -0500 Subject: [PATCH 11/78] test: attribute fresh REPL observation entry journals --- packages/cli/tests/repl-model.test.ts | 22 ++- ...ained-repository-observations-deno.test.ts | 154 +++++++++--------- .../retained-repository-observations.test.ts | 125 +++++++------- .../cli/tests/support/repl-observations.ts | 10 ++ 4 files changed, 176 insertions(+), 135 deletions(-) diff --git a/packages/cli/tests/repl-model.test.ts b/packages/cli/tests/repl-model.test.ts index 4ff20c653..ab73ba344 100644 --- a/packages/cli/tests/repl-model.test.ts +++ b/packages/cli/tests/repl-model.test.ts @@ -19,6 +19,7 @@ import { * binding in a scope that never published it. */ +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { beforeAll, describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { Component, useTempFileCompiler } from "@executablemd/core"; @@ -451,14 +452,21 @@ describe("REPL model: the histories it refuses", () => { expect(refusal(stripped)).toContain("does not retain the schema"); }); - it("E1: a refused answer leaves no answered question in the projection", function* () { - const run = yield* runReference(answering({ decision: "maybe" })); - const model = projected(run.events); + const rejectedAnswer = "E1: a refused answer leaves no answered question in the projection"; + it(rejectedAnswer, () => + captureTestJournal( + { owner: "packages/cli/tests/repl-model.test.ts", name: rejectedAnswer }, + "", + function* (stream) { + const run = yield* runReference(answering({ decision: "maybe" }), stream); + const model = projected(run.events); - expect(run.asked).toHaveLength(1); - expect(only(model)?.elicitations).toEqual([]); - expect(model.transcript.some((row) => row.kind === "elicit")).toBe(false); - }); + expect(run.asked).toHaveLength(1); + expect(only(model)?.elicitations).toEqual([]); + expect(model.transcript.some((row) => row.kind === "elicit")).toBe(false); + }, + ), + ); }); /** diff --git a/packages/cli/tests/retained-repository-observations-deno.test.ts b/packages/cli/tests/retained-repository-observations-deno.test.ts index ce1bd56b2..208bcec3f 100644 --- a/packages/cli/tests/retained-repository-observations-deno.test.ts +++ b/packages/cli/tests/retained-repository-observations-deno.test.ts @@ -33,6 +33,7 @@ import { import { useCommonDirectoryLease } from "../src/repl/repositories/deno/leases.ts"; import { useObservationFixture, writeFixtureFile } from "../../git/tests/support/observations.ts"; import { + captureObservationEntry, entryCounters, methodsCalled, readKinds, @@ -128,7 +129,8 @@ describe("ROB5 — cancellation, persistence and ownership, on a native host", ( ); }); - it("keeps the same entry's mutation out of a held read, then lets it through", function* () { + const heldRead = "keeps the same entry's mutation out of a held read, then lets it through"; + it(heldRead, function* () { const fixture = yield* useObservationFixture(); const place = yield* useEntryPlace(fixture); const counted = entryCounters(); @@ -140,80 +142,86 @@ describe("ROB5 — cancellation, persistence and ownership, on a native host", ( let holding = false; let enteredWhileHeld = false; - const settled = yield* scoped(function* () { - const task = yield* spawn(() => - runEntry( - place, - [ - "", - '', - '', - "", - "", - ].join("\n"), - new InMemoryStream(), - counted, - { - *between(): Operation { - // The second branch starts its mutation only once the read is - // genuinely held, so the race the regression needs is arranged - // rather than hoped for. - yield* registerComponents([ - { - name: "WaitsForTheRead", - origin: "test://waits-for-the-read", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn(): Operation { - yield* readHeld.operation; - return ""; - }, + yield* captureObservationEntry( + { owner: "packages/cli/tests/retained-repository-observations-deno.test.ts", name: heldRead }, + place, + function* (stream) { + const settled = yield* scoped(function* () { + const task = yield* spawn(() => + runEntry( + place, + [ + "", + '', + '', + "", + "", + ].join("\n"), + stream, + counted, + { + *between(): Operation { + // The second branch starts its mutation only once the read is + // genuinely held, so the race the regression needs is arranged + // rather than hoped for. + yield* registerComponents([ + { + name: "WaitsForTheRead", + origin: "test://waits-for-the-read", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn(): Operation { + yield* readHeld.operation; + return ""; + }, + }, + ]); }, - ]); - }, - *barrier(method): Operation { - if (method === "add") { - if (holding) { - enteredWhileHeld = true; - } - mutationEntered.resolve(); - return; - } - if (method === "observe" && !holding) { - holding = true; - readHeld.resolve(); - // Long enough that a mutation on a queue of its own would have - // reached the host by now, and short enough to end the case. - yield* race([ - mutationEntered.operation, - (function* (): Operation { - yield* sleep(2000); - })(), - ]); - holding = false; - releaseRead.resolve(); - } - }, - }, - ), - ); - yield* releaseRead.operation; - // The read has finished its own turn; the mutation may now proceed. - yield* race([ - mutationEntered.operation, - (function* (): Operation { - yield* sleep(30_000); - throw new Error("the mutation never reached native Git"); - })(), - ]); - return yield* task; - }); + *barrier(method): Operation { + if (method === "add") { + if (holding) { + enteredWhileHeld = true; + } + mutationEntered.resolve(); + return; + } + if (method === "observe" && !holding) { + holding = true; + readHeld.resolve(); + // Long enough that a mutation on a queue of its own would have + // reached the host by now, and short enough to end the case. + yield* race([ + mutationEntered.operation, + (function* (): Operation { + yield* sleep(2000); + })(), + ]); + holding = false; + releaseRead.resolve(); + } + }, + }, + ), + ); + yield* releaseRead.operation; + // The read has finished its own turn; the mutation may now proceed. + yield* race([ + mutationEntered.operation, + (function* (): Operation { + yield* sleep(30_000); + throw new Error("the mutation never reached native Git"); + })(), + ]); + return yield* task; + }); - // Nothing of this entry's own Git entered while its read held the turn, - // and the mutation did run once the read released it. - expect(enteredWhileHeld).toBe(false); - expect(settled.refusal).toBe(undefined); - expect(readKinds(counted)).toContain("diff"); - expect(methodsCalled(counted)).toContain("add"); + // Nothing of this entry's own Git entered while its read held the turn, + // and the mutation did run once the read released it. + expect(enteredWhileHeld).toBe(false); + expect(settled.refusal).toBe(undefined); + expect(readKinds(counted)).toContain("diff"); + expect(methodsCalled(counted)).toContain("add"); + }, + ); }); it("answers while another holder has the checkout's mutation lease", function* () { diff --git a/packages/cli/tests/retained-repository-observations.test.ts b/packages/cli/tests/retained-repository-observations.test.ts index f1a65dc09..b307d1c0b 100644 --- a/packages/cli/tests/retained-repository-observations.test.ts +++ b/packages/cli/tests/retained-repository-observations.test.ts @@ -55,6 +55,7 @@ import { admitReplRepositoryHistory } from "../src/repl/repositories/admission.t import { Elicitation } from "@executablemd/core"; import { useObservationFixture, writeFixtureFile } from "../../git/tests/support/observations.ts"; import { + captureObservationEntry, entryCounters, methodsCalled, readKinds, @@ -583,79 +584,93 @@ describe("ROB2 — the record is closed, and named by the request it carries", ( }); describe("ROB3 — ordinary middleware keeps its ordinary meaning", () => { - it("creates no record when a replacement answers above the provider", function* () { + const replacement = "creates no record when a replacement answers above the provider"; + it(replacement, function* () { const fixture = yield* useObservationFixture(); const place = yield* useEntryPlace(fixture); const counted = entryCounters(); const answered: string[] = []; - const run = yield* runEntry( + yield* captureObservationEntry( + { owner: "packages/cli/tests/retained-repository-observations.test.ts", name: replacement }, place, - ['', "", "", ""].join("\n"), - new InMemoryStream(), - counted, - { - *between(): Operation { - yield* GitQuery.around({ - // deno-lint-ignore require-yield - *diff([invocation]: [GitDiffInvocation]): Operation { - answered.push(invocation.request.kind); - return { - comparison: { compare: "unstaged" }, - text: "answered above", - offset: 0, - length: 14, - next: null, - }; + function* (stream) { + const run = yield* runEntry( + place, + ['', "", "", ""].join("\n"), + stream, + counted, + { + *between(): Operation { + yield* GitQuery.around({ + // deno-lint-ignore require-yield + *diff([invocation]: [GitDiffInvocation]): Operation { + answered.push(invocation.request.kind); + return { + comparison: { compare: "unstaged" }, + text: "answered above", + offset: 0, + length: 14, + next: null, + }; + }, + }); }, - }); - }, + }, + ); + + expect(run.refusal).toBe(undefined); + expect(answered).toEqual(["diff"]); + expect(run.output).toContain("answered above"); + // Answered entirely above the provider, so no provider was reached: no + // native read, no scratch directory and no observation record. + expect(observations(run.events)).toEqual([]); + // Ambient discovery still happened — the component asks which repository is + // in scope before it asks anything of it — but not one native *read* ran. + expect(readKinds(counted)).toEqual([]); }, ); - - expect(run.refusal).toBe(undefined); - expect(answered).toEqual(["diff"]); - expect(run.output).toContain("answered above"); - // Answered entirely above the provider, so no provider was reached: no - // native read, no scratch directory and no observation record. - expect(observations(run.events)).toEqual([]); - // Ambient discovery still happened — the component asks which repository is - // in scope before it asks anything of it — but not one native *read* ran. - expect(readKinds(counted)).toEqual([]); }); - it("records the request a delegating replacement actually passed down", function* () { + const delegation = "records the request a delegating replacement actually passed down"; + it(delegation, function* () { const fixture = yield* useObservationFixture(); const place = yield* useEntryPlace(fixture); const counted = entryCounters(); - const run = yield* runEntry( + yield* captureObservationEntry( + { owner: "packages/cli/tests/retained-repository-observations.test.ts", name: delegation }, place, - ['', ""].join("\n"), - new InMemoryStream(), - counted, - { - *between(): Operation { - yield* GitQuery.around({ - diff: ([invocation]: [GitDiffInvocation], next): Operation => - next({ ...invocation, request: { ...invocation.request, limit: 7 } }), - }); - }, + function* (stream) { + const run = yield* runEntry( + place, + ['', ""].join("\n"), + stream, + counted, + { + *between(): Operation { + yield* GitQuery.around({ + diff: ([invocation]: [GitDiffInvocation], next): Operation => + next({ ...invocation, request: { ...invocation.request, limit: 7 } }), + }); + }, + }, + ); + + expect(run.refusal).toBe(undefined); + const recorded = observations(run.events); + expect(recorded).toHaveLength(1); + // The request the provider received, not the one the document wrote. + expect(recorded[0]?.record.request.query).toEqual({ + kind: "diff", + comparison: { compare: "unstaged" }, + paths: null, + offset: 0, + limit: 7, + cursor: null, + }); }, ); - - expect(run.refusal).toBe(undefined); - const recorded = observations(run.events); - expect(recorded).toHaveLength(1); - // The request the provider received, not the one the document wrote. - expect(recorded[0]?.record.request.query).toEqual({ - kind: "diff", - comparison: { compare: "unstaged" }, - paths: null, - offset: 0, - limit: 7, - cursor: null, - }); }); }); diff --git a/packages/cli/tests/support/repl-observations.ts b/packages/cli/tests/support/repl-observations.ts index e55939b07..f2dbd02eb 100644 --- a/packages/cli/tests/support/repl-observations.ts +++ b/packages/cli/tests/support/repl-observations.ts @@ -42,6 +42,8 @@ import { useCompositionComponents } from "@executablemd/git"; import { useReplRepositoryRecording } from "../../src/repl/repositories/deno/provider.ts"; import { admitReplRepositoryHistory } from "../../src/repl/repositories/admission.ts"; import type { ObservationFixture } from "../../../git/tests/support/observations.ts"; +import { captureTestJournal } from "../../../test-support/failure-journal.ts"; +import type { JournalCase } from "../../src/test-diagnostics.ts"; /** What the repository handle beneath one entry was asked to do. */ export interface EntryCounters { @@ -265,6 +267,14 @@ export function runEntry( }); } +export function captureObservationEntry( + testCase: JournalCase, + place: EntryPlace, + body: (stream: InMemoryStream) => Operation, +): Operation { + return captureTestJournal(testCase, join(place.root, "entry.md"), body); +} + /** * The prefix an entry left behind when it was left at a question. * From 7de6ad03a73e8c3500ffe60ef4522ad3d0046566 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:05:31 -0500 Subject: [PATCH 12/78] test: capture additional direct Core execution journals --- packages/core/tests/ephemeral-service.test.ts | 46 +- packages/core/tests/execute.test.ts | 453 ++++++++++-------- packages/core/tests/source-position.test.ts | 176 +++---- 3 files changed, 360 insertions(+), 315 deletions(-) diff --git a/packages/core/tests/ephemeral-service.test.ts b/packages/core/tests/ephemeral-service.test.ts index 03de69a46..f83cf8132 100644 --- a/packages/core/tests/ephemeral-service.test.ts +++ b/packages/core/tests/ephemeral-service.test.ts @@ -17,6 +17,9 @@ import { collect } from "../src/collect.ts"; import { execute } from "../src/execute.ts"; import { LiveBindingCollisionError } from "../src/live-env.ts"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/ephemeral-service.test.ts"); const SAMPLE = `--- meta: @@ -548,11 +551,13 @@ const shared = "must-not-execute"; ).toHaveLength(1); }); - it("allows a later ephemeral eval to update an existing live binding", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "doc.md": `\n`, - "components/Provider.md": `--- + journalCase( + "allows a later ephemeral eval to update an existing live binding", + "doc.md", + function* (stream) { + yield* useStubFs({ + "doc.md": `\n`, + "components/Provider.md": `--- meta: componentName: Provider --- @@ -574,21 +579,22 @@ yield* Sample.around({ `, - "components/Sample.md": SAMPLE, - }); + "components/Sample.md": SAMPLE, + }); - const output = String( - yield* scoped(function* () { - return yield* collect( - yield* execute({ - path: "doc.md", - stream, - includes: ["components", "."], - }), - ); - }), - ); + const output = String( + yield* scoped(function* () { + return yield* collect( + yield* execute({ + path: "doc.md", + stream, + includes: ["components", "."], + }), + ); + }), + ); - expect(output).toContain("second"); - }); + expect(output).toContain("second"); + }, + ); }); diff --git a/packages/core/tests/execute.test.ts b/packages/core/tests/execute.test.ts index d051bdb0d..a07ec4061 100644 --- a/packages/core/tests/execute.test.ts +++ b/packages/core/tests/execute.test.ts @@ -26,6 +26,9 @@ import { execute } from "../src/execute.ts"; import { collect } from "../src/collect.ts"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import { asText } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/execute.test.ts"); /** * A stand-in child that behaves like one: it writes its output to the display @@ -206,19 +209,22 @@ describe("Tier B — durable import", () => { }); // B9: import missing component — uncaught at the root, so it fails the run - it("B9: import missing component — the run fails and reports it", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ "README.md": "\n" }); - yield* useStubExec(); - - const message = yield* failure(function* () { - return yield* collect(yield* execute({ path: "README.md", stream })); - }); + journalCase( + "B9: import missing component — the run fails and reports it", + "README.md", + function* (stream) { + yield* useStubFs({ "README.md": "\n" }); + yield* useStubExec(); + + const message = yield* failure(function* () { + return yield* collect(yield* execute({ path: "README.md", stream })); + }); - expect( - message.includes("Cannot resolve component") || message.includes("Failed to import"), - ).toBeTruthy(); - }); + expect( + message.includes("Cannot resolve component") || message.includes("Failed to import"), + ).toBeTruthy(); + }, + ); // B12: root document as component — __root__ import, same journal shape it("B12: root document imported as __root__", function* () { @@ -282,9 +288,9 @@ describe("Tier B — durable import", () => { }); // B15: default resolver middleware — resolves via stat in search path order - it("B15: resolver searches component dirs in order", function* () { + journalCase("B15: resolver searches component dirs in order", "README.md", function* (stream) { // Component exists in root dir (second search path), not components/ - const stream = new InMemoryStream(); + yield* useStubFs({ "README.md": "\n", "Banner.md": "Banner from root\n", @@ -367,8 +373,7 @@ describe("Tier D — code execution and modifiers", () => { }); // D3: a nonzero exit is a checked failure, with or without (#441) - it("D3: non-zero exit code → the run fails", function* () { - const stream = new InMemoryStream(); + journalCase("D3: non-zero exit code → the run fails", "README.md", function* (stream) { yield* useStubFs({ "README.md": ["```bash exec", "failing-command", "```"].join("\n") }); yield* useFailingExec(1, "command not found"); @@ -382,23 +387,26 @@ describe("Tier D — code execution and modifiers", () => { // D3b: the same rule for a command that printed before it failed (#307), run // as a real subprocess so the exit code travels the whole way through // `execFactory` rather than a stub's return value. - it("D3b: non-zero exit with stdout → output, then the printed error", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": ["```bash exec", "echo partial; exit 1", "```"].join("\n"), - }); + journalCase( + "D3b: non-zero exit with stdout → output, then the printed error", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": ["```bash exec", "echo partial; exit 1", "```"].join("\n"), + }); - const run = yield* displayed(function* () { - return yield* failure(function* () { - return yield* collect(yield* execute({ path: "README.md", stream })); + const run = yield* displayed(function* () { + return yield* failure(function* () { + return yield* collect(yield* execute({ path: "README.md", stream })); + }); }); - }); - // What the command printed before it failed reached the reader; the run - // then fails rather than rendering the diagnostic and carrying on (#441). - expect(run.stdout).toContain("partial"); - expect(run.value).toContain("Command failed (exit 1)"); - }); + // What the command printed before it failed reached the reader; the run + // then fails rather than rendering the diagnostic and carrying on (#441). + expect(run.stdout).toContain("partial"); + expect(run.value).toContain("Command failed (exit 1)"); + }, + ); // D4: multi-line command — full script passed to -c it("D4: multi-line command — full script in journal", function* () { @@ -597,88 +605,97 @@ describe("Tier D — code execution and modifiers", () => { }); // D15: unknown modifier in chain → error, uncaught, so the run fails - it("D15: unknown modifier → the run fails and reports it", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": ["```bash frobnicate exec", "echo test", "```"].join("\n"), - }); - yield* useStubExec(); + journalCase( + "D15: unknown modifier → the run fails and reports it", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": ["```bash frobnicate exec", "echo test", "```"].join("\n"), + }); + yield* useStubExec(); - const message = yield* failure(function* () { - return yield* collect(yield* execute({ path: "README.md", stream })); - }); + const message = yield* failure(function* () { + return yield* collect(yield* execute({ path: "README.md", stream })); + }); - expect(message.includes("Unknown modifier") || message.includes("frobnicate")).toBeTruthy(); - }); + expect(message.includes("Unknown modifier") || message.includes("frobnicate")).toBeTruthy(); + }, + ); // D16: no terminal modifier → error - it("D16: no terminal modifier — code block without exec/eval is passive text", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": ["```bash", "echo test", "```"].join("\n"), - }); - yield* useStubExec(); + journalCase( + "D16: no terminal modifier — code block without exec/eval is passive text", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": ["```bash", "echo test", "```"].join("\n"), + }); + yield* useStubExec(); - const result = asText( - yield* collect( - yield* execute({ - path: "README.md", - stream, - }), - ), - ); + const result = asText( + yield* collect( + yield* execute({ + path: "README.md", + stream, + }), + ), + ); - // Without exec/eval, code block is passive text — preserved as-is - expect(result).toContain("```bash"); - expect(result).toContain("echo test"); - }); + // Without exec/eval, code block is passive text — preserved as-is + expect(result).toContain("```bash"); + expect(result).toContain("echo test"); + }, + ); // D17: custom modifier registration - it("D17: custom modifier registration — handler runs in chain", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - // A forwarded block renders nothing, so the text a modifier transforms - // comes from the region that asked for it (#441). - "README.md": [ - '', - "```bash uppercase exec", - "echo hello", - "```", - "", - "", - "{shouted}", - ].join("\n"), - }); - yield* useStubExec(); + journalCase( + "D17: custom modifier registration — handler runs in chain", + "README.md", + function* (stream) { + yield* useStubFs({ + // A forwarded block renders nothing, so the text a modifier transforms + // comes from the region that asked for it (#441). + "README.md": [ + '', + "```bash uppercase exec", + "echo hello", + "```", + "", + "", + "{shouted}", + ].join("\n"), + }); + yield* useStubExec(); - const result = asText( - yield* collect( - yield* execute({ - path: "README.md", - stream, - modifiers: { - uppercase: (_params) => (_args, next) => - (function* () { - const inner = yield* next(); - return { - output: inner.output.toUpperCase(), - exitCode: inner.exitCode, - stderr: inner.stderr, - }; - })(), - }, - }), - ), - ); + const result = asText( + yield* collect( + yield* execute({ + path: "README.md", + stream, + modifiers: { + uppercase: (_params) => (_args, next) => + (function* () { + const inner = yield* next(); + return { + output: inner.output.toUpperCase(), + exitCode: inner.exitCode, + stderr: inner.stderr, + }; + })(), + }, + }), + ), + ); - expect(result).toContain("HELLO"); - }); + expect(result).toContain("HELLO"); + }, + ); // D19: modifier parsing — timeout=30s - it("D19: modifier with params parsed correctly", function* () { + journalCase("D19: modifier with params parsed correctly", "README.md", function* (stream) { // We test that the modifier receives its params let receivedParams: string | undefined; - const stream = new InMemoryStream(); + yield* useStubFs({ "README.md": ["```bash timeout=30s exec", "echo test", "```"].join("\n"), }); @@ -796,8 +813,7 @@ describe("execute", () => { }); // E6: Props flow through expansion - it("E6: validated props flow through expansion", function* () { - const stream = new InMemoryStream(); + journalCase("E6: validated props flow through expansion", "README.md", function* (stream) { yield* useStubFs({ "README.md": '\n', "components/Greeting.md": [ @@ -829,8 +845,7 @@ describe("execute", () => { }); // E7: Undeclared prop in full document — uncaught, so the run fails - it("E7: undeclared prop fails the run and reports it", function* () { - const stream = new InMemoryStream(); + journalCase("E7: undeclared prop fails the run and reports it", "README.md", function* (stream) { yield* useStubFs({ "README.md": '\n', "components/Badge.md": ["---", "color: blue", "---", "", "badge"].join("\n"), @@ -875,8 +890,7 @@ describe("execute", () => { }); // Simple text document — no components, no exec - it("simple text document — passthrough", function* () { - const stream = new InMemoryStream(); + journalCase("simple text document — passthrough", "README.md", function* (stream) { yield* useStubFs({ "README.md": "# Hello World\n\nThis is a test.\n" }); yield* useStubExec(); @@ -893,8 +907,7 @@ describe("execute", () => { }); // Default props applied - it("default props applied when not provided", function* () { - const stream = new InMemoryStream(); + journalCase("default props applied when not provided", "README.md", function* (stream) { yield* useStubFs({ "README.md": "\n", "components/Greeting.md": [ @@ -1035,36 +1048,39 @@ describe("execute", () => { }); // E10: unclosed bold across component boundary — healed - it("E10: unclosed bold across component boundary — healed in first segment", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": "This is **bold\n\nmore text\n", - "components/Greeting.md": "greeting\n", - }); - yield* useStubExec(); + journalCase( + "E10: unclosed bold across component boundary — healed in first segment", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": "This is **bold\n\nmore text\n", + "components/Greeting.md": "greeting\n", + }); + yield* useStubExec(); - const result = asText( - yield* collect( - yield* execute({ - path: "README.md", - stream, - }), - ), - ); + const result = asText( + yield* collect( + yield* execute({ + path: "README.md", + stream, + }), + ), + ); - // The **bold should be healed (closed) before component expansion. - // remend appends closing ** after the text segment (including trailing \n). - // Result: "This is **bold\n**" + "greeting\n" + "\nmore text\n" - expect(result).toContain("greeting"); - expect(result).toContain("more text"); - - // The first text segment should be healed — it should contain both - // opening ** and closing ** (remend closes the unclosed bold). - // The closing ** appears after the newline: "**bold\n**" - const beforeComponent = result.split("greeting")[0]!; - const openCount = (beforeComponent.match(/\*\*/g) || []).length; - expect(openCount).toBe(2); - }); + // The **bold should be healed (closed) before component expansion. + // remend appends closing ** after the text segment (including trailing \n). + // Result: "This is **bold\n**" + "greeting\n" + "\nmore text\n" + expect(result).toContain("greeting"); + expect(result).toContain("more text"); + + // The first text segment should be healed — it should contain both + // opening ** and closing ** (remend closes the unclosed bold). + // The closing ** appears after the newline: "**bold\n**" + const beforeComponent = result.split("greeting")[0]!; + const openCount = (beforeComponent.match(/\*\*/g) || []).length; + expect(openCount).toBe(2); + }, + ); // E2 complex: full replay with component + exec — zero I/O it("E2 complex: full replay with component + exec — zero I/O on second run", function* () { @@ -1190,8 +1206,7 @@ describe("execute", () => { }); // Content slot with exec - it("Content slot + exec — both work together", function* () { - const stream = new InMemoryStream(); + journalCase("Content slot + exec — both work together", "README.md", function* (stream) { yield* useStubFs({ "README.md": ["", "```bash exec", "echo inside", "```", ""].join("\n"), "components/Wrapper.md": "BEFORE\n\nAFTER\n", @@ -1246,93 +1261,107 @@ describe("Component Api dispatch — journal shape", () => { }); describe("component-declared output — document workflow", () => { - it("applies to an imported component invoked from a streaming root", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": "Intro paragraph.\n\n\n", - "components/Warn.md": "Docs line.\n\n\nWARNING_SHOWN\n\n", - }); - yield* useStubExec(); - const output = yield* collect(yield* execute({ path: "README.md", stream })); - expect(output).toContain("Intro paragraph."); - expect(output).toContain("WARNING_SHOWN"); - expect(output).not.toContain("Docs line"); - }); + journalCase( + "applies to an imported component invoked from a streaming root", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": "Intro paragraph.\n\n\n", + "components/Warn.md": "Docs line.\n\n\nWARNING_SHOWN\n\n", + }); + yield* useStubExec(); + const output = yield* collect(yield* execute({ path: "README.md", stream })); + expect(output).toContain("Intro paragraph."); + expect(output).toContain("WARNING_SHOWN"); + expect(output).not.toContain("Docs line"); + }, + ); - it("applies to a root document the same way", function* () { - const stream = new InMemoryStream(); + journalCase("applies to a root document the same way", "README.md", function* (stream) { yield* useStubFs({ "README.md": "Root docs.\n\n\nROOT_SHOWN\n\n" }); const output = yield* collect(yield* execute({ path: "README.md", stream })); expect(output).toContain("ROOT_SHOWN"); expect(output).not.toContain("Root docs"); }); - it("buffers a root with into a single emission after success", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ "README.md": "Root docs.\n\n\nROOT_SHOWN\n\n" }); - - const execution = yield* execute({ path: "README.md", stream }); - const chunks: string[] = []; - const full = yield* forEach(function* (chunk: string) { - chunks.push(chunk); - }, execution.output); - - expect(full).toContain("ROOT_SHOWN"); - expect(chunks).toHaveLength(1); - }); - - it("emits what a buffered root selected before its documentation failed", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": "\nSELECTED\n\n\n```bash exec\nfailing-command\n```\n", - }); - yield* useFailingExec(1, "command not found"); - - const execution = yield* execute({ path: "README.md", stream }); - const chunks: string[] = []; - yield* forEach(function* (chunk: string) { - chunks.push(chunk); - }, execution.output); - - const result = yield* execution; - expect(result.ok).toBe(false); - // The region completed before the documentation ran, so its text is part - // of what this run rendered — and a run that fails still hands over what it - // rendered (§6.9 Partial output). - expect(chunks.join("")).toContain("SELECTED"); - }); - - it("keeps per-segment streaming for roots without ", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - // Two rendering segments around a foreground block, whose own output - // goes to the reader rather than into the document (#441). - "README.md": "one\n\n```bash exec\necho between\n```\n\ntwo\n", - }); - yield* useStubExec(); - - const execution = yield* execute({ path: "README.md", stream }); - const chunks: string[] = []; - yield* forEach(function* (chunk: string) { - chunks.push(chunk); - }, execution.output); + journalCase( + "buffers a root with into a single emission after success", + "README.md", + function* (stream) { + yield* useStubFs({ "README.md": "Root docs.\n\n\nROOT_SHOWN\n\n" }); - expect(chunks.length).toBeGreaterThanOrEqual(2); - }); + const execution = yield* execute({ path: "README.md", stream }); + const chunks: string[] = []; + const full = yield* forEach(function* (chunk: string) { + chunks.push(chunk); + }, execution.output); - it("emits no output event for an empty buffered root ", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ "README.md": "Root docs.\n\n\n" }); + expect(full).toContain("ROOT_SHOWN"); + expect(chunks).toHaveLength(1); + }, + ); + + journalCase( + "emits what a buffered root selected before its documentation failed", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": "\nSELECTED\n\n\n```bash exec\nfailing-command\n```\n", + }); + yield* useFailingExec(1, "command not found"); + + const execution = yield* execute({ path: "README.md", stream }); + const chunks: string[] = []; + yield* forEach(function* (chunk: string) { + chunks.push(chunk); + }, execution.output); + + const result = yield* execution; + expect(result.ok).toBe(false); + // The region completed before the documentation ran, so its text is part + // of what this run rendered — and a run that fails still hands over what it + // rendered (§6.9 Partial output). + expect(chunks.join("")).toContain("SELECTED"); + }, + ); + + journalCase( + "keeps per-segment streaming for roots without ", + "README.md", + function* (stream) { + yield* useStubFs({ + // Two rendering segments around a foreground block, whose own output + // goes to the reader rather than into the document (#441). + "README.md": "one\n\n```bash exec\necho between\n```\n\ntwo\n", + }); + yield* useStubExec(); - const execution = yield* execute({ path: "README.md", stream }); - const chunks: string[] = []; - const full = yield* forEach(function* (chunk: string) { - chunks.push(chunk); - }, execution.output); + const execution = yield* execute({ path: "README.md", stream }); + const chunks: string[] = []; + yield* forEach(function* (chunk: string) { + chunks.push(chunk); + }, execution.output); - expect(chunks).toHaveLength(0); - expect(full).toBe(""); - }); + expect(chunks.length).toBeGreaterThanOrEqual(2); + }, + ); + + journalCase( + "emits no output event for an empty buffered root ", + "README.md", + function* (stream) { + yield* useStubFs({ "README.md": "Root docs.\n\n\n" }); + + const execution = yield* execute({ path: "README.md", stream }); + const chunks: string[] = []; + const full = yield* forEach(function* (chunk: string) { + chunks.push(chunk); + }, execution.output); + + expect(chunks).toHaveLength(0); + expect(full).toBe(""); + }, + ); it("replays a buffered root to the same result", function* () { const stream = new InMemoryStream(); diff --git a/packages/core/tests/source-position.test.ts b/packages/core/tests/source-position.test.ts index 749d28486..5cfdc8121 100644 --- a/packages/core/tests/source-position.test.ts +++ b/packages/core/tests/source-position.test.ts @@ -1,6 +1,5 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { InMemoryStream } from "@executablemd/durable-streams"; import { useStubFs } from "@executablemd/runtime/test"; import { scanSegments } from "../src/scanner.ts"; import { SOURCE_POSITION_FIELD, sourceDescription } from "../src/source-position.ts"; @@ -9,6 +8,9 @@ import { registerComponents } from "../src/components/registration.ts"; import { execute } from "../src/execute.ts"; import { collect } from "../src/collect.ts"; import type { ComponentElement, SourcePosition } from "../src/types.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/source-position.test.ts"); function componentsOf(segments: ReturnType): ComponentElement[] { const found: ComponentElement[] = []; @@ -51,92 +53,100 @@ describe("source positions", () => { }); }); - it("computes original-file positions past frontmatter, immune to repeated body text", function* () { - // The frontmatter contains a copy of the body's first line: a content - // search for the body would false-match inside the frontmatter, so only - // the suffix computation yields the correct base. - const doc = [ - "---", - 'title: ""', - "note: intro line", - "---", - "intro line", - "", - "", - ].join("\n"); - - const positions: SourcePosition[] = []; - const stream = new InMemoryStream(); - yield* useStubFs({ "README.md": doc }); - // Registered rather than a repository file, so the probe can record what - // the engine tells a component about its own call site. That is the public - // guarantee now — `getExpansion()` — rather than what a claim was offered. - yield* registerComponents([ - { - name: "Probe", - origin: "test", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn() { - const position = (yield* getExpansion()).position; - if (position) { - positions.push(position); - } - return "probed"; + journalCase( + "computes original-file positions past frontmatter, immune to repeated body text", + "README.md", + function* (stream) { + // The frontmatter contains a copy of the body's first line: a content + // search for the body would false-match inside the frontmatter, so only + // the suffix computation yields the correct base. + const doc = [ + "---", + 'title: ""', + "note: intro line", + "---", + "intro line", + "", + "", + ].join("\n"); + + const positions: SourcePosition[] = []; + + yield* useStubFs({ "README.md": doc }); + // Registered rather than a repository file, so the probe can record what + // the engine tells a component about its own call site. That is the public + // guarantee now — `getExpansion()` — rather than what a claim was offered. + yield* registerComponents([ + { + name: "Probe", + origin: "test", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn() { + const position = (yield* getExpansion()).position; + if (position) { + positions.push(position); + } + return "probed"; + }, }, - }, - ]); - - const output = yield* collect(yield* execute({ path: "README.md", stream })); - expect(output).toContain("probed"); - - const probeLine = doc.split("\n").indexOf("") + 1; - expect(positions).toEqual([ - { - path: "README.md", - offset: doc.indexOf("\n") + 1, - line: probeLine, - column: 1, - }, - ]); - }); - - it("positions imported-component invocations in the component's own file", function* () { - const readme = "\n"; - const wrapper = ["---", "title: Wrapper", "---", "before", "", ""].join("\n"); - - const positions: Array<{ name: string; position?: SourcePosition }> = []; - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": readme, - "components/Wrapper.md": wrapper, - }); - yield* registerComponents([ - { - name: "Probe", - origin: "test", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn() { - const metadata = yield* getExpansion(); - positions.push({ - name: metadata.name, - ...(metadata.position ? { position: metadata.position } : {}), - }); - return "probed"; + ]); + + const output = yield* collect(yield* execute({ path: "README.md", stream })); + expect(output).toContain("probed"); + + const probeLine = doc.split("\n").indexOf("") + 1; + expect(positions).toEqual([ + { + path: "README.md", + offset: doc.indexOf("\n") + 1, + line: probeLine, + column: 1, }, - }, - ]); + ]); + }, + ); + + journalCase( + "positions imported-component invocations in the component's own file", + "README.md", + function* (stream) { + const readme = "\n"; + const wrapper = ["---", "title: Wrapper", "---", "before", "", ""].join("\n"); + + const positions: Array<{ name: string; position?: SourcePosition }> = []; + + yield* useStubFs({ + "README.md": readme, + "components/Wrapper.md": wrapper, + }); + yield* registerComponents([ + { + name: "Probe", + origin: "test", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn() { + const metadata = yield* getExpansion(); + positions.push({ + name: metadata.name, + ...(metadata.position ? { position: metadata.position } : {}), + }); + return "probed"; + }, + }, + ]); - const output = yield* collect(yield* execute({ path: "README.md", stream })); - expect(output).toContain("probed"); + const output = yield* collect(yield* execute({ path: "README.md", stream })); + expect(output).toContain("probed"); - const probe = positions.find((p) => p.name === "Probe"); - expect(probe?.position).toEqual({ - path: "components/Wrapper.md", - offset: wrapper.indexOf(""), - line: 5, - column: 1, - }); - }); + const probe = positions.find((p) => p.name === "Probe"); + expect(probe?.position).toEqual({ + path: "components/Wrapper.md", + offset: wrapper.indexOf(""), + line: 5, + column: 1, + }); + }, + ); }); /** From e9d5c7fc91d06d2ad4e476f5ef88ec650f0bdaaf Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:08:06 -0500 Subject: [PATCH 13/78] test: attribute fresh workflow observation journals --- .../tests/generated-observations.test.ts | 327 ++++++++++-------- 1 file changed, 188 insertions(+), 139 deletions(-) diff --git a/packages/workflow/tests/generated-observations.test.ts b/packages/workflow/tests/generated-observations.test.ts index 314714347..2e442e02e 100644 --- a/packages/workflow/tests/generated-observations.test.ts +++ b/packages/workflow/tests/generated-observations.test.ts @@ -33,8 +33,10 @@ import { import type { GeneratedEvaluationOptions } from "../src/deno/workspace/evaluate.ts"; import { recordedFiles, useRecordedFiles } from "../../core/tests/support/fragment-files.ts"; import type { RecordedFiles } from "../../core/tests/support/fragment-files.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; const ROOT_PATH = "workflows/agent.md"; +const journalCase = journalCases("packages/workflow/tests/generated-observations.test.ts"); const URL_ONE = "https://api.example.test/one"; const URL_TWO = "https://api.example.test/two"; const NOTE = "the retained note\n"; @@ -99,10 +101,11 @@ function run( events?: DurableEvent[]; files?: RecordedFiles; } = {}, + stream?: InMemoryStream, ): Operation { return scoped(function* () { yield* useWorkflowGenerated(options.generated ?? {}); - return yield* once(source, options); + return yield* once(source, options, stream); }); } @@ -117,9 +120,9 @@ function run( function once( source: string, options: { events?: DurableEvent[]; files?: RecordedFiles } = {}, + stream = new InMemoryStream(options.events ?? []), ): Operation { return scoped(function* () { - const stream = new InMemoryStream(options.events ?? []); if (options.files !== undefined) { yield* useRecordedFiles(options.files); } @@ -265,114 +268,145 @@ describe("Tier WGX — the selection a workflow run offers", () => { yield* useScope(); }); - it("WGX2: a marker-4 admission holds the selection and nothing live", function* () { - const files = recordedFiles({ "notes.md": NOTE }); - - const attempt = yield* run(evaluating(`\n`), { files }); - - expect(attempt.failure).toBe(undefined); - expect(attempt.output).toContain("the retained note"); - const policy = policyOf(admissions(attempt.events)[0]); - // The closed shape this build writes: the marker, the selected classes and - // the rows. No Workspace basis and no request inventory — what a run stands - // on and what a request may reach are both live state, and a grant compared - // against a copy of either would refuse a run for its own progress. - expect(Object.keys(policy ?? {}).sort()).toEqual(["allow", "allowed", "version"]); - expect(policy?.version).toBe(4); - expect(policy?.allow).toEqual(["read"]); - expect(policy?.allowed).toEqual([ - { - name: "Json", - form: "self-closing", - identity: "https://executable.md/components/json", - kind: "capability", - effect: "composition", - }, - { - name: "File", - form: "self-closing", - identity: "https://executable.md/components/file/read", - kind: "component-answer", - effect: "read", - }, - ]); - }); - - it("WGX3: a fragment that asks for nothing is admitted and retains its source", function* () { - const attempt = yield* run(evaluating("nothing to observe here.\n")); - - expect(attempt.failure).toBe(undefined); - expect(attempt.output).toContain("nothing to observe here."); - expect(admissions(attempt.events)).toHaveLength(1); - expect(reads(attempt.events)).toHaveLength(0); - }); + journalCase( + "WGX2: a marker-4 admission holds the selection and nothing live", + ROOT_PATH, + function* (stream) { + const files = recordedFiles({ "notes.md": NOTE }); + + const attempt = yield* run(evaluating(`\n`), { files }, stream); + + expect(attempt.failure).toBe(undefined); + expect(attempt.output).toContain("the retained note"); + const policy = policyOf(admissions(attempt.events)[0]); + // The closed shape this build writes: the marker, the selected classes and + // the rows. No Workspace basis and no request inventory — what a run stands + // on and what a request may reach are both live state, and a grant compared + // against a copy of either would refuse a run for its own progress. + expect(Object.keys(policy ?? {}).sort()).toEqual(["allow", "allowed", "version"]); + expect(policy?.version).toBe(4); + expect(policy?.allow).toEqual(["read"]); + expect(policy?.allowed).toEqual([ + { + name: "Json", + form: "self-closing", + identity: "https://executable.md/components/json", + kind: "capability", + effect: "composition", + }, + { + name: "File", + form: "self-closing", + identity: "https://executable.md/components/file/read", + kind: "component-answer", + effect: "read", + }, + ]); + }, + ); - it("WGX4: a document with no `` makes no admission at all", function* () { - // The untaken half of the previous row: offering a selection is not - // evaluating anything, so a run that never writes the element appends no - // admission and resolves nothing on its behalf. - const attempt = yield* run("The run wrote no fragment.\n"); + journalCase( + "WGX3: a fragment that asks for nothing is admitted and retains its source", + ROOT_PATH, + function* (stream) { + const attempt = yield* run(evaluating("nothing to observe here.\n"), {}, stream); - expect(attempt.failure).toBe(undefined); - expect(attempt.output).toContain("The run wrote no fragment."); - expect(admissions(attempt.events)).toHaveLength(0); - }); + expect(attempt.failure).toBe(undefined); + expect(attempt.output).toContain("nothing to observe here."); + expect(admissions(attempt.events)).toHaveLength(1); + expect(reads(attempt.events)).toHaveLength(0); + }, + ); - it("WGX5: a name this host did not offer is refused before any effect", function* () { - const files = recordedFiles({ "notes.md": NOTE }); + journalCase( + "WGX4: a document with no `` makes no admission at all", + ROOT_PATH, + function* (stream) { + // The untaken half of the previous row: offering a selection is not + // evaluating anything, so a run that never writes the element appends no + // admission and resolves nothing on its behalf. + const attempt = yield* run("The run wrote no fragment.\n", {}, stream); + + expect(attempt.failure).toBe(undefined); + expect(attempt.output).toContain("The run wrote no fragment."); + expect(admissions(attempt.events)).toHaveLength(0); + }, + ); - // `` is a core default this host did not choose. A generic workflow - // run therefore has no search at all, and the refusal lands before the read - // beside it in the same fragment. - const attempt = yield* run( - evaluating(`\n\n`), - { files }, - ); + journalCase( + "WGX5: a name this host did not offer is refused before any effect", + ROOT_PATH, + function* (stream) { + const files = recordedFiles({ "notes.md": NOTE }); + + // `` is a core default this host did not choose. A generic workflow + // run therefore has no search at all, and the refusal lands before the read + // beside it in the same fragment. + const attempt = yield* run( + evaluating(`\n\n`), + { files }, + stream, + ); - expect(attempt.failure).toContain("did not admit"); - expect(files.performed).toEqual([]); - expect(admissions(attempt.events).length).toBeLessThanOrEqual(1); - expect(reads(attempt.events)).toHaveLength(0); - }); + expect(attempt.failure).toContain("did not admit"); + expect(files.performed).toEqual([]); + expect(admissions(attempt.events).length).toBeLessThanOrEqual(1); + expect(reads(attempt.events)).toHaveLength(0); + }, + ); }); describe("Tier WGX — what an admitted request may reach is live", () => { - it("WGX6: a host that bounds no request offers `` not at all", function* () { - const transport = yield* useTransport(); + journalCase( + "WGX6: a host that bounds no request offers `` not at all", + ROOT_PATH, + function* (stream) { + const transport = yield* useTransport(); - const attempt = yield* run(evaluating(`\n`)); + const attempt = yield* run(evaluating(`\n`), {}, stream); - expect(attempt.failure).toContain("did not admit"); - expect(transport.performed).toHaveLength(0); - }); + expect(attempt.failure).toContain("did not admit"); + expect(transport.performed).toHaveLength(0); + }, + ); - it("WGX7: a bounded destination performs once and retains one observation", function* () { - const transport = yield* useTransport(); + journalCase( + "WGX7: a bounded destination performs once and retains one observation", + ROOT_PATH, + function* (stream) { + const transport = yield* useTransport(); - const attempt = yield* run( - evaluating(`\n\n`), - { generated: { requests: [{ url: URL_ONE }] } }, - ); - - expect(attempt.failure).toBe(undefined); - expect(transport.performed.map((call) => call.url)).toEqual([URL_ONE]); - expect(fetches(attempt.events)).toHaveLength(1); - }); + const attempt = yield* run( + evaluating(`\n\n`), + { generated: { requests: [{ url: URL_ONE }] } }, + stream, + ); - it("WGX8: a destination outside the bound reaches no transport", function* () { - const transport = yield* useTransport(); + expect(attempt.failure).toBe(undefined); + expect(transport.performed.map((call) => call.url)).toEqual([URL_ONE]); + expect(fetches(attempt.events)).toHaveLength(1); + }, + ); - // The name is offered — this host bounds a request — and the destination is - // not. So the refusal is the live terminal's, asked immediately before - // transport, and nothing is sent. - const attempt = yield* run( - evaluating(`\n\n`), - { generated: { requests: [{ url: URL_ONE }] } }, - ); + journalCase( + "WGX8: a destination outside the bound reaches no transport", + ROOT_PATH, + function* (stream) { + const transport = yield* useTransport(); + + // The name is offered — this host bounds a request — and the destination is + // not. So the refusal is the live terminal's, asked immediately before + // transport, and nothing is sent. + const attempt = yield* run( + evaluating(`\n\n`), + { generated: { requests: [{ url: URL_ONE }] } }, + stream, + ); - expect(attempt.failure).toContain("not permitted in this scope"); - expect(transport.performed).toHaveLength(0); - }); + expect(attempt.failure).toContain("not permitted in this scope"); + expect(transport.performed).toHaveLength(0); + }, + ); it("WGX9: a bound this host stated cannot be moved by editing what it was given", function* () { const transport = yield* useTransport(); @@ -474,55 +508,70 @@ describe("Tier WGX — what an admitted request may reach is live", () => { expect(transport.performed).toHaveLength(0); }); - it("WGX15: the request allowance is read once, and `` comes from that reading", function* () { - const server = yield* useLoopback(); - let reads = 0; - // An ordinary accessor-backed options object, which is all a host has to be - // for this to matter: the first reading states no bound and a later one - // states one. Whichever this host meant, the name a fragment may write and - // the policy deciding what it may reach have to come from one reading. - const changing: GeneratedEvaluationOptions = { - get requests() { - reads++; - return reads === 1 ? [] : [{ url: `${server.origin}/admitted` }]; - }, - }; - - const attempt = yield* run( - evaluating(`\n\n`), - { generated: changing }, - ); + journalCase( + "WGX15: the request allowance is read once, and `` comes from that reading", + ROOT_PATH, + function* (stream) { + const server = yield* useLoopback(); + let reads = 0; + // An ordinary accessor-backed options object, which is all a host has to be + // for this to matter: the first reading states no bound and a later one + // states one. Whichever this host meant, the name a fragment may write and + // the policy deciding what it may reach have to come from one reading. + const changing: GeneratedEvaluationOptions = { + get requests() { + reads++; + return reads === 1 ? [] : [{ url: `${server.origin}/admitted` }]; + }, + }; - // Asked first, because it is the consequence: the destination the fragment - // names is one no reading of this host's list ever admitted, and a - // selection taken from a second reading would send it under no policy at - // all. - expect(server.asked).toEqual([]); - // The retained reading bounded nothing, so `` was never offered: the - // fragment is refused at admission, by name, and retains no effect. - expect(attempt.failure).toContain("did not admit"); - expect(fetches(attempt.events)).toEqual([]); - // One reading for the whole setup. A second one is what would let the - // selection and the policy disagree about the same host statement. - expect(reads).toBe(1); - }); + const attempt = yield* run( + evaluating( + `\n\n`, + ), + { generated: changing }, + stream, + ); - it("WGX10: an enclosing restriction still refuses what this host bounded", function* () { - const transport = yield* useTransport(); + // Asked first, because it is the consequence: the destination the fragment + // names is one no reading of this host's list ever admitted, and a + // selection taken from a second reading would send it under no policy at + // all. + expect(server.asked).toEqual([]); + // The retained reading bounded nothing, so `` was never offered: the + // fragment is refused at admission, by name, and retains no effect. + expect(attempt.failure).toContain("did not admit"); + expect(fetches(attempt.events)).toEqual([]); + // One reading for the whole setup. A second one is what would let the + // selection and the policy disagree about the same host statement. + expect(reads).toBe(1); + }, + ); - const attempt = yield* scoped(function* () { - // Narrower than the host, installed outside it. A restriction delegates - // rather than answering `true`, so the enclosing refusal is never asked - // to delegate and the bound cannot widen it. - yield* Permissions.around({ fetch: () => false }); - return yield* run(evaluating(`\n\n`), { - generated: { requests: [{ url: URL_ONE }] }, + journalCase( + "WGX10: an enclosing restriction still refuses what this host bounded", + ROOT_PATH, + function* (stream) { + const transport = yield* useTransport(); + + const attempt = yield* scoped(function* () { + // Narrower than the host, installed outside it. A restriction delegates + // rather than answering `true`, so the enclosing refusal is never asked + // to delegate and the bound cannot widen it. + yield* Permissions.around({ fetch: () => false }); + return yield* run( + evaluating(`\n\n`), + { + generated: { requests: [{ url: URL_ONE }] }, + }, + stream, + ); }); - }); - expect(attempt.failure).toContain("not permitted in this scope"); - expect(transport.performed).toHaveLength(0); - }); + expect(attempt.failure).toContain("not permitted in this scope"); + expect(transport.performed).toHaveLength(0); + }, + ); }); describe("Tier WGX — a completed effect restores from its record", () => { From a12074a72426d897bbba602b1e094464adace76c Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:12:33 -0500 Subject: [PATCH 14/78] test: attribute fresh CLI and Testing execution journals --- packages/cli/tests/run-composition.test.ts | 37 ++-- .../testing/tests/agent-composition.test.ts | 45 +++-- packages/testing/tests/use-testing.test.ts | 164 ++++++++++-------- 3 files changed, 137 insertions(+), 109 deletions(-) diff --git a/packages/cli/tests/run-composition.test.ts b/packages/cli/tests/run-composition.test.ts index 00864c686..ace09a8a7 100644 --- a/packages/cli/tests/run-composition.test.ts +++ b/packages/cli/tests/run-composition.test.ts @@ -35,6 +35,9 @@ import { installPlugins } from "../src/plugin-host.ts"; import type { CommandPlugins } from "../src/plugin-host.ts"; import { BUNDLED_PLUGIN } from "../src/run-profile.ts"; import { DEFAULT_REPOSITORY_ROOT } from "../src/run-repositories.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/cli/tests/run-composition.test.ts"); /** Every element an author can write that needs a repository provider. */ const OPERATIONS: readonly { readonly name: string; readonly source: string }[] = [ @@ -187,21 +190,25 @@ describe("ORC1 — describing the vocabulary reaches nothing", () => { expect(yield* readdir(managed)).toEqual([]); }); - it("leaves every repository operation unprovided after inspection", function* () { - // Registering the declarations installs no provider: the Apis still answer - // with their own defaults, which is what a catalog is allowed to leave - // behind. - // Assembled rather than bootstrapped: the vocabulary belongs to the - // bundled Plugin, and installing it is what a run profile does. Installing - // it still installs no provider, which is the claim. - yield* gitProfile("run"); - const failure = yield* raisedValue( - collect(yield* execute({ ...inlineSource(``), stream: new InMemoryStream() })), - ); - // `` has no lexical Repository, so the first thing it asks for - // is the ambient one — and that is the Api reporting absence. - expect(String(failure)).toContain("no Repository composition provider is installed"); - }); + journalCase( + "leaves every repository operation unprovided after inspection", + "", + function* (stream) { + // Registering the declarations installs no provider: the Apis still answer + // with their own defaults, which is what a catalog is allowed to leave + // behind. + // Assembled rather than bootstrapped: the vocabulary belongs to the + // bundled Plugin, and installing it is what a run profile does. Installing + // it still installs no provider, which is the claim. + yield* gitProfile("run"); + const failure = yield* raisedValue( + collect(yield* execute({ ...inlineSource(``), stream })), + ); + // `` has no lexical Repository, so the first thing it asks for + // is the ambient one — and that is the Api reporting absence. + expect(String(failure)).toContain("no Repository composition provider is installed"); + }, + ); }); describe("ORC2 — one language, described everywhere and operated somewhere", () => { diff --git a/packages/testing/tests/agent-composition.test.ts b/packages/testing/tests/agent-composition.test.ts index 619824762..4fd87023f 100644 --- a/packages/testing/tests/agent-composition.test.ts +++ b/packages/testing/tests/agent-composition.test.ts @@ -7,7 +7,7 @@ */ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { ensure } from "effection"; import type { Result, Stream } from "effection"; import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; @@ -60,7 +60,8 @@ function stubStream( } describe("agent + testing composition", () => { - it("both component sets decorate one execution", function* () { + const name = "both component sets decorate one execution"; + it(name, function* () { const calls: string[] = []; yield* installTestingComponents(); yield* installAgentComponents({ @@ -114,23 +115,29 @@ describe("agent + testing composition", () => { ); // `` names durable work after its own invocation, so the host // declares it to the execution rather than registering it. - const execution = yield* executeInstalled({ path: docPath, stream: new InMemoryStream() }, [ - { components: agentIdentityComponents() }, - ]); - const subscription = yield* execution.output; - let next = yield* subscription.next(); - while (!next.done) { - next = yield* subscription.next(); - } - const result: Result = yield* execution; + yield* captureTestJournal( + { owner: "packages/testing/tests/agent-composition.test.ts", name }, + docPath, + function* (stream) { + const execution = yield* executeInstalled({ path: docPath, stream }, [ + { components: agentIdentityComponents() }, + ]); + const subscription = yield* execution.output; + let next = yield* subscription.next(); + while (!next.done) { + next = yield* subscription.next(); + } + const result: Result = yield* execution; - expect(calls).toEqual(["good", "bad"]); - expect(result.ok).toBe(false); - if (!result.ok) { - expect(result.error).toBeInstanceOf(AggregateError); - if (result.error instanceof AggregateError) { - expect(result.error.message).toBe("1 agent prompt(s) failed"); - } - } + expect(calls).toEqual(["good", "bad"]); + expect(result.ok).toBe(false); + if (!result.ok) { + expect(result.error).toBeInstanceOf(AggregateError); + if (result.error instanceof AggregateError) { + expect(result.error.message).toBe("1 agent prompt(s) failed"); + } + } + }, + ); }); }); diff --git a/packages/testing/tests/use-testing.test.ts b/packages/testing/tests/use-testing.test.ts index d8051f222..a2099053f 100644 --- a/packages/testing/tests/use-testing.test.ts +++ b/packages/testing/tests/use-testing.test.ts @@ -16,9 +16,11 @@ import type { Json } from "@executablemd/core"; import { Test, TestFailureError, testing } from "../src/test-api.ts"; import { useTesting } from "../src/use-testing.ts"; import { documentCases, failureOf, runDoc, withFreshDocument } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; const OWNER = "packages/testing/tests/use-testing.test.ts"; const documentCase = documentCases(OWNER); +const journalCase = journalCases(OWNER); function* drain( subscription: Subscription, @@ -88,29 +90,33 @@ describe("useTesting composition", () => { }); }); - it("composes around core execute and returns session results", function* () { - const outcome = yield* scoped(function* () { - yield* useStubFs({ - "README.md": '\n', + journalCase( + "composes around core execute and returns session results", + "README.md", + function* (stream) { + const outcome = yield* scoped(function* () { + yield* useStubFs({ + "README.md": '\n', + }); + const tests = yield* useTesting(); + const execution = yield* execute({ path: "README.md", stream }); + const result = yield* execution; + const results = yield* tests.results; + return { result, results }; }); - const tests = yield* useTesting(); - const execution = yield* execute({ path: "README.md", stream: new InMemoryStream() }); - const result = yield* execution; - const results = yield* tests.results; - return { result, results }; - }); - expect(outcome.result.ok).toBe(true); - expect(outcome.results.map((r) => [r.name, r.status])).toEqual([["one", "pass"]]); - expect(Object.isFrozen(outcome.results)).toBe(true); - }); + expect(outcome.result.ok).toBe(true); + expect(outcome.results.map((r) => [r.name, r.status])).toEqual([["one", "pass"]]); + expect(Object.isFrozen(outcome.results)).toBe(true); + }, + ); - it("keeps results available after a testing failure", function* () { + journalCase("keeps results available after a testing failure", "README.md", function* (stream) { const outcome = yield* scoped(function* () { yield* useStubFs({ "README.md": '\n', }); const tests = yield* useTesting(); - const execution = yield* execute({ path: "README.md", stream: new InMemoryStream() }); + const execution = yield* execute({ path: "README.md", stream }); const result = yield* execution; const results = yield* tests.results; return { result, results }; @@ -265,69 +271,77 @@ describe("useTesting composition", () => { expect(thrown?.message).toBe("pre-handle setup exploded"); }); - it("a late subscriber still receives all chunks and the close value", function* () { - const { late, value } = yield* scoped(function* () { - yield* useStubFs({ "README.md": "hello world\n" }); - yield* useTesting(); - const execution = yield* execute({ - path: "README.md", - stream: new InMemoryStream(), - }); - const result = yield* execution; - const drained = yield* scoped(function* () { - return yield* drain(yield* execution.output); + journalCase( + "a late subscriber still receives all chunks and the close value", + "README.md", + function* (stream) { + const { late, value } = yield* scoped(function* () { + yield* useStubFs({ "README.md": "hello world\n" }); + yield* useTesting(); + const execution = yield* execute({ + path: "README.md", + stream, + }); + const result = yield* execution; + const drained = yield* scoped(function* () { + return yield* drain(yield* execution.output); + }); + return { late: drained, value: result }; }); - return { late: drained, value: result }; - }); - // No tests in the doc — the session rejects, but output is intact. - expect(value.ok).toBe(false); - expect(late.close).toContain("hello world"); - expect(late.chunks.join("")).toContain("hello world"); - }); + // No tests in the doc — the session rejects, but output is intact. + expect(value.ok).toBe(false); + expect(late.close).toContain("hello world"); + expect(late.chunks.join("")).toContain("hello world"); + }, + ); - it("an early caller-scope halt tears down the document and leased eval scope", function* () { - Reflect.deleteProperty(globalThis, "__useTestingHaltMarker"); - yield* API.Process.around({ - *exec(_args, _next) { - yield* sleep(10_000); - return { exitCode: 0, stdout: "", stderr: "" }; - }, - }); - const doc = [ - "", - '', - "```js persist eval", - "globalThis.__useTestingHaltMarker = true;", - "yield* spawn(function* () { try { yield* suspend(); } finally { globalThis.__useTestingHaltMarker = false; } });", - "```", - "```bash exec", - "sleep 600", - "```", - "", - "", - "", - ].join("\n"); - yield* useStubFs({ "README.md": doc }); + journalCase( + "an early caller-scope halt tears down the document and leased eval scope", + "README.md", + function* (stream) { + Reflect.deleteProperty(globalThis, "__useTestingHaltMarker"); + yield* API.Process.around({ + *exec(_args, _next) { + yield* sleep(10_000); + return { exitCode: 0, stdout: "", stderr: "" }; + }, + }); + const doc = [ + "", + '', + "```js persist eval", + "globalThis.__useTestingHaltMarker = true;", + "yield* spawn(function* () { try { yield* suspend(); } finally { globalThis.__useTestingHaltMarker = false; } });", + "```", + "```bash exec", + "sleep 600", + "```", + "", + "", + "", + ].join("\n"); + yield* useStubFs({ "README.md": doc }); - yield* scoped(function* () { - yield* useTesting(); - const execution = yield* execute({ path: "README.md", stream: new InMemoryStream() }); - yield* spawn(function* () { - yield* scoped(function* () { - yield* drain(yield* execution.output); + yield* scoped(function* () { + yield* useTesting(); + const execution = yield* execute({ path: "README.md", stream }); + yield* spawn(function* () { + yield* scoped(function* () { + yield* drain(yield* execution.output); + }); }); + // Converge on the document having run the eval block and spawned its + // effect, then leave the scope — halting everything mid-test. A fixed + // sleep races variable startup cost (#335). + yield* when( + function* () { + return Reflect.get(globalThis, "__useTestingHaltMarker") === true; + }, + { timeout: 10_000 }, + ); }); - // Converge on the document having run the eval block and spawned its - // effect, then leave the scope — halting everything mid-test. A fixed - // sleep races variable startup cost (#335). - yield* when( - function* () { - return Reflect.get(globalThis, "__useTestingHaltMarker") === true; - }, - { timeout: 10_000 }, - ); - }); - expect(Reflect.get(globalThis, "__useTestingHaltMarker")).toBe(false); - }); + expect(Reflect.get(globalThis, "__useTestingHaltMarker")).toBe(false); + }, + ); }); From 5003c32e62ef8c2e14c08dab0ea2c4becc3b886b Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:15:26 -0500 Subject: [PATCH 15/78] test: attribute fresh Git issue scenario journals --- packages/git/tests/issue-markdown.test.ts | 25 +++++++++++++++++--- packages/git/tests/support/issue-scenario.ts | 15 ++++++------ 2 files changed, 30 insertions(+), 10 deletions(-) diff --git a/packages/git/tests/issue-markdown.test.ts b/packages/git/tests/issue-markdown.test.ts index 1a8e17db9..41ee6ce19 100644 --- a/packages/git/tests/issue-markdown.test.ts +++ b/packages/git/tests/issue-markdown.test.ts @@ -20,6 +20,7 @@ import type { Operation } from "effection"; import { SOURCE_POSITION_FIELD } from "@executablemd/core"; import { issueYields, runScenario, useScenarioFixture } from "./support/issue-scenario.ts"; import type { ScenarioObservation } from "./support/issue-scenario.ts"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; /** The scenarios, in the order a reader meets them. */ const SCENARIOS = [ @@ -59,9 +60,27 @@ function* stated(observation: ScenarioObservation): Operation { for (const name of SCENARIOS) { - it(`${name} states a contract that holds`, function* () { - yield* stated(yield* runScenario(pathOf(name))); - }); + const title = `${name} states a contract that holds`; + const path = pathOf(name); + if (name === "IssueRead.test.md" || name === "IssueUpsert.test.md") { + it(title, () => + captureTestJournal( + { + owner: "packages/git/tests/issue-markdown.test.ts", + suite: "workflow Issue scenarios", + name: title, + }, + path, + function* (stream) { + yield* stated(yield* runScenario(path, stream)); + }, + ), + ); + } else { + it(title, function* () { + yield* stated(yield* runScenario(path)); + }); + } } it("IssueDurability.test.md states a contract that holds", function* () { diff --git a/packages/git/tests/support/issue-scenario.ts b/packages/git/tests/support/issue-scenario.ts index 849bbe11d..2e739d037 100644 --- a/packages/git/tests/support/issue-scenario.ts +++ b/packages/git/tests/support/issue-scenario.ts @@ -149,7 +149,7 @@ export interface ScenarioFixture { * staged attempt anyway. What it asks about the scenario's journal it asks * through ``. */ - observe(path: string): Operation; + observe(path: string, stream?: DurableStream): Operation; } export function* useScenarioFixture(): Operation { @@ -179,8 +179,9 @@ export function* useScenarioFixture(): Operation { journal(): DurableEvent[] { return held.snapshot(RUN.runId); }, - observe(path: string): Operation { - return observeDocument(path, held, `observing:${basename(path)}`); + observe(path, stream): Operation { + const runId = `observing:${basename(path)}`; + return observeDocument(path, stream ?? held.for(runId), runId); }, }; } @@ -197,12 +198,12 @@ export function* useScenarioFixture(): Operation { */ function observeDocument( path: string, - held: Journals, + stream: DurableStream, runId: string, ): Operation { return scoped(function* () { const tests = yield* useTesting(); - const execution = yield* executeInstalled({ path, stream: held.for(runId) }, [ + const execution = yield* executeInstalled({ path, stream }, [ retainedWorkflowInstallation({ ...RUN, runId }), ]); // Drained to its close value first: output closes with the rendered text — @@ -957,9 +958,9 @@ function stageAttempt( * left. A scenario that does stage attempts acquires the fixture itself, so it * can stage them between acquiring it and observing the document. */ -export function runScenario(path: string): Operation { +export function runScenario(path: string, stream?: DurableStream): Operation { return scoped(function* () { const fixture = yield* useScenarioFixture(); - return yield* fixture.observe(path); + return yield* fixture.observe(path, stream); }); } From 81ef099b4b3c2936ae38bcb9b48146f737fa4dc9 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:30:24 -0500 Subject: [PATCH 16/78] test: retain separate CLI assembly journals for parent failures --- packages/cli/tests/agent-adapters.test.ts | 174 +++++++++++++++--- .../cli/tests/fixtures/agent-assemblies.ts | 20 +- .../cli/tests/support/assembly-profiles.ts | 2 + .../git/tests/run-composition-managed.test.ts | 48 ++--- .../tests/support/run-composition-child.ts | 18 +- packages/test-support/subprocess-journal.ts | 69 +++++++ .../tests/subprocess-journal.test.ts | 27 +++ 7 files changed, 279 insertions(+), 79 deletions(-) create mode 100644 packages/cli/tests/support/assembly-profiles.ts create mode 100644 packages/test-support/subprocess-journal.ts create mode 100644 packages/test-support/tests/subprocess-journal.test.ts diff --git a/packages/cli/tests/agent-adapters.test.ts b/packages/cli/tests/agent-adapters.test.ts index ab4267277..7c2aa08eb 100644 --- a/packages/cli/tests/agent-adapters.test.ts +++ b/packages/cli/tests/agent-adapters.test.ts @@ -19,14 +19,15 @@ import { fileURLToPath } from "node:url"; import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { exists, rm, writeTextFile } from "@effectionx/fs"; +import { exists, readdir, readTextFile, rm, writeTextFile } from "@effectionx/fs"; +import { useTempDirectory } from "@executablemd/test-support/temp"; import { randomUUID } from "node:crypto"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { API, exec, useQuietProcessOutput } from "@executablemd/runtime"; import { createEmbeddedAdapters } from "@executablemd/acp/embedded-adapters"; import type { EmbeddedAdapters } from "@executablemd/acp/embedded-adapters"; -import { useScope, scoped, ensure, until } from "effection"; +import { useScope, scoped, ensure, lift, until } from "effection"; import type { Operation } from "effection"; import { @@ -39,6 +40,12 @@ import { planWriterDependencies } from "../src/plan-writer-profile.ts"; import type { PlanWriterProviderInputs } from "../src/plan-writer-profile.ts"; import { runPlan } from "../src/plan.ts"; import { AGENT, createPlanHarness, useWorkingDirectory } from "./support/plan-harness.ts"; +import { ASSEMBLY_PROFILES, ASSEMBLY_SOURCE } from "./support/assembly-profiles.ts"; +import { + checkSubprocessJournals, + parseSubprocessJournal, +} from "../../test-support/subprocess-journal.ts"; +import type { SubprocessJournal } from "../../test-support/subprocess-journal.ts"; /** The two agents this build carries a patched snapshot for. */ const EMBEDDED = ["codex", "claude"] as const; @@ -250,7 +257,30 @@ describe("Tier AE — embedded adapters on the run and plan paths", () => { }); }); -function* assemblyInputs(agent: "claude" | "codex"): Operation { +const ASSEMBLY_OWNER = "packages/cli/tests/agent-adapters.test.ts"; +const ASSEMBLY_SUITE = "HC host selection across command assemblies"; + +function checkEnvironment(environmentPreserved: unknown): void { + expect(environmentPreserved).toBe(true); +} + +function assemblyJournals(value: unknown): SubprocessJournal[] { + if (!Array.isArray(value) || value.length !== ASSEMBLY_PROFILES.length) { + return []; + } + const journals = value.map((entry) => ({ + source: ASSEMBLY_SOURCE, + events: parseSubprocessJournal(entry), + })); + return journals.every(({ events }) => events.length > 0) ? journals : []; +} + +function* assemblyInputs( + agent: "claude" | "codex", + name: string, + verify = checkEnvironment, + inspect?: (journals: readonly SubprocessJournal[]) => void, +): Operation { const root = yield* until(realpath(yield* until(mkdtemp(join(tmpdir(), "xmd assemblies "))))); yield* ensure(() => rm(root, { recursive: true, force: true })); const host = join(root, agent); @@ -265,6 +295,7 @@ function* assemblyInputs(agent: "claude" | "codex"): Operation { fileURLToPath(new URL("./fixtures/agent-assemblies.ts", import.meta.url)), root, agent, + "--capture-journal", ], env: { [variable]: host }, }); @@ -272,32 +303,119 @@ function* assemblyInputs(agent: "claude" | "codex"): Operation { if (result.exitCode !== 0) { throw new Error(result.stderr); } - const { results: rows, environmentPreserved } = JSON.parse(result.stdout); - expect(environmentPreserved).toBe(true); - expect(rows.map((row: { profile: string }) => row.profile)).toEqual([ - "run", - "plan", - "repl", - "custom", - "other", - ]); - for (const row of rows) { - expect(row.inputs).toHaveLength(2); - for (const input of row.inputs) { - if (["custom", "other"].includes(row.profile)) { - expect(input.environment).toBeUndefined(); - } else { - expect(input.environment).toEqual({ [variable]: host }); - expect(input.command).toContain(root); - expect(input.command).not.toContain("npx"); - } - } + let output; + try { + output = JSON.parse(result.stdout); + } catch { + throw new Error("the assembly fixture result is invalid JSON"); } + const { results: rows, environmentPreserved, journals: rawJournals } = output; + const journals = assemblyJournals(rawJournals); + inspect?.(journals); + yield* checkSubprocessJournals( + { owner: ASSEMBLY_OWNER, suite: ASSEMBLY_SUITE, name }, + journals, + lift(() => { + verify(environmentPreserved); + expect(rows.map((row: { profile: string }) => row.profile)).toEqual(ASSEMBLY_PROFILES); + for (const row of rows) { + expect(row.inputs).toHaveLength(2); + for (const input of row.inputs) { + if (["custom", "other"].includes(row.profile)) { + expect(input.environment).toBeUndefined(); + } else { + expect(input.environment).toEqual({ [variable]: host }); + expect(input.command).toContain(root); + expect(input.command).not.toContain("npx"); + } + } + } + }), + ); } -describe("HC host selection across command assemblies", () => { - it("HC3/HC4: run, Plan and REPL deliver the host selection to probe and live runtimes", () => - assemblyInputs("claude")); - it("H3: run, Plan and REPL deliver the host Codex selection to probe and live runtimes", () => - assemblyInputs("codex")); +describe(ASSEMBLY_SUITE, () => { + const claude = + "HC3/HC4: run, Plan and REPL deliver the host selection to probe and live runtimes"; + const codex = + "H3: run, Plan and REPL deliver the host Codex selection to probe and live runtimes"; + it(claude, () => assemblyInputs("claude", claude)); + it(codex, () => assemblyInputs("codex", codex)); + + const witness = "attributes each assembly profile when the joined parent assertion fails"; + it(witness, function* () { + const root = yield* useTempDirectory("xmd-assembly-journals-"); + function run( + artifacts: string, + verify: typeof checkEnvironment, + inspect?: Parameters[3], + ) { + return scoped(function* () { + yield* API.Env.around({ + *env([name], next) { + return name === "XMD_TEST_ARTIFACTS" ? artifacts : yield* next(name); + }, + }); + yield* assemblyInputs("claude", witness, verify, inspect); + }); + } + + const passed = join(root, "passed", ".xmd", "test-artifacts"); + yield* run(passed, checkEnvironment, (journals) => { + expect(journals).toHaveLength(ASSEMBLY_PROFILES.length); + }); + expect(yield* exists(passed)).toBe(false); + + const failed = join(root, "failed", ".xmd", "test-artifacts"); + let assertion: unknown; + let caught: unknown; + let received: readonly SubprocessJournal[] = []; + try { + yield* run( + failed, + (value) => { + checkEnvironment(value); + try { + checkEnvironment(false); + } catch (error) { + assertion = error; + throw error; + } + }, + (journals) => { + received = journals; + }, + ); + } catch (error) { + caught = error; + } + expect(assertion).toBeInstanceOf(Error); + expect(caught).toBe(assertion); + expect(received).toHaveLength(ASSEMBLY_PROFILES.length); + const invocations = yield* readdir(failed); + expect(invocations).toHaveLength(1); + const directory = join(failed, invocations[0]); + const expectedFiles = ASSEMBLY_PROFILES.flatMap((_, index) => [ + `child-${index + 1}.case.json`, + `child-${index + 1}.jsonl`, + ]); + expect((yield* readdir(directory)).sort()).toEqual(expectedFiles.sort()); + for (const [index, journal] of received.entries()) { + const ordinal = index + 1; + const stem = join(directory, `child-${ordinal}`); + expect(JSON.parse(yield* readTextFile(`${stem}.case.json`))).toEqual({ + owner: ASSEMBLY_OWNER, + suite: ASSEMBLY_SUITE, + name: witness, + kind: "child", + ordinal, + source: ASSEMBLY_SOURCE, + }); + const events = parseSubprocessJournal( + (yield* readTextFile(`${stem}.jsonl`)).trimEnd().split("\n"), + ); + expect(events).toEqual(journal.events); + expect(events.at(-1)).toMatchObject({ type: "close", coroutineId: "root" }); + } + }); }); diff --git a/packages/cli/tests/fixtures/agent-assemblies.ts b/packages/cli/tests/fixtures/agent-assemblies.ts index 0d8bdeee8..23b8d8981 100644 --- a/packages/cli/tests/fixtures/agent-assemblies.ts +++ b/packages/cli/tests/fixtures/agent-assemblies.ts @@ -1,4 +1,4 @@ -import { InMemoryStream } from "@executablemd/durable-streams"; +import { InMemoryStream, serializeDurableEvent } from "@executablemd/durable-streams"; import { rm } from "@effectionx/fs"; import { main, scoped, useScope } from "effection"; import { useHostFiles } from "@executablemd/runtime"; @@ -14,8 +14,12 @@ import { planWriterDependencies } from "../../src/plan-writer-profile.ts"; import { assembleReplProfile } from "../../src/repl-profile.ts"; import { NO_PLUGINS } from "../../src/plugin-host.ts"; import { createFakeAcp, makeStore, makeRegistry } from "../support/fake-acp.ts"; +import { boundedJournalResult } from "../../../test-support/subprocess-journal.ts"; +import { ASSEMBLY_PROFILES, ASSEMBLY_SOURCE } from "../support/assembly-profiles.ts"; + const root = process.argv[2]!; const agent = process.argv[3] === "codex" ? "codex" : "claude"; +const capture = process.argv[4] === "--capture-journal"; const variable = agent === "codex" ? "CODEX_PATH" : "CLAUDE_CODE_EXECUTABLE"; const environment = { ...process.env }; main(function* () { @@ -35,9 +39,11 @@ main(function* () { command: ReturnType; }[]; }[] = []; - for (const profile of ["run", "plan", "repl", "custom", "other"]) { + const journals: string[][] = []; + for (const profile of ASSEMBLY_PROFILES) { const fake = createFakeAcp(); fake.script({ reply: "assembled" }); + const stream = new InMemoryStream(); yield* scoped(function* () { const host = yield* useScope(); if (profile === "custom") { @@ -70,8 +76,8 @@ main(function* () { yield* collect( yield* executeInstalled( { - ...retainedSource("assembly.md", "assembly"), - stream: new InMemoryStream(), + ...retainedSource(ASSEMBLY_SOURCE, "assembly"), + stream, }, [], ), @@ -84,9 +90,13 @@ main(function* () { })), }); }); + if (capture) { + journals.push((yield* stream.readAll()).map(serializeDurableEvent)); + } } const environmentPreserved = [ ...new Set([...Object.keys(environment), ...Object.keys(process.env)]), ].every((key) => environment[key] === process.env[key]); - console.log(JSON.stringify({ results, environmentPreserved })); + const result = { results, environmentPreserved }; + console.log(capture ? boundedJournalResult(result, { journals }) : JSON.stringify(result)); }); diff --git a/packages/cli/tests/support/assembly-profiles.ts b/packages/cli/tests/support/assembly-profiles.ts new file mode 100644 index 000000000..7a73b967b --- /dev/null +++ b/packages/cli/tests/support/assembly-profiles.ts @@ -0,0 +1,2 @@ +export const ASSEMBLY_PROFILES = ["run", "plan", "repl", "custom", "other"] as const; +export const ASSEMBLY_SOURCE = "assembly.md"; diff --git a/packages/git/tests/run-composition-managed.test.ts b/packages/git/tests/run-composition-managed.test.ts index ff03522da..45ee71651 100644 --- a/packages/git/tests/run-composition-managed.test.ts +++ b/packages/git/tests/run-composition-managed.test.ts @@ -17,11 +17,12 @@ import { expect } from "@executablemd/test-support/expect"; import { scoped, type Operation } from "effection"; import { exists, readdir, readTextFile, rm, writeTextFile } from "@effectionx/fs"; import { API } from "@executablemd/runtime"; -import { parseDurableEvent } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; import { useTempDirectory } from "@executablemd/test-support/temp"; -import { withFailureJournal } from "@executablemd/testing"; -import { useTestDiagnostics } from "../../cli/src/test-diagnostics.ts"; +import { + checkSubprocessJournals, + parseSubprocessJournal, +} from "../../test-support/subprocess-journal.ts"; import { join } from "node:path"; import { git, useBareRemote } from "./support/git-remotes.ts"; import { spawnSync } from "node:child_process"; @@ -538,24 +539,6 @@ describe("ORC11 — an interrupted creation", () => { const ORC12_SUITE = "ORC12 — exclusive ownership across processes"; const OWNER = "packages/git/tests/run-composition-managed.test.ts"; -function parseJournal(value: unknown): DurableEvent[] { - if (!Array.isArray(value)) { - return []; - } - const events: DurableEvent[] = []; - for (const record of value) { - if (typeof record !== "string") { - return []; - } - const parsed = parseDurableEvent(record); - if (!parsed.ok) { - return []; - } - events.push(parsed.value); - } - return events; -} - describe(ORC12_SUITE, () => { /** One second process, run to completion, and what it reported. */ function* elsewhere( @@ -604,7 +587,7 @@ describe(ORC12_SUITE, () => { reason: "reason" in result && typeof result.reason === "string" ? result.reason : undefined, message: "message" in result && typeof result.message === "string" ? result.message : undefined, - events: capture && "journal" in result ? parseJournal(result.journal) : [], + events: capture && "journal" in result ? parseSubprocessJournal(result.journal) : [], }; } @@ -702,19 +685,12 @@ describe(ORC12_SUITE, () => { }, }); } - const diagnostics = yield* useTestDiagnostics(process.stderr, { - owner: OWNER, - suite: ORC12_SUITE, - name, - }); - yield* withFailureJournal( - diagnostics.execution("child", "").journal(() => false), - function* (buffer) { - // The real second process takes the same checkout. Its result is available after exit. - const later = yield* elsewhere(root, checkout.root, document, true); - for (const event of later.events) { - yield* buffer.append(event); - } + // The real second process takes the same checkout. Its result is available after exit. + const later = yield* elsewhere(root, checkout.root, document, true); + yield* checkSubprocessJournals( + { owner: OWNER, suite: ORC12_SUITE, name }, + [{ source: "", events: later.events }], + function* () { expect(later.kind).toBe("selected"); expect(later.bound).toBe(slot.checkout); yield* check(slot, later.events); @@ -769,7 +745,7 @@ describe(ORC12_SUITE, () => { source: "", }); const lines = (yield* readTextFile(join(directory, "child-1.jsonl"))).trimEnd().split("\n"); - const events = parseJournal(lines); + const events = parseSubprocessJournal(lines); expect(events).toEqual(received); expect(events.at(-1)).toMatchObject({ type: "close", coroutineId: "root" }); }); diff --git a/packages/git/tests/support/run-composition-child.ts b/packages/git/tests/support/run-composition-child.ts index 5cb9e57e5..26c5e6ee6 100644 --- a/packages/git/tests/support/run-composition-child.ts +++ b/packages/git/tests/support/run-composition-child.ts @@ -13,13 +13,13 @@ import { main } from "effection"; import process from "node:process"; -import { Buffer } from "node:buffer"; import { InMemoryStream, serializeDurableEvent } from "@executablemd/durable-streams"; import { collect, execute, inlineSource } from "@executablemd/core"; import { API, useHostFiles } from "@executablemd/runtime"; import { useCompositionComponents } from "../../src/composition/installation.ts"; import { useRunComposition } from "../../src/deno/run-composition/provider.ts"; import { ManagedCheckoutError } from "../../src/deno/run-composition/errors.ts"; +import { boundedJournalResult } from "../../../test-support/subprocess-journal.ts"; /** What the parent reads back off this process's stdout. */ export interface ChildOutcome { @@ -65,15 +65,13 @@ await main(function* () { : { kind: "refused", reason: refusal.reason, message: refusal.message }; } - let line = `${JSON.stringify(outcome)}\n`; - if (capture === "--capture-journal") { - const journal = (yield* stream.readAll()).map(serializeDurableEvent); - const enriched = `${JSON.stringify({ ...outcome, journal })}\n`; - if (Buffer.byteLength(enriched) <= 64 * 1024) { - line = enriched; - } - } - process.stdout.write(line); + const line = + capture === "--capture-journal" + ? boundedJournalResult(outcome, { + journal: (yield* stream.readAll()).map(serializeDurableEvent), + }) + : JSON.stringify(outcome); + process.stdout.write(`${line}\n`); }); /** The managed-checkout refusal in this error's chain, if there is one. */ diff --git a/packages/test-support/subprocess-journal.ts b/packages/test-support/subprocess-journal.ts new file mode 100644 index 000000000..6a0319b15 --- /dev/null +++ b/packages/test-support/subprocess-journal.ts @@ -0,0 +1,69 @@ +import { Buffer } from "node:buffer"; +import process from "node:process"; +import { scoped } from "effection"; +import type { Operation } from "effection"; +import { parseDurableEvent } from "@executablemd/durable-streams"; +import type { DurableEvent } from "@executablemd/durable-streams"; +import { withFailureJournal } from "@executablemd/testing"; +import { useTestDiagnostics } from "../cli/src/test-diagnostics.ts"; +import type { JournalCase } from "../cli/src/test-diagnostics.ts"; + +const MAX_ENVELOPE_BYTES = 64 * 1024; + +export function boundedJournalResult(result: object, evidence: object): string { + const enriched = JSON.stringify({ ...result, ...evidence }); + return Buffer.byteLength(enriched) + 1 <= MAX_ENVELOPE_BYTES ? enriched : JSON.stringify(result); +} + +export function parseSubprocessJournal(value: unknown): DurableEvent[] { + if (!Array.isArray(value) || Buffer.byteLength(JSON.stringify(value)) > MAX_ENVELOPE_BYTES) { + return []; + } + const events: DurableEvent[] = []; + for (const record of value) { + if (typeof record !== "string") { + return []; + } + const parsed = parseDurableEvent(record); + if (!parsed.ok) { + return []; + } + events.push(parsed.value); + } + return events; +} + +export interface SubprocessJournal { + readonly source: string; + readonly events: readonly DurableEvent[]; +} + +/** Hold settled records from a joined synthetic child through its parent's assertions. */ +export function checkSubprocessJournals( + testCase: JournalCase, + journals: readonly SubprocessJournal[], + check: () => Operation, +): Operation { + if (journals.length === 0) { + return check(); + } + return scoped(function* () { + const diagnostics = yield* useTestDiagnostics(process.stderr, testCase); + const captures = journals.map((journal) => ({ + events: journal.events, + host: diagnostics.execution("child", journal.source).journal(() => false), + })); + const run = captures.reduceRight<() => Operation>( + (next, { events, host }) => + () => + withFailureJournal(host, function* (buffer) { + for (const event of events) { + yield* buffer.append(event); + } + return yield* next(); + }), + check, + ); + return yield* run(); + }); +} diff --git a/packages/test-support/tests/subprocess-journal.test.ts b/packages/test-support/tests/subprocess-journal.test.ts new file mode 100644 index 000000000..bc10c466a --- /dev/null +++ b/packages/test-support/tests/subprocess-journal.test.ts @@ -0,0 +1,27 @@ +import { describe, it } from "../bdd.ts"; +import { expect } from "../expect.ts"; +import { serializeDurableEvent } from "@executablemd/durable-streams"; +import type { DurableEvent } from "@executablemd/durable-streams"; +import { boundedJournalResult, parseSubprocessJournal } from "../subprocess-journal.ts"; + +describe("private subprocess journal envelope", () => { + // deno-lint-ignore require-yield + it("keeps the ordinary result when the UTF-8 envelope exceeds its limit", function* () { + const result = { kind: "selected" }; + expect(JSON.parse(boundedJournalResult(result, { journal: ["é".repeat(32 * 1024)] }))).toEqual( + result, + ); + }); + + // deno-lint-ignore require-yield + it("rejects a partially valid snapshot", function* () { + const event: DurableEvent = { + type: "close", + coroutineId: "root", + result: { status: "ok", value: null }, + }; + const line = serializeDurableEvent(event); + expect(parseSubprocessJournal([line])).toEqual([event]); + expect(parseSubprocessJournal([line, "malformed"])).toEqual([]); + }); +}); From 88cc32c9aa847f399fa7288cfe025fdcc880a5ea Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:32:46 -0500 Subject: [PATCH 17/78] test: attribute guarded CLI host and upgrade journals --- packages/cli/tests/prompt-usage-hosts.test.ts | 143 +++++++------ packages/cli/tests/upgrade-output.test.ts | 191 ++++++++++-------- 2 files changed, 188 insertions(+), 146 deletions(-) diff --git a/packages/cli/tests/prompt-usage-hosts.test.ts b/packages/cli/tests/prompt-usage-hosts.test.ts index 72f239071..b96844d62 100644 --- a/packages/cli/tests/prompt-usage-hosts.test.ts +++ b/packages/cli/tests/prompt-usage-hosts.test.ts @@ -44,6 +44,11 @@ import { records, useHarness } from "./fixtures/repl/issue-883/sidekick-harness. import { parseDurableEvent } from "@executablemd/durable-streams"; import { sleep } from "effection"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/cli/tests/prompt-usage-hosts.test.ts"); +const PROMPT_SOURCE = "hosts.md"; + const HOST: PromptUsageHost = { host: "deno-source", xmd: { version: "0.0.0-hosts" } }; const RETAINED = { @@ -110,7 +115,7 @@ function usageIn(events: readonly DurableEvent[]): (PromptUsage | undefined)[] { function* promptOnce(stream: DurableStream): Operation { yield* collect( yield* executeInstalled( - { ...retainedSource("hosts.md", "measure me"), stream }, + { ...retainedSource(PROMPT_SOURCE, "measure me"), stream }, [{ components: agentIdentityComponents() }], ), ); @@ -132,55 +137,64 @@ function expectRetained(usage: PromptUsage | undefined, adapterVersion: string): } describe("Tier HU — Prompt usage through the host assemblies", () => { - it("HU1: an ordinary run's agent stack retains usage in the run's own history", function* () { - yield* useHostFiles(); - const root = yield* useRoot(); - const fake = createFakeAcp(); - fake.script({ reply: "ok", usage: RETAINED }); - const stream = new InMemoryStream(); - yield* scoped(function* () { - const stack = stackAt(root); - yield* installAgentProviderStack(stack, leaf(stack, fake)); - yield* promptOnce(stream); - }); - const [usage] = usageIn(yield* stream.readAll()); - expectRetained(usage, "0.70.0"); - }); + journalCase( + "HU1: an ordinary run's agent stack retains usage in the run's own history", + PROMPT_SOURCE, + function* (stream) { + yield* useHostFiles(); + const root = yield* useRoot(); + const fake = createFakeAcp(); + fake.script({ reply: "ok", usage: RETAINED }); + yield* scoped(function* () { + const stack = stackAt(root); + yield* installAgentProviderStack(stack, leaf(stack, fake)); + yield* promptOnce(stream); + }); + const [usage] = usageIn(yield* stream.readAll()); + expectRetained(usage, "0.70.0"); + }, + ); - it("HU2: the Plan writer's dependencies retain usage the same way", function* () { - yield* useHostFiles(); - const root = yield* useRoot(); - const fake = createFakeAcp(); - fake.script({ reply: "ok", usage: RETAINED }); - const stream = new InMemoryStream(); - yield* scoped(function* () { - const stack = stackAt(root); - const host = yield* useScope(); - yield* installAgentProviderStack( - stack, - planWriterDependencies({ stack, acp: leaf(stack, fake) }, root, host), - ); - yield* promptOnce(stream); - }); - expectRetained(usageIn(yield* stream.readAll())[0], "0.70.0"); - }); + journalCase( + "HU2: the Plan writer's dependencies retain usage the same way", + PROMPT_SOURCE, + function* (stream) { + yield* useHostFiles(); + const root = yield* useRoot(); + const fake = createFakeAcp(); + fake.script({ reply: "ok", usage: RETAINED }); + yield* scoped(function* () { + const stack = stackAt(root); + const host = yield* useScope(); + yield* installAgentProviderStack( + stack, + planWriterDependencies({ stack, acp: leaf(stack, fake) }, root, host), + ); + yield* promptOnce(stream); + }); + expectRetained(usageIn(yield* stream.readAll())[0], "0.70.0"); + }, + ); - it("HU3: the REPL profile, through its headless wrapper, retains usage", function* () { - yield* useHostFiles(); - const root = yield* useRoot(); - const fake = createFakeAcp(); - fake.script({ reply: "ok", usage: RETAINED }); - const stream = new InMemoryStream(); - yield* scoped(function* () { - const stack = stackAt(root); - yield* assembleReplProfile(stack, NO_PLUGINS, { - acp: leaf(stack, fake), - planWriterRoot: join(root, "plans"), + journalCase( + "HU3: the REPL profile, through its headless wrapper, retains usage", + PROMPT_SOURCE, + function* (stream) { + yield* useHostFiles(); + const root = yield* useRoot(); + const fake = createFakeAcp(); + fake.script({ reply: "ok", usage: RETAINED }); + yield* scoped(function* () { + const stack = stackAt(root); + yield* assembleReplProfile(stack, NO_PLUGINS, { + acp: leaf(stack, fake), + planWriterRoot: join(root, "plans"), + }); + yield* promptOnce(stream); }); - yield* promptOnce(stream); - }); - expectRetained(usageIn(yield* stream.readAll())[0], "0.70.0"); - }); + expectRetained(usageIn(yield* stream.readAll())[0], "0.70.0"); + }, + ); it("HU4: the Sidekick's held conversation retains usage through its own assembly", function* () { yield* useHostFiles(); @@ -250,22 +264,25 @@ describe("Tier HU — Prompt usage through the host assemblies", () => { }); }); - it("HU6: a host that states no usage facts collects none, and runs the same turn", function* () { - yield* useHostFiles(); - const root = yield* useRoot(); - const fake = createFakeAcp(); - fake.script({ reply: "ok", usage: RETAINED }); - const stream = new InMemoryStream(); - yield* scoped(function* () { - const stack: AgentStack = { - ...stackAt(root), - sessions: { advertiseNativeLaunch: [], advertiseClientNativeAttachment: [] }, - }; - yield* installAgentProviderStack(stack, leaf(stack, fake)); - yield* promptOnce(stream); - }); - expect(usageIn(yield* stream.readAll())).toEqual([undefined]); - }); + journalCase( + "HU6: a host that states no usage facts collects none, and runs the same turn", + PROMPT_SOURCE, + function* (stream) { + yield* useHostFiles(); + const root = yield* useRoot(); + const fake = createFakeAcp(); + fake.script({ reply: "ok", usage: RETAINED }); + yield* scoped(function* () { + const stack: AgentStack = { + ...stackAt(root), + sessions: { advertiseNativeLaunch: [], advertiseClientNativeAttachment: [] }, + }; + yield* installAgentProviderStack(stack, leaf(stack, fake)); + yield* promptOnce(stream); + }); + expect(usageIn(yield* stream.readAll())).toEqual([undefined]); + }, + ); it("HU7: a REPL entry retains usage through the entry publisher, and the Sidekick through its owner", function* () { yield* useHostFiles(); diff --git a/packages/cli/tests/upgrade-output.test.ts b/packages/cli/tests/upgrade-output.test.ts index 7604375e0..6268f1be1 100644 --- a/packages/cli/tests/upgrade-output.test.ts +++ b/packages/cli/tests/upgrade-output.test.ts @@ -31,9 +31,15 @@ import { UPGRADE_REPLACE_RETURNS, UPGRADE_VERIFY_RETURNS, } from "../src/compiled-upgrade.ts"; -import { runUpgrade } from "../src/upgrade.ts"; +import { runUpgrade, UPGRADE_COMMAND_IDENTITY } from "../src/upgrade.ts"; import type { UpgradeAssembly, UpgradeConsumer } from "../src/upgrade.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; + +const OWNER = "packages/cli/tests/upgrade-output.test.ts"; +const journalCase = journalCases(OWNER); + const INSTALLED = "0.10.2"; const RELEASE = "v0.11.0"; const EXECUTABLE = "/usr/local/bin/xmd"; @@ -147,7 +153,7 @@ function assemblyFor(phases: Phases): UpgradeAssembly { }; } -function install(consume: UpgradeConsumer, phases: Phases = {}) { +function install(stream: InMemoryStream, consume: UpgradeConsumer, phases: Phases = {}) { return runUpgrade({ command: { requestedTag: null, @@ -156,7 +162,7 @@ function install(consume: UpgradeConsumer, phases: Phases = {}) { allowPrerelease: false, }, assembly: assemblyFor(phases), - stream: new InMemoryStream(), + stream, consume, }); } @@ -164,114 +170,133 @@ function install(consume: UpgradeConsumer, phases: Phases = {}) { describe("Tier UO — the upgrade transcript", () => { beforeAll(() => useTempFileCompiler()); - it("UO1: each milestone reaches the reader before the next phase begins", function* () { - // The decisive case. A run that buffered everything and wrote it at the end - // produces byte-identical output, so the only way to tell streaming from - // buffering is to look at what has already arrived while a later phase has - // not started. - const arrived: string[] = []; - const soFar = () => arrived.join(""); - let atVerify = ""; - let atReplace = ""; + journalCase( + "UO1: each milestone reaches the reader before the next phase begins", + UPGRADE_COMMAND_IDENTITY, + function* (stream) { + // The decisive case. A run that buffered everything and wrote it at the end + // produces byte-identical output, so the only way to tell streaming from + // buffering is to look at what has already arrived while a later phase has + // not started. + const arrived: string[] = []; + const soFar = () => arrived.join(""); + let atVerify = ""; + let atReplace = ""; - const outcome = yield* install( - // deno-lint-ignore require-yield - function* (chunk) { - arrived.push(chunk); - }, - { + const outcome = yield* install( + stream, // deno-lint-ignore require-yield - *beforeVerify() { - atVerify = soFar(); + function* (chunk) { + arrived.push(chunk); }, - // deno-lint-ignore require-yield - *beforeReplace() { - atReplace = soFar(); + { + // deno-lint-ignore require-yield + *beforeVerify() { + atVerify = soFar(); + }, + // deno-lint-ignore require-yield + *beforeReplace() { + atReplace = soFar(); + }, }, - }, - ); + ); - expect(outcome.ok).toBe(true); + expect(outcome.ok).toBe(true); - // Before verification started, the reader already had the selection and the - // download — and nothing about verification or replacement. - expect(atVerify).toContain("Selected release: v0.11.0 (newer than installed version 0.10.2)"); - expect(atVerify).toContain(`Downloaded binary: ${ASSET}`); - expect(atVerify).not.toContain("Verified: SHA-256"); - expect(atVerify).not.toContain("Installed xmd"); + // Before verification started, the reader already had the selection and the + // download — and nothing about verification or replacement. + expect(atVerify).toContain("Selected release: v0.11.0 (newer than installed version 0.10.2)"); + expect(atVerify).toContain(`Downloaded binary: ${ASSET}`); + expect(atVerify).not.toContain("Verified: SHA-256"); + expect(atVerify).not.toContain("Installed xmd"); - // Before replacement started, verification had landed too. - expect(atReplace).toContain("Verified: SHA-256 checksum and version 0.11.0"); - expect(atReplace).not.toContain("Installed xmd"); + // Before replacement started, verification had landed too. + expect(atReplace).toContain("Verified: SHA-256 checksum and version 0.11.0"); + expect(atReplace).not.toContain("Installed xmd"); - // And the installation summary is last. - expect(soFar()).toContain("Installed xmd 0.11.0 (replaced 0.10.2)."); + // And the installation summary is last. + expect(soFar()).toContain("Installed xmd 0.11.0 (replaced 0.10.2)."); - // Blank runs are collapsed to one blank line, and the transcript ends with - // exactly one newline. A branch the command did not take leaves the engine - // emitting the blank lines that surrounded it, and this document has enough - // branches that a reader would otherwise meet a dozen at a time. - expect(soFar()).not.toMatch(/\n{3}/); - expect(soFar().startsWith("#")).toBe(true); - expect(soFar().endsWith("\n")).toBe(true); - expect(soFar().endsWith("\n\n")).toBe(false); - }); + // Blank runs are collapsed to one blank line, and the transcript ends with + // exactly one newline. A branch the command did not take leaves the engine + // emitting the blank lines that surrounded it, and this document has enough + // branches that a reader would otherwise meet a dozen at a time. + expect(soFar()).not.toMatch(/\n{3}/); + expect(soFar().startsWith("#")).toBe(true); + expect(soFar().endsWith("\n")).toBe(true); + expect(soFar().endsWith("\n\n")).toBe(false); + }, + ); - it("UO2: every consumer drains the same stream, and nothing is printed twice", function* () { + const identical = "UO2: every consumer drains the same stream, and nothing is printed twice"; + journalCase(identical, UPGRADE_COMMAND_IDENTITY, function* (stream) { // The three shapes the command supports: a terminal writing as it goes, a // pipe writing once at the end, and a test observing. All read the same // `execution.output`, so the bytes cannot differ between them. const streamed: string[] = []; const first = yield* install( + stream, // deno-lint-ignore require-yield function* (chunk) { streamed.push(chunk); }, ); - const buffered: string[] = []; - const second = yield* install( - // deno-lint-ignore require-yield - function* (chunk) { - buffered.push(chunk); - }, - ); + yield* captureTestJournal( + { owner: OWNER, name: identical }, + UPGRADE_COMMAND_IDENTITY, + function* (otherStream) { + const buffered: string[] = []; + const second = yield* install( + otherStream, + // deno-lint-ignore require-yield + function* (chunk) { + buffered.push(chunk); + }, + ); - expect(first.ok).toBe(true); - expect(second.ok).toBe(true); - expect(streamed.join("")).toBe(buffered.join("")); - // More than one chunk, or the progressive claim above would be vacuous. - expect(streamed.length).toBeGreaterThan(1); + expect(first.ok).toBe(true); + expect(second.ok).toBe(true); + expect(streamed.join("")).toBe(buffered.join("")); + // More than one chunk, or the progressive claim above would be vacuous. + expect(streamed.length).toBeGreaterThan(1); - // The completion value is never handed back for printing: a text root's - // value is the text the consumer already has, and returning it would invite - // the caller to say everything twice. - expect(first.ok ? first.value : "unreachable").toBe(undefined); + // The completion value is never handed back for printing: a text root's + // value is the text the consumer already has, and returning it would invite + // the caller to say everything twice. + expect(first.ok ? first.value : "unreachable").toBe(undefined); + }, + ); }); - it("UO3: a consumer that fails cancels the run and reports rather than hanging", function* () { - let replaced = false; - const outcome = yield* install( - // deno-lint-ignore require-yield - function* (chunk) { - if (chunk.includes("Downloaded binary:")) { - throw new Error("the terminal went away"); - } - }, - { + journalCase( + "UO3: a consumer that fails cancels the run and reports rather than hanging", + UPGRADE_COMMAND_IDENTITY, + function* (stream) { + let replaced = false; + const outcome = yield* install( + stream, // deno-lint-ignore require-yield - *beforeReplace() { - replaced = true; + function* (chunk) { + if (chunk.includes("Downloaded binary:")) { + throw new Error("the terminal went away"); + } }, - }, - ); + { + // deno-lint-ignore require-yield + *beforeReplace() { + replaced = true; + }, + }, + ); - expect(outcome.ok).toBe(false); - expect(outcome.ok ? "" : outcome.error.message).toContain("the terminal went away"); - // The document was cancelled, so the phase after the failing chunk never - // ran. A consumer failure is not a reason to finish replacing a binary. - expect(replaced).toBe(false); - }); + expect(outcome.ok).toBe(false); + expect(outcome.ok ? "" : outcome.error.message).toContain("the terminal went away"); + // The document was cancelled, so the phase after the failing chunk never + // ran. A consumer failure is not a reason to finish replacing a binary. + expect(replaced).toBe(false); + }, + ); it("UO4: the durable stream records the run and grants it nothing", function* () { // The journal is evidence, never input. This asserts the first half — that From 3409f1d4334691d8b108301fbde4496dec96c30b Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:34:45 -0500 Subject: [PATCH 18/78] test: attribute guarded Agent provider and usage journals --- packages/agent/tests/agent-stack.test.ts | 243 ++++++++++++--------- packages/agent/tests/agent-usage.test.ts | 154 +++++++------ packages/agent/tests/root-provider.test.ts | 170 +++++++------- packages/test-support/journal-cases.ts | 18 ++ 4 files changed, 342 insertions(+), 243 deletions(-) diff --git a/packages/agent/tests/agent-stack.test.ts b/packages/agent/tests/agent-stack.test.ts index ffd2b307e..d5ebf280b 100644 --- a/packages/agent/tests/agent-stack.test.ts +++ b/packages/agent/tests/agent-stack.test.ts @@ -7,14 +7,13 @@ * not established here; it is asserted at the CLI boundary. */ import { describe, it } from "@executablemd/test-support/bdd"; +import { fileJournalCases } from "../../test-support/journal-cases.ts"; import { expect } from "@executablemd/test-support/expect"; import { ensure, scoped } from "effection"; import type { Operation, Result } from "effection"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import type { InMemoryStream } from "@executablemd/durable-streams"; import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; -import { randomUUID } from "node:crypto"; import * as path from "node:path"; -import * as os from "node:os"; import { execute } from "../../core/src/execute.ts"; import { registerComponents } from "../../core/src/components/registration.ts"; import { Agent } from "../src/agent-api.ts"; @@ -55,11 +54,18 @@ function recordingFactory(seen: AgentProviderOptions[]): AgentProviderFactory { }; } +const journalCase = fileJournalCases( + "packages/agent/tests/agent-stack.test.ts", + "xmd-ag-", + "doc.md", +); + function* runDoc( doc: string, install: () => Operation, + stream: InMemoryStream, + dir: string, ): Operation<{ output: string; result: Result }> { - const dir = path.join(os.tmpdir(), `xmd-ag-${randomUUID()}`); yield* ensureDir(dir); return yield* scoped(function* () { yield* ensure(() => rm(dir, { recursive: true, force: true })); @@ -67,7 +73,7 @@ function* runDoc( const docPath = path.join(dir, "doc.md"); yield* writeTextFile(docPath, doc); yield* install(); - const execution = yield* execute({ path: docPath, stream: new InMemoryStream() }); + const execution = yield* execute({ path: docPath, stream }); const subscription = yield* execution.output; let next = yield* subscription.next(); while (!next.done) { @@ -211,106 +217,139 @@ describe("Tier AG — provider registry and permission policies", () => { expect(yield* decide()).toEqual({ outcome: "selected", optionId: "allow-once" }); }); - it("AG7: approves inside its body under an enclosing deny", function* () { - const outcomes: string[] = []; - const { result } = yield* runDoc( - ["", "", "", "", "", "", "", ""].join("\n"), - function* () { - yield* installAskComponent(outcomes); - yield* installAgentComponents(); - }, - ); - expect(result.ok).toBe(true); - expect(outcomes).toEqual(["reject-once", "allow-once", "reject-once"]); - }); + journalCase( + "AG7: approves inside its body under an enclosing deny", + function* (stream, directory) { + const outcomes: string[] = []; + const { result } = yield* runDoc( + ["", "", "", "", "", "", "", ""].join("\n"), + function* () { + yield* installAskComponent(outcomes); + yield* installAgentComponents(); + }, + stream, + directory, + ); + expect(result.ok).toBe(true); + expect(outcomes).toEqual(["reject-once", "allow-once", "reject-once"]); + }, + ); - it("AG8: denies inside its body under an enclosing approve-all", function* () { - const outcomes: string[] = []; - const { result } = yield* runDoc( - ["", "", "", "", "", "", "", ""].join( - "\n", - ), - function* () { - yield* installAskComponent(outcomes); - yield* installApproveAll(); - yield* installAgentComponents(); - }, - ); - expect(result.ok).toBe(true); - expect(outcomes).toEqual(["allow-once", "reject-once", "allow-once"]); - }); + journalCase( + "AG8: denies inside its body under an enclosing approve-all", + function* (stream, directory) { + const outcomes: string[] = []; + const { result } = yield* runDoc( + ["", "", "", "", "", "", "", ""].join( + "\n", + ), + function* () { + yield* installAskComponent(outcomes); + yield* installApproveAll(); + yield* installAgentComponents(); + }, + stream, + directory, + ); + expect(result.ok).toBe(true); + expect(outcomes).toEqual(["allow-once", "reject-once", "allow-once"]); + }, + ); - it("AG9: installAgentComponents seeds the default agent and permission mode", function* () { - const seen: AgentProviderOptions[] = []; - const { result } = yield* runDoc('\n', function* () { - yield* registerAgentProvider("rec", recordingFactory(seen)); - yield* installAgentComponents({ - defaultAgent: "seeded-agent", - permissionMode: "approve-reads", - }); - }); - expect(result.ok).toBe(true); - expect(seen).toEqual([{ defaultAgent: "seeded-agent", permissionMode: "approve-reads" }]); - }); + journalCase( + "AG9: installAgentComponents seeds the default agent and permission mode", + function* (stream, directory) { + const seen: AgentProviderOptions[] = []; + const { result } = yield* runDoc( + '\n', + function* () { + yield* registerAgentProvider("rec", recordingFactory(seen)); + yield* installAgentComponents({ + defaultAgent: "seeded-agent", + permissionMode: "approve-reads", + }); + }, + stream, + directory, + ); + expect(result.ok).toBe(true); + expect(seen).toEqual([{ defaultAgent: "seeded-agent", permissionMode: "approve-reads" }]); + }, + ); - it("AG10: overrides inside its body and restores after", function* () { - const seen: AgentProviderOptions[] = []; - const { result } = yield* runDoc( - [ - '', - "inside", - "", - '', - "", - ].join("\n"), - function* () { - yield* registerAgentProvider("rec", recordingFactory(seen)); - yield* installAgentComponents({ - defaultAgent: "seeded-agent", - permissionMode: "deny-all", - }); - }, - ); - expect(result.ok).toBe(true); - expect(seen.map((options) => options.defaultAgent)).toEqual(["scoped-agent", "seeded-agent"]); - // permissionMode is inherited, never overridden by a prop. - expect(seen.every((options) => options.permissionMode === "deny-all")).toBe(true); - }); + journalCase( + "AG10: overrides inside its body and restores after", + function* (stream, directory) { + const seen: AgentProviderOptions[] = []; + const { result } = yield* runDoc( + [ + '', + "inside", + "", + '', + "", + ].join("\n"), + function* () { + yield* registerAgentProvider("rec", recordingFactory(seen)); + yield* installAgentComponents({ + defaultAgent: "seeded-agent", + permissionMode: "deny-all", + }); + }, + stream, + directory, + ); + expect(result.ok).toBe(true); + expect(seen.map((options) => options.defaultAgent)).toEqual(["scoped-agent", "seeded-agent"]); + // permissionMode is inherited, never overridden by a prop. + expect(seen.every((options) => options.permissionMode === "deny-all")).toBe(true); + }, + ); - it("AG11: an unknown fails the execution; no body or later content renders", function* () { - const seen: AgentProviderOptions[] = []; - const { output, result } = yield* runDoc( - [ - '', - "INSIDE_MARKER", - "", - "AFTER_MARKER", - "", - ].join("\n"), - function* () { - yield* registerAgentProvider("rec", recordingFactory(seen)); - yield* installAgentComponents({ defaultAgent: "seeded-agent" }); - }, - ); - expect(result.ok).toBe(false); - expect(output).not.toContain("INSIDE_MARKER"); - expect(output).not.toContain("AFTER_MARKER"); - expect(seen.length).toBe(0); - }); + journalCase( + "AG11: an unknown fails the execution; no body or later content renders", + function* (stream, directory) { + const seen: AgentProviderOptions[] = []; + const { output, result } = yield* runDoc( + [ + '', + "INSIDE_MARKER", + "", + "AFTER_MARKER", + "", + ].join("\n"), + function* () { + yield* registerAgentProvider("rec", recordingFactory(seen)); + yield* installAgentComponents({ defaultAgent: "seeded-agent" }); + }, + stream, + directory, + ); + expect(result.ok).toBe(false); + expect(output).not.toContain("INSIDE_MARKER"); + expect(output).not.toContain("AFTER_MARKER"); + expect(seen.length).toBe(0); + }, + ); - it("AG12: without any default agent fails before its body expands", function* () { - const seen: AgentProviderOptions[] = []; - const { output, result } = yield* runDoc( - ['', "INSIDE_MARKER", "", ""].join("\n"), - function* () { - yield* registerAgentProvider("rec", recordingFactory(seen)); - yield* installAgentComponents(); - }, - ); - expect(result.ok).toBe(false); - const message = result.ok ? "" : result.error.message; - expect(message).toContain("no default agent"); - expect(output).not.toContain("INSIDE_MARKER"); - expect(seen.length).toBe(0); - }); + journalCase( + "AG12: without any default agent fails before its body expands", + function* (stream, directory) { + const seen: AgentProviderOptions[] = []; + const { output, result } = yield* runDoc( + ['', "INSIDE_MARKER", "", ""].join("\n"), + function* () { + yield* registerAgentProvider("rec", recordingFactory(seen)); + yield* installAgentComponents(); + }, + stream, + directory, + ); + expect(result.ok).toBe(false); + const message = result.ok ? "" : result.error.message; + expect(message).toContain("no default agent"); + expect(output).not.toContain("INSIDE_MARKER"); + expect(seen.length).toBe(0); + }, + ); }); diff --git a/packages/agent/tests/agent-usage.test.ts b/packages/agent/tests/agent-usage.test.ts index 7195db337..beb038937 100644 --- a/packages/agent/tests/agent-usage.test.ts +++ b/packages/agent/tests/agent-usage.test.ts @@ -8,6 +8,7 @@ */ import { describe, it } from "@executablemd/test-support/bdd"; +import { fileJournalCases } from "../../test-support/journal-cases.ts"; import { expect } from "@executablemd/test-support/expect"; import { InMemoryStream } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; @@ -261,6 +262,12 @@ function always(plan: TurnPlan): () => TurnPlan { return () => ({ ...plan }); } +const journalCase = fileJournalCases( + "packages/agent/tests/agent-usage.test.ts", + "xmd-pu-test-", + "doc.md", +); + function* runDocument( doc: string, stream: InMemoryStream, @@ -270,8 +277,8 @@ function* runDocument( direct?: boolean; scanner?: () => SecretScanner; } = {}, + dir = path.join(os.tmpdir(), `xmd-pu-test-${randomUUID()}`), ): Operation<{ result: Result; events: DurableEvent[] }> { - const dir = path.join(os.tmpdir(), `xmd-pu-test-${randomUUID()}`); yield* ensureDir(dir); return yield* scoped(function* () { yield* ensure(() => rm(dir, { recursive: true, force: true })); @@ -435,52 +442,60 @@ describe("Tier PU — subscription-local receiver", () => { expect(trace.acquisitions).toBe(2); }); - it("PU-B3: a direct Agent.prompt() gets an ephemeral receiver and lends nothing to the next Prompt", function* () { - const trace = newTrace(); - const receivers: (PromptUsageReporter | undefined)[] = []; - const plans: TurnPlan[] = [ - { - usage: () => versioned("direct"), - captured: (report) => receivers.push(report), - }, - { captured: (report) => receivers.push(report) }, - { - usage: () => versioned("canonical"), - captured: (report) => receivers.push(report), - }, - ]; - const { result, events } = yield* runDocument( - "\n\nsilent\n\nmeasured\n", - new InMemoryStream(), - stubFactory(trace, () => plans.shift() ?? {}), - { direct: true }, - ); - expect(result.ok).toBe(true); - expect(receivers.length).toBe(3); - expect(receivers[0]).not.toBe(undefined); - // The direct call's turn reported, and no record exists for it; the - // adjacent Prompt that reported nothing retains nothing; the one that did - // retains its own. - const records = promptValues(events); - expect(records.length).toBe(2); - expect(Object.hasOwn(records[0], "usage")).toBe(false); - expect(parsePromptRecord(records[1])?.usage?.provenance.xmd.version).toBe("canonical"); - }); - - it("PU-B4: a registered provider's delivered coordinator keeps the optional receiver", function* () { - const trace = newTrace(); - const { result, events } = yield* runDocument( - '\n\none\n\n\n', - new InMemoryStream(), - stubFactory(trace, always({ usage: () => versioned("registered") })), - { register: true }, - ); - expect(result.ok).toBe(true); - expect(trace.acquisitions).toBe(1); - expect(parsePromptRecord(promptValues(events)[0])?.usage?.provenance.xmd.version).toBe( - "registered", - ); - }); + journalCase( + "PU-B3: a direct Agent.prompt() gets an ephemeral receiver and lends nothing to the next Prompt", + function* (stream, directory) { + const trace = newTrace(); + const receivers: (PromptUsageReporter | undefined)[] = []; + const plans: TurnPlan[] = [ + { + usage: () => versioned("direct"), + captured: (report) => receivers.push(report), + }, + { captured: (report) => receivers.push(report) }, + { + usage: () => versioned("canonical"), + captured: (report) => receivers.push(report), + }, + ]; + const { result, events } = yield* runDocument( + "\n\nsilent\n\nmeasured\n", + stream, + stubFactory(trace, () => plans.shift() ?? {}), + { direct: true }, + directory, + ); + expect(result.ok).toBe(true); + expect(receivers.length).toBe(3); + expect(receivers[0]).not.toBe(undefined); + // The direct call's turn reported, and no record exists for it; the + // adjacent Prompt that reported nothing retains nothing; the one that did + // retains its own. + const records = promptValues(events); + expect(records.length).toBe(2); + expect(Object.hasOwn(records[0], "usage")).toBe(false); + expect(parsePromptRecord(records[1])?.usage?.provenance.xmd.version).toBe("canonical"); + }, + ); + + journalCase( + "PU-B4: a registered provider's delivered coordinator keeps the optional receiver", + function* (stream, directory) { + const trace = newTrace(); + const { result, events } = yield* runDocument( + '\n\none\n\n\n', + stream, + stubFactory(trace, always({ usage: () => versioned("registered") })), + { register: true }, + directory, + ); + expect(result.ok).toBe(true); + expect(trace.acquisitions).toBe(1); + expect(parsePromptRecord(promptValues(events)[0])?.usage?.provenance.xmd.version).toBe( + "registered", + ); + }, + ); }); describe("Tier PU — canonical retention and replay", () => { @@ -511,26 +526,31 @@ describe("Tier PU — canonical retention and replay", () => { expect(restored?.map((record) => record.usage)).toEqual([sampleUsage("one")]); }); - it("PU-P2: an acknowledged failed turn keeps what it reported, and no checkpoint", function* () { - const failing = sampleUsage("failed"); - const partial: PromptUsage = { - ...failing, - coverage: { - finalReport: "unavailable", - outerPrompt: "unknown", - limitations: ["final-report-unavailable"], - }, - }; - const { events } = yield* runDocument( - "fails\n", - new InMemoryStream(), - stubFactory(newTrace(), always({ status: "failed", usage: () => partial })), - ); - const record = parsePromptRecord(promptValues(events)[0]); - expect(record?.status).toBe("failed"); - expect(record?.usage).toEqual(partial); - expect(record?.checkpoint).toBe(undefined); - }); + journalCase( + "PU-P2: an acknowledged failed turn keeps what it reported, and no checkpoint", + function* (stream, directory) { + const failing = sampleUsage("failed"); + const partial: PromptUsage = { + ...failing, + coverage: { + finalReport: "unavailable", + outerPrompt: "unknown", + limitations: ["final-report-unavailable"], + }, + }; + const { events } = yield* runDocument( + "fails\n", + stream, + stubFactory(newTrace(), always({ status: "failed", usage: () => partial })), + {}, + directory, + ); + const record = parsePromptRecord(promptValues(events)[0]); + expect(record?.status).toBe("failed"); + expect(record?.usage).toEqual(partial); + expect(record?.checkpoint).toBe(undefined); + }, + ); it("PU-P3: a held conversation's turn retains usage through the same runner", function* () { const stream = new InMemoryStream(); diff --git a/packages/agent/tests/root-provider.test.ts b/packages/agent/tests/root-provider.test.ts index 43c21991b..d55c50ee1 100644 --- a/packages/agent/tests/root-provider.test.ts +++ b/packages/agent/tests/root-provider.test.ts @@ -8,14 +8,13 @@ * teardown — never a manual teardown call or a Promise. */ import { describe, it } from "@executablemd/test-support/bdd"; +import { fileJournalCases } from "../../test-support/journal-cases.ts"; import { expect } from "@executablemd/test-support/expect"; import { ensure, Ok, scoped } from "effection"; import type { Operation, Result, Stream } from "effection"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import type { InMemoryStream } from "@executablemd/durable-streams"; import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; -import { randomUUID } from "node:crypto"; import * as path from "node:path"; -import * as os from "node:os"; import { execute } from "../../core/src/execute.ts"; import { Agent } from "../src/agent-api.ts"; import { sessionOf } from "../src/session-use.ts"; @@ -130,15 +129,24 @@ function stubStream( }; } -function* runDoc(doc: string): Operation<{ output: string; result: Result }> { - const dir = path.join(os.tmpdir(), `xmd-rp-test-${randomUUID()}`); +const journalCase = fileJournalCases( + "packages/agent/tests/root-provider.test.ts", + "xmd-rp-test-", + "doc.md", +); + +function* runDoc( + doc: string, + stream: InMemoryStream, + dir: string, +): Operation<{ output: string; result: Result }> { yield* ensureDir(dir); return yield* scoped(function* () { yield* ensure(() => rm(dir, { recursive: true, force: true })); const docPath = path.join(dir, "doc.md"); yield* writeTextFile(docPath, doc); - const execution = yield* execute({ path: docPath, stream: new InMemoryStream() }); + const execution = yield* execute({ path: docPath, stream }); const subscription = yield* execution.output; let next = yield* subscription.next(); while (!next.done) { @@ -152,81 +160,95 @@ function* runDoc(doc: string): Operation<{ output: string; result: Result const OPTIONS: AgentProviderOptions = { defaultAgent: "a", permissionMode: "deny-all" }; describe("Tier RP — root-provider lifecycle", () => { - it("RP1: provider is active during execution; its finalizer runs once, before completion settles", function* () { - const { factory, state } = createProvider(); - yield* installAgentComponents({ rootProvider: { factory, options: OPTIONS } }); - const { output, result } = yield* runDoc('\n'); - expect(result.ok).toBe(true); - expect(output).toContain("[hi]"); - expect(state.activeDuringPrompt).toBe(true); - expect(state.finalizeCount).toBe(1); - // Completion only settled after cleanup ran. - expect(state.cleanupDone).toBe(true); - }); - - it("RP2: a teardown failure still closes rendered output but makes completion an Err", function* () { - const boom = new Error("teardown boom"); - const { factory } = createProvider({ teardownError: boom }); - yield* installAgentComponents({ rootProvider: { factory, options: OPTIONS } }); - const { output, result } = yield* runDoc('\n'); - expect(output).toContain("[hi]"); - expect(result.ok).toBe(false); - if (!result.ok) { - expect(result.error).toBe(boom); - } - }); + journalCase( + "RP1: provider is active during execution; its finalizer runs once, before completion settles", + function* (stream, directory) { + const { factory, state } = createProvider(); + yield* installAgentComponents({ rootProvider: { factory, options: OPTIONS } }); + const { output, result } = yield* runDoc('\n', stream, directory); + expect(result.ok).toBe(true); + expect(output).toContain("[hi]"); + expect(state.activeDuringPrompt).toBe(true); + expect(state.finalizeCount).toBe(1); + // Completion only settled after cleanup ran. + expect(state.cleanupDone).toBe(true); + }, + ); + + journalCase( + "RP2: a teardown failure still closes rendered output but makes completion an Err", + function* (stream, directory) { + const boom = new Error("teardown boom"); + const { factory } = createProvider({ teardownError: boom }); + yield* installAgentComponents({ rootProvider: { factory, options: OPTIONS } }); + const { output, result } = yield* runDoc('\n', stream, directory); + expect(output).toContain("[hi]"); + expect(result.ok).toBe(false); + if (!result.ok) { + expect(result.error).toBe(boom); + } + }, + ); // RP5: first-failure precedence, where it is easiest to get wrong. The // document fails on its own terms and cleanup fails too. Both happened; what // the caller receives is the failure the document earned, because a completion // policy adds and never replaces. - it("RP5: a failed document keeps its own failure even when cleanup also fails", function* () { - const boom = new Error("teardown boom"); - const { factory, state } = createProvider({ teardownError: boom, extraFinalizer: true }); - yield* installAgentComponents({ rootProvider: { factory, options: OPTIONS } }); - - // The document fails on its own terms — a failing command inside , - // where an error fails the execution rather than printing — with no prompt - // having failed. - const { result } = yield* runDoc( - ["", "", "```bash exec", "exit 3", "```", "", "", ""].join("\n"), - ); - - expect(result.ok).toBe(false); - if (!result.ok) { - expect(result.error).not.toBe(boom); - expect(result.error).not.toBeInstanceOf(AggregateError); - expect(result.error.message).not.toContain("teardown boom"); - } - // Cleanup still ran — both finalizers. - expect(state.extraRan).toBe(true); - expect(state.cleanupDone).toBe(true); - }); + journalCase( + "RP5: a failed document keeps its own failure even when cleanup also fails", + function* (stream, directory) { + const boom = new Error("teardown boom"); + const { factory, state } = createProvider({ teardownError: boom, extraFinalizer: true }); + yield* installAgentComponents({ rootProvider: { factory, options: OPTIONS } }); + + // The document fails on its own terms — a failing command inside , + // where an error fails the execution rather than printing — with no prompt + // having failed. + const { result } = yield* runDoc( + ["", "", "```bash exec", "exit 3", "```", "", "", ""].join("\n"), + stream, + directory, + ); - it("RP3: a prompt failure plus a teardown failure aggregate — primary first, every cleanup runs", function* () { - const boom = new Error("teardown boom"); - const { factory, state } = createProvider({ - teardownError: boom, - extraFinalizer: true, - fail: true, - }); - yield* installAgentComponents({ rootProvider: { factory, options: OPTIONS } }); - const { result } = yield* runDoc('\n'); - expect(result.ok).toBe(false); - if (!result.ok) { - expect(result.error).toBeInstanceOf(AggregateError); - if (result.error instanceof AggregateError) { - const errors = result.error.errors; - expect(errors[0]).toBeInstanceOf(AgentPromptError); - expect(errors[errors.length - 1]).toBe(boom); - expect(result.error.message).toContain("agent prompt(s) failed"); - expect(result.error.message).toContain("teardown failed"); + expect(result.ok).toBe(false); + if (!result.ok) { + expect(result.error).not.toBe(boom); + expect(result.error).not.toBeInstanceOf(AggregateError); + expect(result.error.message).not.toContain("teardown boom"); } - } - // The non-throwing finalizer still ran despite the throwing one. - expect(state.extraRan).toBe(true); - expect(state.cleanupDone).toBe(true); - }); + // Cleanup still ran — both finalizers. + expect(state.extraRan).toBe(true); + expect(state.cleanupDone).toBe(true); + }, + ); + + journalCase( + "RP3: a prompt failure plus a teardown failure aggregate — primary first, every cleanup runs", + function* (stream, directory) { + const boom = new Error("teardown boom"); + const { factory, state } = createProvider({ + teardownError: boom, + extraFinalizer: true, + fail: true, + }); + yield* installAgentComponents({ rootProvider: { factory, options: OPTIONS } }); + const { result } = yield* runDoc('\n', stream, directory); + expect(result.ok).toBe(false); + if (!result.ok) { + expect(result.error).toBeInstanceOf(AggregateError); + if (result.error instanceof AggregateError) { + const errors = result.error.errors; + expect(errors[0]).toBeInstanceOf(AgentPromptError); + expect(errors[errors.length - 1]).toBe(boom); + expect(result.error.message).toContain("agent prompt(s) failed"); + expect(result.error.message).toContain("teardown failed"); + } + } + // The non-throwing finalizer still ran despite the throwing one. + expect(state.extraRan).toBe(true); + expect(state.cleanupDone).toBe(true); + }, + ); }); describe("Tier RP — what the delivery adapter carries to a provider", () => { diff --git a/packages/test-support/journal-cases.ts b/packages/test-support/journal-cases.ts index 2fa110cfb..2851b45d2 100644 --- a/packages/test-support/journal-cases.ts +++ b/packages/test-support/journal-cases.ts @@ -2,6 +2,9 @@ import { it } from "./bdd.ts"; import { captureTestJournal } from "./failure-journal.ts"; import type { InMemoryStream } from "@executablemd/durable-streams"; import type { Operation } from "effection"; +import { randomUUID } from "node:crypto"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; /** Register a case that owns one fresh guarded document execution. */ export function journalCases(owner: string) { @@ -13,3 +16,18 @@ export function journalCases(owner: string) { it(name, () => captureTestJournal({ owner, name }, source, body)); }; } + +/** Attribute a real fixture file whose directory is created by the case. */ +export function fileJournalCases(owner: string, directoryPrefix: string, filename: string) { + return ( + name: string, + body: (stream: InMemoryStream, directory: string) => Operation, + ): void => { + it(name, () => { + const directory = join(tmpdir(), directoryPrefix + randomUUID()); + return captureTestJournal({ owner, name }, join(directory, filename), (stream) => + body(stream, directory), + ); + }); + }; +} From da0ecf30d51189a55b62ef233dc9999ed56bb40b Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:36:55 -0500 Subject: [PATCH 19/78] test: attribute fresh Answers, Elicit and Fail fixture journals --- packages/core/tests/answers-component.test.ts | 567 +++++++++--------- packages/core/tests/elicit-component.test.ts | 254 ++++---- packages/core/tests/fail-component.test.ts | 257 ++++---- packages/test-support/journal-cases.ts | 20 +- 4 files changed, 584 insertions(+), 514 deletions(-) diff --git a/packages/core/tests/answers-component.test.ts b/packages/core/tests/answers-component.test.ts index 0713bdb90..6b0459639 100644 --- a/packages/core/tests/answers-component.test.ts +++ b/packages/core/tests/answers-component.test.ts @@ -16,6 +16,7 @@ */ import { describe, it } from "@executablemd/test-support/bdd"; +import { workspaceJournalCases } from "../../test-support/journal-cases.ts"; import { expect } from "@executablemd/test-support/expect"; import { ensure, resource, scoped, until } from "effection"; import type { Operation, Result } from "effection"; @@ -41,6 +42,12 @@ const SCHEMA = '{"type":"object","properties":{"decision":{"type":"string"}},"required":["decision"],' + '"additionalProperties":false}'; +const journalCase = workspaceJournalCases( + "packages/core/tests/answers-component.test.ts", + "doc.md", + useWorkspace, +); + function useWorkspace(): Operation { return resource(function* (provide) { const root = yield* until(realpath(yield* until(mkdtemp(join(tmpdir(), "answers-test-"))))); @@ -178,29 +185,30 @@ function reported(result: Run): string { } describe("Answers: choosing by template", () => { - it("answers a nested component's elicitation with no host provider installed", function* () { - const workspace = yield* useWorkspace(); - yield* writeGate(workspace); - - const result = yield* run( - workspace, - [ - "", - '', - "", - "", - "", - "", - ].join("\n"), - ); + journalCase( + "answers a nested component's elicitation with no host provider installed", + function* (stream, workspace) { + yield* writeGate(workspace); - expect(result.failure).toBe(undefined); - expect(result.output).toContain("gate saw: approve"); - }); + const result = yield* run( + workspace, + [ + "", + '', + "", + "", + "", + "", + ].join("\n"), + { stream }, + ); - it("matches anything when the matcher has no template", function* () { - const workspace = yield* useWorkspace(); + expect(result.failure).toBe(undefined); + expect(result.output).toContain("gate saw: approve"); + }, + ); + journalCase("matches anything when the matcher has no template", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -214,14 +222,13 @@ describe("Answers: choosing by template", () => { "", "", ].join("\n"), + { stream }, ); expect(result.output).toContain("Got: catch-all"); }); - it("reads a multiline template from children", function* () { - const workspace = yield* useWorkspace(); - + journalCase("reads a multiline template from children", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -237,15 +244,14 @@ describe("Answers: choosing by template", () => { "", "", ].join("\n"), + { stream }, ); expect(result.output).toContain("Got: deployed"); }); /** `{?name}` constrains position but carries nothing into the answer. */ - it("uses a wildcard hole to constrain without binding", function* () { - const workspace = yield* useWorkspace(); - + journalCase("uses a wildcard hole to constrain without binding", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -259,34 +265,35 @@ describe("Answers: choosing by template", () => { "", "", ].join("\n"), + { stream }, ); expect(result.output).toContain("Got: yes"); }); - it("does not match when the literal text around a hole differs", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run( - workspace, - SCHEMA_BLOCK + - [ - "", - '', - "", - elicits("a", "Deploy api to staging?"), - "", - "", - ].join("\n"), - ); + journalCase( + "does not match when the literal text around a hole differs", + function* (stream, workspace) { + const result = yield* run( + workspace, + SCHEMA_BLOCK + + [ + "", + '', + "", + elicits("a", "Deploy api to staging?"), + "", + "", + ].join("\n"), + { stream }, + ); - expect(result.failure).toContain("no matcher for this elicitation"); - }); + expect(result.failure).toContain("no matcher for this elicitation"); + }, + ); /** A `{binding}` in the prop form reaches the engine intact and constrains. */ - it("interpolates a binding in the template prop", function* () { - const workspace = yield* useWorkspace(); - + journalCase("interpolates a binding in the template prop", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -304,37 +311,39 @@ describe("Answers: choosing by template", () => { "", "", ].join("\n"), + { stream }, ); expect(result.output).toContain("Got: bound"); }); - it("does not match when the interpolated binding differs", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run( - workspace, - SCHEMA_BLOCK + - [ - "```js eval", - 'const service = "worker";', - "```", - "", - "", - '', - "", - elicits("a", "Deploy api to production?"), - "", - "", - ].join("\n"), - ); + journalCase( + "does not match when the interpolated binding differs", + function* (stream, workspace) { + const result = yield* run( + workspace, + SCHEMA_BLOCK + + [ + "```js eval", + 'const service = "worker";', + "```", + "", + "", + '', + "", + elicits("a", "Deploy api to production?"), + "", + "", + ].join("\n"), + { stream }, + ); - expect(result.failure).toContain("no matcher for this elicitation"); - }); + expect(result.failure).toContain("no matcher for this elicitation"); + }, + ); /** A string answer is JSON text like any other, so it is written quoted. */ - it("round-trips a string answer written as quoted JSON", function* () { - const workspace = yield* useWorkspace(); + journalCase("round-trips a string answer written as quoted JSON", function* (stream, workspace) { const stringSchema = '{"type":"string"}'; const result = yield* run( @@ -353,15 +362,14 @@ describe("Answers: choosing by template", () => { "", "", ].join("\n"), + { stream }, ); expect(result.failure).toBe(undefined); expect(result.output).toContain("Got: approve"); }); - it("reads a value written as captured JSON text", function* () { - const workspace = yield* useWorkspace(); - + journalCase("reads a value written as captured JSON text", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -375,6 +383,7 @@ describe("Answers: choosing by template", () => { "", "", ].join("\n"), + { stream }, ); expect(result.output).toContain("Got: from-text"); @@ -386,9 +395,7 @@ describe("Answers: selection", () => { * First declared wins, and the consequence is the point: a broad template * above a narrow one shadows it permanently. */ - it("takes the first declared matching matcher", function* () { - const workspace = yield* useWorkspace(); - + journalCase("takes the first declared matching matcher", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -403,38 +410,39 @@ describe("Answers: selection", () => { "", "", ].join("\n"), + { stream }, ); expect(result.output).toContain("Got: broad"); }); - it("lets a narrower matcher win when it is declared first", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run( - workspace, - SCHEMA_BLOCK + - [ - "", - '', - '', - "", - elicits("a", "Approve the plan?"), - elicits("b", "Something else"), - "", - "Got: {a.decision} then {b.decision}", - "", - "", - ].join("\n"), - ); + journalCase( + "lets a narrower matcher win when it is declared first", + function* (stream, workspace) { + const result = yield* run( + workspace, + SCHEMA_BLOCK + + [ + "", + '', + '', + "", + elicits("a", "Approve the plan?"), + elicits("b", "Something else"), + "", + "Got: {a.decision} then {b.decision}", + "", + "", + ].join("\n"), + { stream }, + ); - expect(result.output).toContain("Got: narrow then broad"); - }); + expect(result.output).toContain("Got: narrow then broad"); + }, + ); /** A matcher is not consumed by answering: it answers every match it sees. */ - it("reuses one matcher across several elicitations", function* () { - const workspace = yield* useWorkspace(); - + journalCase("reuses one matcher across several elicitations", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -450,15 +458,14 @@ describe("Answers: selection", () => { "", "", ].join("\n"), + { stream }, ); expect(result.failure).toBe(undefined); expect(result.output).toContain("Got: same same same"); }); - it("does not mind a matcher that never fires", function* () { - const workspace = yield* useWorkspace(); - + journalCase("does not mind a matcher that never fires", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -473,37 +480,38 @@ describe("Answers: selection", () => { "", "", ].join("\n"), + { stream }, ); expect(result.failure).toBe(undefined); expect(result.output).toContain("Got: used"); }); - it("still judges a matched value against the asking component's schema", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run( - workspace, - SCHEMA_BLOCK + - [ - "", - '', - "", - elicits("v", "Approve?"), - "", - "", - ].join("\n"), - ); + journalCase( + "still judges a matched value against the asking component's schema", + function* (stream, workspace) { + const result = yield* run( + workspace, + SCHEMA_BLOCK + + [ + "", + '', + "", + elicits("v", "Approve?"), + "", + "", + ].join("\n"), + { stream }, + ); - expect(result.failure).toContain(""); - expect(result.failure).toContain("failed its schema"); - }); + expect(result.failure).toContain(""); + expect(result.failure).toContain("failed its schema"); + }, + ); }); describe("Answers: unmatched elicitations", () => { - it("names the message and every template tried", function* () { - const workspace = yield* useWorkspace(); - + journalCase("names the message and every template tried", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -516,6 +524,7 @@ describe("Answers: unmatched elicitations", () => { "", "", ].join("\n"), + { stream }, ); expect(result.failure).toContain("Something nobody wrote a matcher for"); @@ -523,44 +532,43 @@ describe("Answers: unmatched elicitations", () => { expect(result.failure).toContain('"Reject?"'); }); - it("passes an unmatched elicitation outward when delegate is set", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run( - workspace, - SCHEMA_BLOCK + - [ - "", - '', - "", - elicits("a", "Approve?"), - elicits("b", "The one a person answers"), - "", - "Got: {a.decision} then {b.decision}", - "", - "", - ].join("\n"), - // deno-lint-ignore require-yield - { - outer: function* () { - return { decision: "from-host" }; + journalCase( + "passes an unmatched elicitation outward when delegate is set", + function* (stream, workspace) { + const result = yield* run( + workspace, + SCHEMA_BLOCK + + [ + "", + '', + "", + elicits("a", "Approve?"), + elicits("b", "The one a person answers"), + "", + "Got: {a.decision} then {b.decision}", + "", + "", + ].join("\n"), + { + stream, + outer: function* () { + return { decision: "from-host" }; + }, }, - }, - ); - - expect(result.failure).toBe(undefined); - expect(result.output).toContain("Got: scripted then from-host"); + ); - // The delegated request is the asking component's, unchanged — - // forwards it rather than re-describing it. - expect(result.delegated).toHaveLength(1); - expect(result.delegated[0].message).toContain("The one a person answers"); - expect(result.delegated[0].schema).toEqual(JSON.parse(SCHEMA)); - }); + expect(result.failure).toBe(undefined); + expect(result.output).toContain("Got: scripted then from-host"); - it("does not reach the outer provider without delegate", function* () { - const workspace = yield* useWorkspace(); + // The delegated request is the asking component's, unchanged — + // forwards it rather than re-describing it. + expect(result.delegated).toHaveLength(1); + expect(result.delegated[0].message).toContain("The one a person answers"); + expect(result.delegated[0].schema).toEqual(JSON.parse(SCHEMA)); + }, + ); + journalCase("does not reach the outer provider without delegate", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -572,8 +580,8 @@ describe("Answers: unmatched elicitations", () => { "", "", ].join("\n"), - // deno-lint-ignore require-yield { + stream, outer: function* () { return { decision: "from-host" }; }, @@ -586,9 +594,7 @@ describe("Answers: unmatched elicitations", () => { }); describe("Answers: nesting", () => { - it("lets the nearest region answer first", function* () { - const workspace = yield* useWorkspace(); - + journalCase("lets the nearest region answer first", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -606,41 +612,42 @@ describe("Answers: nesting", () => { "", "", ].join("\n"), + { stream }, ); expect(result.output).toContain("Got: inner"); }); - it("reaches the enclosing region when the inner one delegates", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run( - workspace, - SCHEMA_BLOCK + - [ - "", - '', - "", - "", - '', - "", - elicits("a", "Inner question?"), - elicits("b", "Outer question?"), - "", - "Got: {a.decision} then {b.decision}", - "", - "", - "", - ].join("\n"), - ); - - expect(result.failure).toBe(undefined); - expect(result.output).toContain("Got: from-inner then from-outer"); - }); + journalCase( + "reaches the enclosing region when the inner one delegates", + function* (stream, workspace) { + const result = yield* run( + workspace, + SCHEMA_BLOCK + + [ + "", + '', + "", + "", + '', + "", + elicits("a", "Inner question?"), + elicits("b", "Outer question?"), + "", + "Got: {a.decision} then {b.decision}", + "", + "", + "", + ].join("\n"), + { stream }, + ); - it("stops at the inner region when it does not delegate", function* () { - const workspace = yield* useWorkspace(); + expect(result.failure).toBe(undefined); + expect(result.output).toContain("Got: from-inner then from-outer"); + }, + ); + journalCase("stops at the inner region when it does not delegate", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -656,15 +663,14 @@ describe("Answers: nesting", () => { "", "", ].join("\n"), + { stream }, ); expect(result.failure).toContain("no matcher for this elicitation"); }); /** The region ends with its body, so a later sibling is not answered by it. */ - it("stops answering once its body is over", function* () { - const workspace = yield* useWorkspace(); - + journalCase("stops answering once its body is over", function* (stream, workspace) { const result = yield* run( workspace, SCHEMA_BLOCK + @@ -678,6 +684,7 @@ describe("Answers: nesting", () => { elicits("b", "Outside?"), "", ].join("\n"), + { stream }, ); expect(result.failure).toContain("no elicitation provider configured"); @@ -685,12 +692,11 @@ describe("Answers: nesting", () => { }); describe("Answers: configuration printed errors", () => { - it("refuses an outside an ", function* () { - const workspace = yield* useWorkspace(); - + journalCase("refuses an outside an ", function* (stream, workspace) { const result = yield* run( workspace, '\n', + { stream }, ); expect(reported(result)).toContain(" must be a direct child of "); @@ -715,9 +721,7 @@ describe("Answers: configuration printed errors", () => { expect(reported(selfClosing)).toContain("has no body to answer for"); }); - it("refuses both template forms at once", function* () { - const workspace = yield* useWorkspace(); - + journalCase("refuses both template forms at once", function* (stream, workspace) { const result = yield* run( workspace, [ @@ -728,6 +732,7 @@ describe("Answers: configuration printed errors", () => { "", "", ].join("\n"), + { stream }, ); expect(reported(result)).toContain( @@ -735,9 +740,7 @@ describe("Answers: configuration printed errors", () => { ); }); - it("refuses a template that cannot be parsed", function* () { - const workspace = yield* useWorkspace(); - + journalCase("refuses a template that cannot be parsed", function* (stream, workspace) { const result = yield* run( workspace, [ @@ -748,17 +751,17 @@ describe("Answers: configuration printed errors", () => { "", "", ].join("\n"), + { stream }, ); expect(reported(result)).toContain("adjacent capture holes"); }); - it("refuses a matcher with no value", function* () { - const workspace = yield* useWorkspace(); - + journalCase("refuses a matcher with no value", function* (stream, workspace) { const result = yield* run( workspace, ["", '', "", "body", "", ""].join("\n"), + { stream }, ); expect(reported(result)).toContain('requires a "value" prop'); @@ -769,9 +772,7 @@ describe("Answers: configuration printed errors", () => { * become a match-anything matcher — and first-wins plus reusable would turn * that into permanent shadowing of every matcher below it. */ - it("refuses a template written as an expression", function* () { - const workspace = yield* useWorkspace(); - + journalCase("refuses a template written as an expression", function* (stream, workspace) { const result = yield* run( workspace, [ @@ -786,15 +787,14 @@ describe("Answers: configuration printed errors", () => { "", "", ].join("\n"), + { stream }, ); expect(reported(result)).toContain("template must be a literal string prop"); expect(reported(result)).toContain("{binding} holes"); }); - it("refuses a value that is not JSON", function* () { - const workspace = yield* useWorkspace(); - + journalCase("refuses a value that is not JSON", function* (stream, workspace) { const result = yield* run( workspace, [ @@ -805,6 +805,7 @@ describe("Answers: configuration printed errors", () => { "", "", ].join("\n"), + { stream }, ); expect(reported(result)).toContain("value text is not JSON"); @@ -815,46 +816,50 @@ describe("Answers: configuration printed errors", () => { * `approve`, which is not JSON. The printed error points at the spelling that * works rather than only reporting the parse failure. */ - it("points a bare string value at the JSON-quoted spelling", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run( - workspace, - [ - "", - '', - "", - "body", - "", - "", - ].join("\n"), - ); + journalCase( + "points a bare string value at the JSON-quoted spelling", + function* (stream, workspace) { + const result = yield* run( + workspace, + [ + "", + '', + "", + "body", + "", + "", + ].join("\n"), + { stream }, + ); - expect(reported(result)).toContain("captured JSON text"); - expect(reported(result)).toContain(`value='\"approve\"'`); - }); + expect(reported(result)).toContain("captured JSON text"); + expect(reported(result)).toContain(`value='\"approve\"'`); + }, + ); /** * A malformed matcher stops the region before its body expands: a region that * cannot be trusted to answer should not run something that will ask. */ - it("does not expand the body when a matcher is malformed", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run( - workspace, - [ - "", - '', - "", - "a body nobody should see", - "", - "", - ].join("\n"), - ); + journalCase( + "does not expand the body when a matcher is malformed", + function* (stream, workspace) { + const result = yield* run( + workspace, + [ + "", + '', + "", + "a body nobody should see", + "", + "", + ].join("\n"), + { stream }, + ); - expect(reported(result)).not.toContain("a body nobody should see"); - }); + expect(reported(result)).not.toContain("a body nobody should see"); + }, + ); }); describe("Answers: reservation", () => { @@ -873,30 +878,33 @@ describe("Answers: reservation", () => { yield* writeTextFile(join(workspace, "Answer.md"), "REPOSITORY_ANSWER\n"); } - it("does not let a repository Answers.md stand in for the construct", function* () { - const workspace = yield* useWorkspace(); - yield* writeStandIns(workspace); - - const result = yield* run( - workspace, - SCHEMA_BLOCK + - [ - "", - '', - "", - elicits("v", "Approve?"), - "", - "Got: {v.decision}", - "", - "", - ].join("\n"), - ); + journalCase( + "does not let a repository Answers.md stand in for the construct", + function* (stream, workspace) { + yield* writeStandIns(workspace); + + const result = yield* run( + workspace, + SCHEMA_BLOCK + + [ + "", + '', + "", + elicits("v", "Approve?"), + "", + "Got: {v.decision}", + "", + "", + ].join("\n"), + { stream }, + ); - expect(result.failure).toBe(undefined); - expect(result.output).toContain("Got: supplied"); - expect(result.output).not.toContain("REPOSITORY_ANSWERS"); - expect(result.output).not.toContain("REPOSITORY_ANSWER"); - }); + expect(result.failure).toBe(undefined); + expect(result.output).toContain("Got: supplied"); + expect(result.output).not.toContain("REPOSITORY_ANSWERS"); + expect(result.output).not.toContain("REPOSITORY_ANSWER"); + }, + ); /** * Membership in the reserved set, which nothing above reaches. @@ -932,20 +940,23 @@ describe("Answers: reservation", () => { } }); - it("does not let a repository Answer.md rescue a stray matcher", function* () { - const workspace = yield* useWorkspace(); - yield* writeStandIns(workspace); + journalCase( + "does not let a repository Answer.md rescue a stray matcher", + function* (stream, workspace) { + yield* writeStandIns(workspace); - const result = yield* run( - workspace, - '\n', - ); + const result = yield* run( + workspace, + '\n', + { stream }, + ); - // A reserved name resolves to nothing else wherever it is written, so the - // a misplaced one is still a printed error rather than a component that renders. - expect(reported(result)).toContain(" must be a direct child of "); - expect(result.output).not.toContain("REPOSITORY_ANSWER"); - }); + // A reserved name resolves to nothing else wherever it is written, so the + // a misplaced one is still a printed error rather than a component that renders. + expect(reported(result)).toContain(" must be a direct child of "); + expect(result.output).not.toContain("REPOSITORY_ANSWER"); + }, + ); }); describe("Answers: durability", () => { diff --git a/packages/core/tests/elicit-component.test.ts b/packages/core/tests/elicit-component.test.ts index 23df48b2b..c974a0400 100644 --- a/packages/core/tests/elicit-component.test.ts +++ b/packages/core/tests/elicit-component.test.ts @@ -11,6 +11,7 @@ */ import { beforeAll, describe, it } from "@executablemd/test-support/bdd"; +import { workspaceJournalCases } from "../../test-support/journal-cases.ts"; import { expect } from "@executablemd/test-support/expect"; import { ensure, race, resource, scoped, sleep, suspend, until } from "effection"; import type { Operation } from "effection"; @@ -29,6 +30,12 @@ import type { ElicitationRequest } from "../src/elicitation-api.ts"; import { execute } from "../src/execute.ts"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; +const journalCase = workspaceJournalCases( + "packages/core/tests/elicit-component.test.ts", + "doc.md", + useWorkspace, +); + function useWorkspace(): Operation { return resource(function* (provide) { const root = yield* until(realpath(yield* until(mkdtemp(join(tmpdir(), "elicit-test-"))))); @@ -114,12 +121,16 @@ function run( } /** Execute with no provider installed at all. */ -function runWithoutProvider(workspace: string, source: string): Operation { +function runWithoutProvider( + workspace: string, + source: string, + stream: InMemoryStream, +): Operation { return scoped(function* () { const path = join(workspace, "doc.md"); yield* writeTextFile(path, source); try { - const output = yield* collect(yield* execute({ path, stream: new InMemoryStream() })); + const output = yield* collect(yield* execute({ path, stream })); return { output: String(output), requests: [] }; } catch (error) { return { @@ -163,37 +174,37 @@ function document(body: string, schema: string = DECISION_SCHEMA): string { describe("Elicit: the question", () => { beforeAll(() => useTempFileCompiler()); - it("hands the provider the rendered message and the compiled schema, and nothing else", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run( - workspace, - document("Approve the plan?"), - constant({ decision: "approve" }), - ); - - expect(result.failure).toBe(undefined); - expect(result.requests).toHaveLength(1); - expect(Object.keys(result.requests[0]).sort()).toEqual(["message", "schema"]); - expect(result.requests[0].message).toContain("Approve the plan?"); - expect(result.requests[0].schema).toEqual(JSON.parse(DECISION_SCHEMA)); - expect(result.output).toContain("Decision: approve"); - }); + journalCase( + "hands the provider the rendered message and the compiled schema, and nothing else", + function* (stream, workspace) { + const result = yield* run( + workspace, + document("Approve the plan?"), + constant({ decision: "approve" }), + stream, + ); - it("renders nothing of its own", function* () { - const workspace = yield* useWorkspace(); + expect(result.failure).toBe(undefined); + expect(result.requests).toHaveLength(1); + expect(Object.keys(result.requests[0]).sort()).toEqual(["message", "schema"]); + expect(result.requests[0].message).toContain("Approve the plan?"); + expect(result.requests[0].schema).toEqual(JSON.parse(DECISION_SCHEMA)); + expect(result.output).toContain("Decision: approve"); + }, + ); + journalCase("renders nothing of its own", function* (stream, workspace) { const result = yield* run( workspace, document("Approve the plan?"), constant({ decision: "approve" }), + stream, ); expect(result.output).not.toContain("Approve the plan?"); }); - it("accepts a schema as captured JSON text", function* () { - const workspace = yield* useWorkspace(); + journalCase("accepts a schema as captured JSON text", function* (stream, workspace) { const source = [ "```js eval", `const schemaText = ${JSON.stringify(DECISION_SCHEMA)};`, @@ -205,7 +216,7 @@ describe("Elicit: the question", () => { "", ].join("\n"); - const result = yield* run(workspace, source, constant({ decision: "reject" })); + const result = yield* run(workspace, source, constant({ decision: "reject" }), stream); expect(result.failure).toBe(undefined); expect(result.requests[0].schema).toEqual(JSON.parse(DECISION_SCHEMA)); @@ -216,13 +227,14 @@ describe("Elicit: the question", () => { describe("Elicit: what it refuses", () => { beforeAll(() => useTempFileCompiler()); - it("fails with no provider configured, before asking anything", function* () { - const workspace = yield* useWorkspace(); + journalCase( + "fails with no provider configured, before asking anything", + function* (stream, workspace) { + const result = yield* runWithoutProvider(workspace, document("Approve?"), stream); - const result = yield* runWithoutProvider(workspace, document("Approve?")); - - expect(result.failure?.message).toContain("no elicitation provider configured"); - }); + expect(result.failure?.message).toContain("no elicitation provider configured"); + }, + ); /** * The schema compiles before the body expands, so an unusable schema produces @@ -230,81 +242,87 @@ describe("Elicit: what it refuses", () => { * does not exist is what proves the ordering, where asserting only that the * run failed would pass even if the body had run first. */ - it("compiles the schema before the invocation content expands", function* () { - const workspace = yield* useWorkspace(); - const marker = join(workspace, "expanded.txt"); - const source = [ - "```js eval", - 'const badSchema = {"type":"object","properties":{"decision":{"type":"not-a-type"}}};', - "```", - "", - '', - "", - "```js eval", - `Deno.writeTextFileSync(${JSON.stringify(marker)}, "expanded");`, - "```", - "", - "", - "", - ].join("\n"); - - const result = yield* run(workspace, source, constant({ decision: "approve" })); - - expect(result.failure).toBeDefined(); - expect(result.requests).toHaveLength(0); - expect(yield* exists(marker)).toBe(false); - }); - - it("refuses a schema declaring __proto__ as a name, naming the position", function* () { - const workspace = yield* useWorkspace(); - const schema = '{"type":"object","properties":{"__proto__":{"type":"string"}}}'; + journalCase( + "compiles the schema before the invocation content expands", + function* (stream, workspace) { + const marker = join(workspace, "expanded.txt"); + const source = [ + "```js eval", + 'const badSchema = {"type":"object","properties":{"decision":{"type":"not-a-type"}}};', + "```", + "", + '', + "", + "```js eval", + `Deno.writeTextFileSync(${JSON.stringify(marker)}, "expanded");`, + "```", + "", + "", + "", + ].join("\n"); + + const result = yield* run(workspace, source, constant({ decision: "approve" }), stream); + + expect(result.failure).toBeDefined(); + expect(result.requests).toHaveLength(0); + expect(yield* exists(marker)).toBe(false); + }, + ); - const result = yield* run( - workspace, - document("Approve?", schema), - constant({ decision: "approve" }), - ); + journalCase( + "refuses a schema declaring __proto__ as a name, naming the position", + function* (stream, workspace) { + const schema = '{"type":"object","properties":{"__proto__":{"type":"string"}}}'; - expect(result.failure?.message).toContain("__proto__"); - expect(result.failure?.message).toContain("#/properties"); - expect(result.requests).toHaveLength(0); - }); + const result = yield* run( + workspace, + document("Approve?", schema), + constant({ decision: "approve" }), + stream, + ); - it("refuses a reference that leaves the schema, naming the position", function* () { - const workspace = yield* useWorkspace(); - const schema = '{"type":"object","properties":{"decision":{"$ref":"other.json#/x"}}}'; + expect(result.failure?.message).toContain("__proto__"); + expect(result.failure?.message).toContain("#/properties"); + expect(result.requests).toHaveLength(0); + }, + ); - const result = yield* run( - workspace, - document("Approve?", schema), - constant({ decision: "approve" }), - ); + journalCase( + "refuses a reference that leaves the schema, naming the position", + function* (stream, workspace) { + const schema = '{"type":"object","properties":{"decision":{"$ref":"other.json#/x"}}}'; - expect(result.failure?.message).toContain("other.json#/x"); - expect(result.failure?.message).toContain("#192"); - expect(result.requests).toHaveLength(0); - }); + const result = yield* run( + workspace, + document("Approve?", schema), + constant({ decision: "approve" }), + stream, + ); - it("refuses a schema that is not an object", function* () { - const workspace = yield* useWorkspace(); + expect(result.failure?.message).toContain("other.json#/x"); + expect(result.failure?.message).toContain("#192"); + expect(result.requests).toHaveLength(0); + }, + ); + journalCase("refuses a schema that is not an object", function* (stream, workspace) { const result = yield* run( workspace, document("Approve?", "[1,2]"), constant({ decision: "approve" }), + stream, ); expect(result.failure?.message).toContain("schema must be a JSON Schema object"); expect(result.requests).toHaveLength(0); }); - it("refuses schema text that is not JSON", function* () { - const workspace = yield* useWorkspace(); + journalCase("refuses schema text that is not JSON", function* (stream, workspace) { const source = ['Approve?', ""].join( "\n", ); - const result = yield* run(workspace, source, constant({ decision: "approve" })); + const result = yield* run(workspace, source, constant({ decision: "approve" }), stream); expect(result.failure?.message).toContain("schema text is not JSON"); expect(result.requests).toHaveLength(0); @@ -314,19 +332,23 @@ describe("Elicit: what it refuses", () => { describe("Elicit: judging the answer", () => { beforeAll(() => useTempFileCompiler()); - it("validates the provider's answer against the same schema", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run(workspace, document("Approve?"), constant({ decision: "maybe" })); - - expect(result.failure?.message).toContain("failed its schema"); - expect(result.failure?.message).toContain("decision"); - }); + journalCase( + "validates the provider's answer against the same schema", + function* (stream, workspace) { + const result = yield* run( + workspace, + document("Approve?"), + constant({ decision: "maybe" }), + stream, + ); - it("fails once, without asking a second time", function* () { - const workspace = yield* useWorkspace(); + expect(result.failure?.message).toContain("failed its schema"); + expect(result.failure?.message).toContain("decision"); + }, + ); - const result = yield* run(workspace, document("Approve?"), constant({ wrong: true })); + journalCase("fails once, without asking a second time", function* (stream, workspace) { + const result = yield* run(workspace, document("Approve?"), constant({ wrong: true }), stream); expect(result.failure).toBeDefined(); expect(result.requests).toHaveLength(1); @@ -366,35 +388,37 @@ describe("Elicit: judging the answer", () => { ]); }); - it("renders those issues into the printed error a document sees", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run(workspace, document("Approve?"), constant({ decision: 7 })); + journalCase( + "renders those issues into the printed error a document sees", + function* (stream, workspace) { + const result = yield* run(workspace, document("Approve?"), constant({ decision: 7 }), stream); - expect(result.failure?.message).toContain(""); - expect(result.failure?.message).toContain('"/decision" must be string'); - }); + expect(result.failure?.message).toContain(""); + expect(result.failure?.message).toContain('"/decision" must be string'); + }, + ); /** * A provider's own failure travels verbatim. Wrapping it would replace the * only description of what actually went wrong — the provider knows why it * could not reach anyone and `` does not. */ - it("propagates a provider failure rather than swallowing it", function* () { - const workspace = yield* useWorkspace(); - - const result = yield* run( - workspace, - document("Approve?"), - // deno-lint-ignore require-yield - function* () { - throw new Error("the provider could not reach anyone"); - }, - ); + journalCase( + "propagates a provider failure rather than swallowing it", + function* (stream, workspace) { + const result = yield* run( + workspace, + document("Approve?"), + function* () { + throw new Error("the provider could not reach anyone"); + }, + stream, + ); - expect(result.failure?.message).toBe("the provider could not reach anyone"); - expect(result.output).toBe(""); - }); + expect(result.failure?.message).toBe("the provider could not reach anyone"); + expect(result.output).toBe(""); + }, + ); }); describe("Elicit: the provider is contextual", () => { diff --git a/packages/core/tests/fail-component.test.ts b/packages/core/tests/fail-component.test.ts index fef30901d..2e7544733 100644 --- a/packages/core/tests/fail-component.test.ts +++ b/packages/core/tests/fail-component.test.ts @@ -16,6 +16,7 @@ */ import { describe, it } from "@executablemd/test-support/bdd"; +import { workspaceJournalCases } from "../../test-support/journal-cases.ts"; import { expect } from "@executablemd/test-support/expect"; import { ensure, resource, scoped, until } from "effection"; import type { Operation, Result } from "effection"; @@ -54,6 +55,12 @@ interface Run { events: DurableEvent[]; } +const journalCase = workspaceJournalCases( + "packages/core/tests/fail-component.test.ts", + "doc.md", + useDir, +); + function useDir(): Operation { return resource(function* (provide) { const dir = yield* until(mkdtemp(join(tmpdir(), "xmd-fail-"))); @@ -172,50 +179,56 @@ const MISSING_RETURN = "The root document declares `returns` but produced no { - it("FAIL1: ends a plain root with the authored message and runs no later sibling", function* () { - const dir = yield* useDir(); - const result = yield* run( - dir, - [ - "before", - "", - '', - "", - '', - "", - ].join("\n"), - ); - - // The authored sentence is the outcome, unprefixed and unclassified. - expect(failureOf(result).message).toBe("Review aborted; nothing was saved."); - // Text before it had already streamed; the component itself rendered none. - expect(result.output).toBe("before\n\n"); - expect(result.ran).toEqual([]); - // Nothing printed it: an unmarked component leaves recovery to the region. - expect(result.observed).toEqual([]); - }); + journalCase( + "FAIL1: ends a plain root with the authored message and runs no later sibling", + function* (stream, dir) { + const result = yield* run( + dir, + [ + "before", + "", + '', + "", + '', + "", + ].join("\n"), + { stream }, + ); - it("FAIL2: fails a value root instead of reporting a missing ", function* () { - const dir = yield* useDir(); - const result = yield* run( - dir, - [ - VALUE_ROOT, - '', - "", - '', - "", - ].join("\n"), - ); + // The authored sentence is the outcome, unprefixed and unclassified. + expect(failureOf(result).message).toBe("Review aborted; nothing was saved."); + // Text before it had already streamed; the component itself rendered none. + expect(result.output).toBe("before\n\n"); + expect(result.ran).toEqual([]); + // Nothing printed it: an unmarked component leaves recovery to the region. + expect(result.observed).toEqual([]); + }, + ); - const failure = failureOf(result); - // The authored error itself, by identity, rather than a message that reads - // like it. - expect(reaches(failure, offeredByFail(result).error)).toBe(true); - expect(failure.message).toBe("No candidate was approvable."); - expect(failure.message).not.toBe(MISSING_RETURN); - expect(everythingSaid(result)).not.toContain("produced no value"); - }); + journalCase( + "FAIL2: fails a value root instead of reporting a missing ", + function* (stream, dir) { + const result = yield* run( + dir, + [ + VALUE_ROOT, + '', + "", + '', + "", + ].join("\n"), + { stream }, + ); + + const failure = failureOf(result); + // The authored error itself, by identity, rather than a message that reads + // like it. + expect(reaches(failure, offeredByFail(result).error)).toBe(true); + expect(failure.message).toBe("No candidate was approvable."); + expect(failure.message).not.toBe(MISSING_RETURN); + expect(everythingSaid(result)).not.toContain("produced no value"); + }, + ); it("FAIL3: does nothing beneath an unselected , and the root returns", function* () { const dir = yield* useDir(); @@ -239,61 +252,66 @@ describe("Tier FAIL — stopping a document deliberately", () => { expect(importedNames(result.events)).not.toContain("Fail"); }); - it("FAIL4: names loop exhaustion after the loop reached its own max", function* () { - const dir = yield* useDir(); - const result = yield* run( - dir, - [ - VALUE_ROOT, - '', - "", - '', - "", - '', - "", - '', - "", - ].join("\n"), - ); - - // The loop finished normally; the failure is the sibling chosen after it. - expect(result.ran).toEqual(["attempt", "attempt"]); - expect(failureOf(result).message).toBe( - "No attempt produced an approvable candidate in 2 tries.", - ); - expect(result.ran).not.toContain("after"); - expect(everythingSaid(result)).not.toContain("produced no value"); - }); - - it("FAIL5: is recovered by an authored in a text root, once", function* () { - const dir = yield* useDir(); - const result = yield* run( - dir, - [ - "", - '', - "", - "", - '', - "tail", - "", - ].join("\n"), - ); + journalCase( + "FAIL4: names loop exhaustion after the loop reached its own max", + function* (stream, dir) { + const result = yield* run( + dir, + [ + VALUE_ROOT, + '', + "", + '', + "", + '', + "", + '', + "", + ].join("\n"), + { stream }, + ); + + // The loop finished normally; the failure is the sibling chosen after it. + expect(result.ran).toEqual(["attempt", "attempt"]); + expect(failureOf(result).message).toBe( + "No attempt produced an approvable candidate in 2 tries.", + ); + expect(result.ran).not.toContain("after"); + expect(everythingSaid(result)).not.toContain("produced no value"); + }, + ); - expect(result.outcome.ok).toBe(true); - // Reported exactly once, as an ordinary function-component diagnostic. - expect(result.observed.map((segment) => segment.message)).toEqual([ - "Function component Fail error: This region was abandoned.", - ]); - // Later siblings run, and the component contributed nothing but that one - // printed error — the sentence appears exactly once in what the reader saw. - expect(result.ran).toEqual(["after"]); - expect(result.output).toContain("tail"); - expect(result.output.split("This region was abandoned.").length - 1).toBe(1); - }); + journalCase( + "FAIL5: is recovered by an authored in a text root, once", + function* (stream, dir) { + const result = yield* run( + dir, + [ + "", + '', + "", + "", + '', + "tail", + "", + ].join("\n"), + { stream }, + ); + + expect(result.outcome.ok).toBe(true); + // Reported exactly once, as an ordinary function-component diagnostic. + expect(result.observed.map((segment) => segment.message)).toEqual([ + "Function component Fail error: This region was abandoned.", + ]); + // Later siblings run, and the component contributed nothing but that one + // printed error — the sentence appears exactly once in what the reader saw. + expect(result.ran).toEqual(["after"]); + expect(result.output).toContain("tail"); + expect(result.output.split("This region was abandoned.").length - 1).toBe(1); + }, + ); - it("FAIL6: is not recovered by in a value root", function* () { - const dir = yield* useDir(); + journalCase("FAIL6: is not recovered by in a value root", function* (stream, dir) { const result = yield* run( dir, [ @@ -305,6 +323,7 @@ describe("Tier FAIL — stopping a document deliberately", () => { '', "", ].join("\n"), + { stream }, ); const failure = failureOf(result); @@ -374,29 +393,31 @@ describe("Tier FAIL — invocations that never raise the authored message", () = }); describe("Tier FAIL — position, durability and precedence", () => { - it("FAIL8: positions the failure at the opening tag it was written on", function* () { - const dir = yield* useDir(); - const lines = [ - "# Review", - "", - "some prose", - "", - '', - "", - ]; - const source = lines.join("\n"); - const result = yield* run(dir, source); - - const failure = offeredByFail(result); - expect(failure.name).toBe("Fail"); - expect(failure.error.message).toBe("Stopped at line five."); - expect(failure.position).toEqual({ - path: join(dir, "doc.md"), - offset: source.indexOf("', + "", + ]; + const source = lines.join("\n"); + const result = yield* run(dir, source, { stream }); + + const failure = offeredByFail(result); + expect(failure.name).toBe("Fail"); + expect(failure.error.message).toBe("Stopped at line five."); + expect(failure.position).toEqual({ + path: join(dir, "doc.md"), + offset: source.indexOf(" join(tmpdir(), directoryPrefix + randomUUID())), + ); +} + +/** Use the file identity chosen by a case's existing workspace fixture. */ +export function workspaceJournalCases( + owner: string, + filename: string, + workspace: () => Operation, +) { return ( name: string, body: (stream: InMemoryStream, directory: string) => Operation, ): void => { - it(name, () => { - const directory = join(tmpdir(), directoryPrefix + randomUUID()); - return captureTestJournal({ owner, name }, join(directory, filename), (stream) => + it(name, function* () { + const directory = yield* workspace(); + yield* captureTestJournal({ owner, name }, join(directory, filename), (stream) => body(stream, directory), ); }); From 468000cc144ec047a44ca641fd71d217b02f3180 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:41:40 -0500 Subject: [PATCH 20/78] test: attribute fresh TestAgent component and launch journals --- packages/test-agent/tests/components.test.ts | 698 ++++++++++-------- .../test-agent/tests/native-launch.test.ts | 433 ++++++----- 2 files changed, 641 insertions(+), 490 deletions(-) diff --git a/packages/test-agent/tests/components.test.ts b/packages/test-agent/tests/components.test.ts index 263375092..560f5cbb0 100644 --- a/packages/test-agent/tests/components.test.ts +++ b/packages/test-agent/tests/components.test.ts @@ -5,6 +5,7 @@ * clean suspension at teardown — driven through the component surface * with real workers. */ +import { fileJournalCases } from "../../test-support/journal-cases.ts"; import { describe, it, beforeAll } from "@executablemd/test-support/bdd"; import { useTempFileCompiler } from "@executablemd/core"; import { expect } from "@executablemd/test-support/expect"; @@ -55,8 +56,18 @@ interface RunOptions { cwdRef?: { value: string; flipTo: string }; } -function* runDoc(files: Record, options?: RunOptions): Operation { - const dir = path.join(os.tmpdir(), `xmd-tv-${randomUUID()}`); +const journalCase = fileJournalCases( + "packages/test-agent/tests/components.test.ts", + "xmd-tv-", + "doc.md", +); + +function* runDoc( + files: Record, + options?: RunOptions, + stream = new InMemoryStream(), + dir = path.join(os.tmpdir(), `xmd-tv-${randomUUID()}`), +): Operation { yield* ensureDir(dir); return yield* scoped(function* () { yield* ensure(() => rm(dir, { recursive: true, force: true })); @@ -102,7 +113,7 @@ function* runDoc(files: Record, options?: RunOptions): Operation const execution = yield* executeInstalled( { path: path.join(dir, "doc.md"), - stream: new InMemoryStream(), + stream, ...(options?.includes ? { includes: options.includes.map((d) => path.join(dir, d)) } : {}), @@ -173,96 +184,130 @@ describe("Tier TV — TestAgent components", { sanitizeOps: false, sanitizeResou } }); - it("fails the owning Test when actual prompt configuration violates a constraint", function* () { - const run = yield* runDoc({ - "hi.md": '\n\nwrong\n', - "doc.md": - '\n\n\nhi\n\n\n', - }); - expect(run.results.map((result) => result.status)).toEqual(["fail"]); - expect(run.output).toContain("Prompt configuration does not match"); - }); - - it("TV1: outside an active testing session is a configuration error", function* () { - const run = yield* runDoc( - { "doc.md": "\nbody\n\n" }, - { session: false }, - ); - // Nothing recovers the configuration error, so it is the run's outcome. - expect(run.result.ok).toBe(false); - expect(run.result.ok ? "" : run.result.error.message).toContain( - "valid only in an active testing session", - ); - }); - - it("TV12: a configuration diagnostic is observed once and rendered once", function* () { - const observed: string[] = []; - yield* Component.around({ - *raise([error], next) { - observed.push(error.message); - return yield* next(error); - }, - }); - // Written in a region that prints: what this pins is that the diagnostic - // is observed once and rendered once, which needs it rendered. - const run = yield* runDoc( - { "doc.md": "\n\nbody\n\n\n" }, - { session: false }, - ); - expect(observed).toHaveLength(1); - expect(observed[0]).toContain("valid only in an active testing session"); - expect(run.output.match(/valid only in an active testing session/g)).toHaveLength(1); - }); - - it("TV2: missing and duplicate mappings fail the owning test before the turn", function* () { - const run = yield* runDoc({ - "agents/hi.md": HI, - "doc.md": [ - "", - ' ', - ' ', - ' ', - ' ', - " ", - ' ', - ' ', - " ", - "", - "", - ].join("\n"), - }); - expect(run.results.map((entry) => entry.status)).toEqual(["fail", "fail"]); - // Both refusals name the agent and the session they are about, so a reader - // of a failing suite knows which mapping to write or remove. - expect(run.output).toContain( - 'No was found for agent "test" and session "unmapped".', - ); - expect(run.output).toContain( - 'More than one was declared for agent "test" and session "dup".', - ); - }); + journalCase( + "fails the owning Test when actual prompt configuration violates a constraint", + function* (stream, directory) { + const run = yield* runDoc( + { + "hi.md": '\n\nwrong\n', + "doc.md": + '\n\n\nhi\n\n\n', + }, + undefined, + stream, + directory, + ); + expect(run.results.map((result) => result.status)).toEqual(["fail"]); + expect(run.output).toContain("Prompt configuration does not match"); + }, + ); + + journalCase( + "TV1: outside an active testing session is a configuration error", + function* (stream, directory) { + const run = yield* runDoc( + { "doc.md": "\nbody\n\n" }, + { session: false }, + stream, + directory, + ); + // Nothing recovers the configuration error, so it is the run's outcome. + expect(run.result.ok).toBe(false); + expect(run.result.ok ? "" : run.result.error.message).toContain( + "valid only in an active testing session", + ); + }, + ); + + journalCase( + "TV12: a configuration diagnostic is observed once and rendered once", + function* (stream, directory) { + const observed: string[] = []; + yield* Component.around({ + *raise([error], next) { + observed.push(error.message); + return yield* next(error); + }, + }); + // Written in a region that prints: what this pins is that the diagnostic + // is observed once and rendered once, which needs it rendered. + const run = yield* runDoc( + { "doc.md": "\n\nbody\n\n\n" }, + { session: false }, + stream, + directory, + ); + expect(observed).toHaveLength(1); + expect(observed[0]).toContain("valid only in an active testing session"); + expect(run.output.match(/valid only in an active testing session/g)).toHaveLength(1); + }, + ); + + journalCase( + "TV2: missing and duplicate mappings fail the owning test before the turn", + function* (stream, directory) { + const run = yield* runDoc( + { + "agents/hi.md": HI, + "doc.md": [ + "", + ' ', + ' ', + ' ', + ' ', + " ", + ' ', + ' ', + " ", + "", + "", + ].join("\n"), + }, + undefined, + stream, + directory, + ); + expect(run.results.map((entry) => entry.status)).toEqual(["fail", "fail"]); + // Both refusals name the agent and the session they are about, so a reader + // of a failing suite knows which mapping to write or remove. + expect(run.output).toContain( + 'No was found for agent "test" and session "unmapped".', + ); + expect(run.output).toContain( + 'More than one was declared for agent "test" and session "dup".', + ); + }, + ); - it("TV3: each gets fresh state; a mismatch fails only its owning test", function* () { - const run = yield* runDoc({ - "agents/hi.md": HI, - "doc.md": [ - "", - ' ', - ' ', - ' ', - " ", - ' ', - ' ', - ' ', - " ", - "", - "", - ].join("\n"), - }); - expect(run.results.map((entry) => entry.status)).toEqual(["fail", "pass"]); - expect(run.output).toContain("expected template: hi"); - expect(run.output).toContain("actual prompt: wrong"); - }); + journalCase( + "TV3: each gets fresh state; a mismatch fails only its owning test", + function* (stream, directory) { + const run = yield* runDoc( + { + "agents/hi.md": HI, + "doc.md": [ + "", + ' ', + ' ', + ' ', + " ", + ' ', + ' ', + ' ', + " ", + "", + "", + ].join("\n"), + }, + undefined, + stream, + directory, + ); + expect(run.results.map((entry) => entry.status)).toEqual(["fail", "pass"]); + expect(run.output).toContain("expected template: hi"); + expect(run.output).toContain("actual prompt: wrong"); + }, + ); it("TV4: non-whitespace pre-matcher output and eval imports are configuration failures", function* () { const preMatcher = yield* runDoc({ @@ -375,224 +420,285 @@ describe("Tier TV — TestAgent components", { sanitizeOps: false, sanitizeResou expect(typescript.results.map((entry) => entry.status)).toEqual(["fail"]); }); - it("TV6: default and named mappings resolve; the agent prop registers additional agents", function* () { - // One per mapping: each prompt spawns a worker, and under Node a - // spawn costs enough that three inside one brush the fixed - // 20-second test timeout on a loaded runner (#332). Splitting keeps every - // test far from the deadline and names the mapping that failed. - const run = yield* runDoc({ - "agents/default.md": '\n\ndefault-reply\n', - "agents/named.md": '\n\nnamed-reply\n', - "agents/extra.md": '\n\nextra-reply\n', - "doc.md": [ - "", - ' ', - ' ', - ' ', - ' ', - ' ', - ' ', - " ", - ' ', - ' ', - ' ', - " ", - ' ', - ' ', - ' ', - " ", - "", - "", - ].join("\n"), - }); - expect(run.results.map((entry) => entry.status)).toEqual(["pass", "pass", "pass"]); - }); - - it("TV7: different working directories get independent scenario scenarios", function* () { - const cwdRef = { value: path.resolve("."), flipTo: os.tmpdir() }; - const run = yield* runDoc( - { - "agents/hi.md": HI, - "doc.md": [ - "", - ' ', - ' ', - ' ', - "", - "```bash exec silent", - "flip-cwd", - "```", - "", - ' ', - ' ', - ' ', - " ", - "", - "", - ].join("\n"), - }, - { cwdRef }, - ); - // The same stage-1 prompt matched twice: the flipped cwd allocated a - // fresh scenario instead of reusing (and exhausting) the first one. - expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); - }); - - it("TV8: exhaustion fails the owning test; a suspended scenario tears down cleanly", function* () { - const run = yield* runDoc({ - "agents/hi.md": HI, - "agents/two.md": TWO_STAGES, - "doc.md": [ - "", - ' ', - ' ', - ' ', - ' ', - ' ', - " ", - ' ', - ' ', - ' ', - " ", - "", - "", - "after the agent scope", - "", - ].join("\n"), - }); - expect(run.results.map((entry) => entry.status)).toEqual(["fail", "pass"]); - expect(run.output).toContain("scenario exhausted"); - // Clean teardown: the suspended second scenario did not fail the - // document, and content after the boundary still rendered. - expect(run.output).toContain("after the agent scope"); - expect(run.result.ok).toBe(false); - }); - - it("TV9: the behavior document executes from the declaration snapshot", function* () { - const dirToken = `xmd-snap-${randomUUID()}`; - const run = yield* runDoc({ - "agents/hi.md": HI, - "doc.md": [ - "", - ' ', - "", - "```bash exec silent", - `rm __DIR__/agents/hi.md || true # ${dirToken}`, - "```", - "", - ' ', - ' ', - ' ', - " ", - "", - "", - ].join("\n"), - }); - expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); - }); - - it("TV10: / pin a resolved session that routes nested prompts", function* () { - const run = yield* runDoc({ - "agents/two.md": TWO_STAGES, - "doc.md": [ - "", - ' ', - ' ', - ' ', - ' ', - ' ', - ' ', - " ", - " ", - ' ', - ' ', - " ", - "", - "", - ].join("\n"), - }); - // Both prompts routed through the Session object pinned by - // to the same scenario, so stage 2 matched after stage 1. - expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); - }); - - it("TV11: a pinned session is rejected for an agent that did not create it", function* () { - const run = yield* runDoc({ - "agents/owner.md": '\n\nowner-reply\n', - "agents/other.md": '\n\nother-reply\n', - "doc.md": [ - "", - ' ', - ' ', - ' ', - ' ', - ' ', - ' ', - ' ', - " ", - " ", - " ", - " ", - "", - "", - ].join("\n"), - }); - expect(run.results.map((entry) => entry.status)).toEqual(["fail"]); - expect(run.output).toContain('agent "extra" does not match session'); - // Neither agent's scenario advanced: no turn ran on either. - expect(run.output).not.toContain("owner-reply"); - expect(run.output).not.toContain("other-reply"); - }); + journalCase( + "TV6: default and named mappings resolve; the agent prop registers additional agents", + function* (stream, directory) { + // One per mapping: each prompt spawns a worker, and under Node a + // spawn costs enough that three inside one brush the fixed + // 20-second test timeout on a loaded runner (#332). Splitting keeps every + // test far from the deadline and names the mapping that failed. + const run = yield* runDoc( + { + "agents/default.md": '\n\ndefault-reply\n', + "agents/named.md": '\n\nnamed-reply\n', + "agents/extra.md": '\n\nextra-reply\n', + "doc.md": [ + "", + ' ', + ' ', + ' ', + ' ', + ' ', + ' ', + " ", + ' ', + ' ', + ' ', + " ", + ' ', + ' ', + ' ', + " ", + "", + "", + ].join("\n"), + }, + undefined, + stream, + directory, + ); + expect(run.results.map((entry) => entry.status)).toEqual(["pass", "pass", "pass"]); + }, + ); + + journalCase( + "TV7: different working directories get independent scenario scenarios", + function* (stream, directory) { + const cwdRef = { value: path.resolve("."), flipTo: os.tmpdir() }; + const run = yield* runDoc( + { + "agents/hi.md": HI, + "doc.md": [ + "", + ' ', + ' ', + ' ', + "", + "```bash exec silent", + "flip-cwd", + "```", + "", + ' ', + ' ', + ' ', + " ", + "", + "", + ].join("\n"), + }, + { cwdRef }, + stream, + directory, + ); + // The same stage-1 prompt matched twice: the flipped cwd allocated a + // fresh scenario instead of reusing (and exhausting) the first one. + expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); + }, + ); + + journalCase( + "TV8: exhaustion fails the owning test; a suspended scenario tears down cleanly", + function* (stream, directory) { + const run = yield* runDoc( + { + "agents/hi.md": HI, + "agents/two.md": TWO_STAGES, + "doc.md": [ + "", + ' ', + ' ', + ' ', + ' ', + ' ', + " ", + ' ', + ' ', + ' ', + " ", + "", + "", + "after the agent scope", + "", + ].join("\n"), + }, + undefined, + stream, + directory, + ); + expect(run.results.map((entry) => entry.status)).toEqual(["fail", "pass"]); + expect(run.output).toContain("scenario exhausted"); + // Clean teardown: the suspended second scenario did not fail the + // document, and content after the boundary still rendered. + expect(run.output).toContain("after the agent scope"); + expect(run.result.ok).toBe(false); + }, + ); + + journalCase( + "TV9: the behavior document executes from the declaration snapshot", + function* (stream, directory) { + const dirToken = `xmd-snap-${randomUUID()}`; + const run = yield* runDoc( + { + "agents/hi.md": HI, + "doc.md": [ + "", + ' ', + "", + "```bash exec silent", + `rm __DIR__/agents/hi.md || true # ${dirToken}`, + "```", + "", + ' ', + ' ', + ' ', + " ", + "", + "", + ].join("\n"), + }, + undefined, + stream, + directory, + ); + expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); + }, + ); + + journalCase( + "TV10: / pin a resolved session that routes nested prompts", + function* (stream, directory) { + const run = yield* runDoc( + { + "agents/two.md": TWO_STAGES, + "doc.md": [ + "", + ' ', + ' ', + ' ', + ' ', + ' ', + ' ', + " ", + " ", + ' ', + ' ', + " ", + "", + "", + ].join("\n"), + }, + undefined, + stream, + directory, + ); + // Both prompts routed through the Session object pinned by + // to the same scenario, so stage 2 matched after stage 1. + expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); + }, + ); + + journalCase( + "TV11: a pinned session is rejected for an agent that did not create it", + function* (stream, directory) { + const run = yield* runDoc( + { + "agents/owner.md": '\n\nowner-reply\n', + "agents/other.md": '\n\nother-reply\n', + "doc.md": [ + "", + ' ', + ' ', + ' ', + ' ', + ' ', + ' ', + ' ', + " ", + " ", + " ", + " ", + "", + "", + ].join("\n"), + }, + undefined, + stream, + directory, + ); + expect(run.results.map((entry) => entry.status)).toEqual(["fail"]); + expect(run.output).toContain('agent "extra" does not match session'); + // Neither agent's scenario advanced: no turn ran on either. + expect(run.output).not.toContain("owner-reply"); + expect(run.output).not.toContain("other-reply"); + }, + ); // The regression the scoped() removal fixes: content projected by // tryContent() anchors to the invocation, so anything installs // inside a child frame is invisible to its own body. Wrapping the region in // scoped() again turns every scenario into "valid only inside " // and every prompt into "Agent.agent() has no provider". - it("TV13: a scenario in the body sees the session installed", function* () { - const run = yield* runDoc({ - "agents/hi.md": HI, - "doc.md": [ - "", - '', - '', - "", - "", - ].join("\n"), - }); + journalCase( + "TV13: a scenario in the body sees the session installed", + function* (stream, directory) { + const run = yield* runDoc( + { + "agents/hi.md": HI, + "doc.md": [ + "", + '', + '', + "", + "", + ].join("\n"), + }, + undefined, + stream, + directory, + ); - expect(run.output).not.toContain("is valid only inside "); - expect(run.output).not.toContain("has no provider"); - expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); - }); + expect(run.output).not.toContain("is valid only inside "); + expect(run.output).not.toContain("has no provider"); + expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); + }, + ); // TC1's analog: a settled diagnostic beside healthy scenarios renders inline // and the rest of the body still runs. content() would replace the whole // invocation's output with that diagnostic instead. The empty-string src also // pins that the component's own check still owns that wording — the schema // accepts "" as a string, so only the fn can catch it. - it("TV14: a scenario diagnostic renders inline beside a healthy one", function* () { - const run = yield* runDoc({ - "agents/hi.md": HI, - // The region prints, which is what lets the rest of the body run after - // the scenario's own diagnostic. - "doc.md": [ - "", - "", - '', - '', - "BODY TEXT", - '', - "", - "", - "", - ].join("\n"), - }); + journalCase( + "TV14: a scenario diagnostic renders inline beside a healthy one", + function* (stream, directory) { + const run = yield* runDoc( + { + "agents/hi.md": HI, + // The region prints, which is what lets the rest of the body run after + // the scenario's own diagnostic. + "doc.md": [ + "", + "", + '', + '', + "BODY TEXT", + '', + "", + "", + "", + ].join("\n"), + }, + undefined, + stream, + directory, + ); - expect(run.output).toContain('requires a "src" prop'); - expect(run.output).toContain("BODY TEXT"); - expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); - }); + expect(run.output).toContain('requires a "src" prop'); + expect(run.output).toContain("BODY TEXT"); + expect(run.results.map((entry) => entry.status)).toEqual(["pass"]); + }, + ); // A registration is a default, so a repository component of either name wins. // Each fixture declares a props schema: a markdown component without one diff --git a/packages/test-agent/tests/native-launch.test.ts b/packages/test-agent/tests/native-launch.test.ts index c8b1c64fa..da86a6cce 100644 --- a/packages/test-agent/tests/native-launch.test.ts +++ b/packages/test-agent/tests/native-launch.test.ts @@ -14,6 +14,7 @@ * asserts "no hidden prompt" by the answer that later prompt gets, not by an * absence. */ +import { fileJournalCases } from "../../test-support/journal-cases.ts"; import { beforeAll, describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { useTempFileCompiler } from "@executablemd/core"; @@ -60,8 +61,17 @@ interface RunOptions { hostLauncher?: (request: NativeLaunchRequest) => void; } -function* runDoc(doc: string, options: RunOptions = {}): Operation { - const dir = path.join(os.tmpdir(), `xmd-tl-${randomUUID()}`); +const journalCase = fileJournalCases( + "packages/test-agent/tests/native-launch.test.ts", + "xmd-tl-", + "doc.md", +); + +function* runDoc( + doc: string, + options: RunOptions = {}, + dir = path.join(os.tmpdir(), `xmd-tl-${randomUUID()}`), +): Operation { yield* ensureDir(dir); const launches: NativeLaunchRequest[] = []; const sessions: NativeSessionReport[] = []; @@ -205,16 +215,23 @@ describe( expect(instructions).not.toContain("TestAgent"); }); - it("TL2: the native UI is started with the identity the agent asserted", function* () { - const run = yield* runDoc(testDoc(LAUNCH_BODY)); - - expect(run.launches.length).toBe(1); - const nativeSessionId = run.sessions.at(-1)!.nativeSessionId; - expect(nativeSessionId.startsWith("native-")).toBe(true); - expect(run.launches[0]?.command).toEqual(["xmd-test-agent-ui", "--resume", nativeSessionId]); - // And the retained record names that same identity. - expect(preparedRecords(run.events)[0]?.nativeSessionId).toBe(nativeSessionId); - }); + journalCase( + "TL2: the native UI is started with the identity the agent asserted", + function* (stream, directory) { + const run = yield* runDoc(testDoc(LAUNCH_BODY), { stream }, directory); + + expect(run.launches.length).toBe(1); + const nativeSessionId = run.sessions.at(-1)!.nativeSessionId; + expect(nativeSessionId.startsWith("native-")).toBe(true); + expect(run.launches[0]?.command).toEqual([ + "xmd-test-agent-ui", + "--resume", + nativeSessionId, + ]); + // And the retained record names that same identity. + expect(preparedRecords(run.events)[0]?.nativeSessionId).toBe(nativeSessionId); + }, + ); it("TL3: raw prepared instructions never reach argv or environment", function* () { const run = yield* runDoc(testDoc(LAUNCH_BODY)); @@ -224,197 +241,225 @@ describe( expect(JSON.stringify(request.env ?? {})).not.toContain("repository implementor"); }); - it("TL5: a later prompt reattaches to the session the native UI was given", function* () { - const run = yield* runDoc( - testDoc( + journalCase( + "TL5: a later prompt reattaches to the session the native UI was given", + function* (stream, directory) { + const run = yield* runDoc( + testDoc( + [ + LAUNCH_BODY, + "", + '', + "what changed?", + "", + ].join("\n"), + ), + { stream }, + directory, + ); + + expect(run.result.ok).toBe(true); + // Reattaching re-establishes the session rather than reusing the handle + // that predates the handoff, and it lands on the provider-native state the + // launch retained. + const launched = preparedRecords(run.events)[0]?.nativeSessionId; + expect(launched).toBeDefined(); + expect(run.sessions.at(-1)?.nativeSessionId).toBe(launched); + }, + ); + + journalCase( + "TL6: a nonzero native exit fails the test that launched", + function* (stream, directory) { + const run = yield* runDoc(testDoc(LAUNCH_BODY), { stream, exitCode: 4 }, directory); + + expect(run.results.some((result) => result.status === "fail")).toBe(true); + // The provider session facts survive the failure. + expect(preparedRecords(run.events)[0]?.nativeSessionId).toBeDefined(); + }, + ); + + journalCase( + "TL7: a launch under never reaches the host's launcher", + function* (stream, directory) { + // The host has one, and it is the wrong one to reach: a scripted agent's + // native UI does not exist, and the terminal a host would hand it belongs + // to whoever is running the tests. Under `xmd test` there is no host + // launcher at all, which is the same fact from the other side. + const hostReached: NativeLaunchRequest[] = []; + const run = yield* runDoc( + testDoc(LAUNCH_BODY), + { stream, hostLauncher: (request) => hostReached.push(request) }, + directory, + ); + + expect(run.result.ok ? "" : run.result.error.message).toBe(""); + expect(hostReached).toEqual([]); + // The component's own launcher took it instead. + expect(run.launches.length).toBe(1); + }, + ); + + journalCase( + "TL9: two sibling tests naming one session each get a session of their own", + function* (stream, directory) { + // Identical agent, identical session name, identical cwd — so the natural + // key a coordinator would exclude on is the same for both. What keeps + // them apart is that each `` owns a complete provider partition, + // with its own runtime, store, managed sessions, scenarios and + // coordinator. Two sessions, not two owners of one. + // + // The layers differ deliberately: identical ones would resume, and a + // shared partition would then look like an isolated pair. + const run = yield* runDoc( [ - LAUNCH_BODY, + "", + '', + "", + '', + '', + "You are the repository implementor.", + "", + '', + "what changed?", + "", + "", "", + '', + '', + "You are the repository reviewer.", + "", '', "what changed?", "", + "", + "", + "", ].join("\n"), - ), - ); - - expect(run.result.ok).toBe(true); - // Reattaching re-establishes the session rather than reusing the handle - // that predates the handoff, and it lands on the provider-native state the - // launch retained. - const launched = preparedRecords(run.events)[0]?.nativeSessionId; - expect(launched).toBeDefined(); - expect(run.sessions.at(-1)?.nativeSessionId).toBe(launched); - }); - - it("TL6: a nonzero native exit fails the test that launched", function* () { - const run = yield* runDoc(testDoc(LAUNCH_BODY), { exitCode: 4 }); - - expect(run.results.some((result) => result.status === "fail")).toBe(true); - // The provider session facts survive the failure. - expect(preparedRecords(run.events)[0]?.nativeSessionId).toBeDefined(); - }); - - it("TL7: a launch under never reaches the host's launcher", function* () { - // The host has one, and it is the wrong one to reach: a scripted agent's - // native UI does not exist, and the terminal a host would hand it belongs - // to whoever is running the tests. Under `xmd test` there is no host - // launcher at all, which is the same fact from the other side. - const hostReached: NativeLaunchRequest[] = []; - const run = yield* runDoc(testDoc(LAUNCH_BODY), { - hostLauncher: (request) => hostReached.push(request), - }); - - expect(run.result.ok ? "" : run.result.error.message).toBe(""); - expect(hostReached).toEqual([]); - // The component's own launcher took it instead. - expect(run.launches.length).toBe(1); - }); - - it("TL9: two sibling tests naming one session each get a session of their own", function* () { - // Identical agent, identical session name, identical cwd — so the natural - // key a coordinator would exclude on is the same for both. What keeps - // them apart is that each `` owns a complete provider partition, - // with its own runtime, store, managed sessions, scenarios and - // coordinator. Two sessions, not two owners of one. - // - // The layers differ deliberately: identical ones would resume, and a - // shared partition would then look like an isolated pair. - const run = yield* runDoc( - [ - "", - '', - "", - '', - '', - "You are the repository implementor.", - "", - '', - "what changed?", - "", - "", - "", - '', - '', - "You are the repository reviewer.", - "", - '', - "what changed?", - "", - "", - "", - "", - ].join("\n"), - ); - - expect(run.result.ok ? "" : run.result.error.message).toBe(""); - expect(run.results.map((result) => result.status)).toEqual(["pass", "pass"]); - - // Two native identities, so neither test saw the other's session — and - // neither waited on the other, which a shared coordinator would have - // made them do. - const identities = new Set(run.launches.map((request) => request.command.at(-1))); - expect(run.launches.length).toBe(2); - expect(identities.size).toBe(2); - - // Both session/new and session/load report the layer for the same identity. - const reportsByIdentity = new Map(); - for (const report of run.sessions) { - const reports = reportsByIdentity.get(report.nativeSessionId) ?? []; - reports.push(report); - reportsByIdentity.set(report.nativeSessionId, reports); - } - expect(new Set(reportsByIdentity.keys())).toEqual(identities); - const layers: string[] = []; - const scenarioIds = new Set(); - for (const reports of reportsByIdentity.values()) { - expect(reports.length).toBeGreaterThan(0); - const first = reports[0]; - if (first === undefined || first.systemPrompt === undefined) { - throw new Error("A launched identity has no instruction layer."); + { stream }, + directory, + ); + + expect(run.result.ok ? "" : run.result.error.message).toBe(""); + expect(run.results.map((result) => result.status)).toEqual(["pass", "pass"]); + + // Two native identities, so neither test saw the other's session — and + // neither waited on the other, which a shared coordinator would have + // made them do. + const identities = new Set(run.launches.map((request) => request.command.at(-1))); + expect(run.launches.length).toBe(2); + expect(identities.size).toBe(2); + + // Both session/new and session/load report the layer for the same identity. + const reportsByIdentity = new Map(); + for (const report of run.sessions) { + const reports = reportsByIdentity.get(report.nativeSessionId) ?? []; + reports.push(report); + reportsByIdentity.set(report.nativeSessionId, reports); } - for (const report of reports) { - expect(report.systemPrompt).toBe(first.systemPrompt); + expect(new Set(reportsByIdentity.keys())).toEqual(identities); + const layers: string[] = []; + const scenarioIds = new Set(); + for (const reports of reportsByIdentity.values()) { + expect(reports.length).toBeGreaterThan(0); + const first = reports[0]; + if (first === undefined || first.systemPrompt === undefined) { + throw new Error("A launched identity has no instruction layer."); + } + for (const report of reports) { + expect(report.systemPrompt).toBe(first.systemPrompt); + } + layers.push(first.systemPrompt.trim()); + expect(new Set(reports.map((report) => report.scenarioId)).size).toBe(1); + scenarioIds.add(first.scenarioId); } - layers.push(first.systemPrompt.trim()); - expect(new Set(reports.map((report) => report.scenarioId)).size).toBe(1); - scenarioIds.add(first.scenarioId); - } - expect(layers.sort()).toEqual([ - "You are the repository implementor.", - "You are the repository reviewer.", - ]); - expect(scenarioIds.size).toBe(2); - - // Each test's prompt was answered by a scenario of its own: one stage - // exists per instance, and a shared one would have been exhausted. - const answers = run.output.split("nothing yet").length - 1; - expect(answers).toBe(2); - }); - - it("TL10: the provider is installed once, in , not per test", function* () { - // Outside every ``, so the only installation that can serve this - // launch is the one the `` invocation made. A provider - // installed per test would leave this content with none. - const run = yield* runDoc( - [ - "", - '', - "", - '', + expect(layers.sort()).toEqual([ "You are the repository implementor.", - "", - "", - // A testing session needs one, and this one is deliberately empty: - // the launch above it is what reaches the installation. - '', - "nothing to check here", - "", - "", - "", - ].join("\n"), - ); - - expect(run.result.ok ? "" : run.result.error.message).toBe(""); - expect(run.launches.length).toBe(1); - expect(run.sessions.filter((report) => report.systemPrompt !== undefined).length).toBe(1); - }); - - it("TL11: a prompt attaches to the conversation XMD named, under that same identity", function* () { - const run = yield* runDoc( - [ - "", - '', - "", - '', - '', - LAUNCH_BODY, - "", - '', - "what changed?", - "", - "", - "", - "", - "", - ].join("\n"), - ); - - expect(run.result.ok ? "" : run.result.error.message).toBe(""); - expect(run.results.map((result) => result.status)).toEqual(["pass"]); - // XMD chose the identity and handed it to the native process... - const named = preparedRecords(run.events)[0]?.nativeSessionId; - expect(typeof named).toBe("string"); - expect(run.launches[0]?.command.slice(1, 3)).toEqual(["--session-id", named]); - // ...and the worker the prompt attached to reported that conversation, - // not one of its own and not the loading target it was asked for. - expect(run.sessions.length).toBeGreaterThan(0); - for (const report of run.sessions) { - expect(report.nativeSessionId).toBe(named); - } - expect(promptRecords(run.events).map((record) => record.agentSessionId)).toEqual([named]); - // The one scripted stage answered exactly once. - expect(run.output.split("nothing yet").length - 1).toBe(1); - }); + "You are the repository reviewer.", + ]); + expect(scenarioIds.size).toBe(2); + + // Each test's prompt was answered by a scenario of its own: one stage + // exists per instance, and a shared one would have been exhausted. + const answers = run.output.split("nothing yet").length - 1; + expect(answers).toBe(2); + }, + ); + + journalCase( + "TL10: the provider is installed once, in , not per test", + function* (stream, directory) { + // Outside every ``, so the only installation that can serve this + // launch is the one the `` invocation made. A provider + // installed per test would leave this content with none. + const run = yield* runDoc( + [ + "", + '', + "", + '', + "You are the repository implementor.", + "", + "", + // A testing session needs one, and this one is deliberately empty: + // the launch above it is what reaches the installation. + '', + "nothing to check here", + "", + "", + "", + ].join("\n"), + { stream }, + directory, + ); + + expect(run.result.ok ? "" : run.result.error.message).toBe(""); + expect(run.launches.length).toBe(1); + expect(run.sessions.filter((report) => report.systemPrompt !== undefined).length).toBe(1); + }, + ); + + journalCase( + "TL11: a prompt attaches to the conversation XMD named, under that same identity", + function* (stream, directory) { + const run = yield* runDoc( + [ + "", + '', + "", + '', + '', + LAUNCH_BODY, + "", + '', + "what changed?", + "", + "", + "", + "", + "", + ].join("\n"), + { stream }, + directory, + ); + + expect(run.result.ok ? "" : run.result.error.message).toBe(""); + expect(run.results.map((result) => result.status)).toEqual(["pass"]); + // XMD chose the identity and handed it to the native process... + const named = preparedRecords(run.events)[0]?.nativeSessionId; + expect(typeof named).toBe("string"); + expect(run.launches[0]?.command.slice(1, 3)).toEqual(["--session-id", named]); + // ...and the worker the prompt attached to reported that conversation, + // not one of its own and not the loading target it was asked for. + expect(run.sessions.length).toBeGreaterThan(0); + for (const report of run.sessions) { + expect(report.nativeSessionId).toBe(named); + } + expect(promptRecords(run.events).map((record) => record.agentSessionId)).toEqual([named]); + // The one scripted stage answered exactly once. + expect(run.output.split("nothing yet").length - 1).toBe(1); + }, + ); it("TL8: full replay contacts neither the agent nor the launcher", function* () { const stream = new InMemoryStream(); From adb9c60c862bf7e6c26f1ec90f89b166b42fe7a0 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:42:55 -0500 Subject: [PATCH 21/78] test: capture fresh inline REPL selection journals --- packages/cli/tests/repl-execution.test.ts | 60 ++++++++++++++--------- 1 file changed, 38 insertions(+), 22 deletions(-) diff --git a/packages/cli/tests/repl-execution.test.ts b/packages/cli/tests/repl-execution.test.ts index 9d3ef1335..fb8e508fe 100644 --- a/packages/cli/tests/repl-execution.test.ts +++ b/packages/cli/tests/repl-execution.test.ts @@ -15,7 +15,7 @@ import { beforeAll, describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { useTempFileCompiler } from "@executablemd/core"; +import { INLINE_SOURCE_PATH, useTempFileCompiler } from "@executablemd/core"; import { InMemoryStream, serializeDurableEvent } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; import { createContext, ensure, race, scoped, sleep, spawn, until } from "effection"; @@ -244,10 +244,20 @@ function captureReferenceEntry( body: (holder: ReplExecution) => Operation, sink: DeliverySink = process.stderr, suite = SUBMIT_SUITE, +): Operation { + return captureEntry(suite, name, REFERENCE_PATH, body, sink); +} + +function captureEntry( + suite: string, + name: string, + source: string, + body: (holder: ReplExecution) => Operation, + sink: DeliverySink = process.stderr, ): Operation { return captureTestJournal( { owner: OWNER, suite, name }, - REFERENCE_PATH, + source, (stream) => body({ id: "kf39sla2", stream }), { sink, @@ -257,7 +267,7 @@ function captureReferenceEntry( throw partition.error; } if (partition.value.length > 1) { - throw new Error("reference execution holds more than one admitted entry"); + throw new Error("fixture execution holds more than one admitted entry"); } return partition.value[0]?.events ?? []; }, @@ -1137,7 +1147,9 @@ describe("REPL execution: one execution's file", () => { }); }); -describe("REPL execution: the selection each entry reads", () => { +const SELECTION_SUITE = "REPL execution: the selection each entry reads"; + +describe(SELECTION_SUITE, () => { beforeAll(() => useTempFileCompiler()); /** @@ -1149,30 +1161,34 @@ describe("REPL execution: the selection each entry reads", () => { */ const DESCRIBING = '\n'; - it("X1: the session's selection is the entry's default, and a host's own is not replaced", function* () { + const selection = + "X1: the session's selection is the entry's default, and a host's own is not replaced"; + it(selection, function* () { // Control: no host states a selection, so the entry runs under the one the // command supplies and the fragment is admitted. - const ordinary = opened( - yield* submitReplEntry({ ...options(execution()), source: DESCRIBING }), - ); - const settled = yield* ordinary.join(); - expect(settled.ok).toBe(true); - expect(ordinary.model.terminal?.status).toBe("ok"); + yield* captureEntry(SELECTION_SUITE, selection, INLINE_SOURCE_PATH, function* (holder) { + const ordinary = opened(yield* submitReplEntry({ ...options(holder), source: DESCRIBING })); + const settled = yield* ordinary.join(); + expect(settled.ok).toBe(true); + expect(ordinary.model.terminal?.status).toBe("ok"); + }); // The same entry, where a host installation states its own. It is defined, // narrower, and nearer than the session's default — so it is what core // reads, and the same fragment is refused for the name it writes. - const narrowed = opened( - yield* submitReplEntry({ - ...options(execution()), - source: DESCRIBING, - installations: [selecting({ Glob: ["self-closing"] })], - }), - ); - const refused = yield* narrowed.join(); - expect(refused.ok).toBe(false); - expect(refused.ok ? "" : refused.error.message).toContain("did not admit"); - expect(narrowed.model.terminal?.status).toBe("err"); + yield* captureEntry(SELECTION_SUITE, selection, INLINE_SOURCE_PATH, function* (holder) { + const narrowed = opened( + yield* submitReplEntry({ + ...options(holder), + source: DESCRIBING, + installations: [selecting({ Glob: ["self-closing"] })], + }), + ); + const refused = yield* narrowed.join(); + expect(refused.ok).toBe(false); + expect(refused.ok ? "" : refused.error.message).toContain("did not admit"); + expect(narrowed.model.terminal?.status).toBe("err"); + }); }); it("X1: a host's defined empty selection refuses the entry before its body", function* () { From 113b89cde0e2fb4e1990c7bd08baa5a4e82cecdc Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:43:41 -0500 Subject: [PATCH 22/78] test: capture guarded Glob fixture journals --- packages/core/tests/glob-component.test.ts | 84 +++++++++++++--------- 1 file changed, 49 insertions(+), 35 deletions(-) diff --git a/packages/core/tests/glob-component.test.ts b/packages/core/tests/glob-component.test.ts index 444b7420a..c41f8a5d5 100644 --- a/packages/core/tests/glob-component.test.ts +++ b/packages/core/tests/glob-component.test.ts @@ -22,6 +22,7 @@ import { API, useHostFiles } from "@executablemd/runtime"; import { InMemoryStream } from "@executablemd/durable-streams"; import type { Json } from "@executablemd/durable-streams"; import { execute } from "../src/execute.ts"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { collect } from "../src/collect.ts"; import { GlobError } from "../src/components/Glob.ts"; import { mkdir, mkdtemp, realpath, symlink } from "node:fs/promises"; @@ -66,18 +67,22 @@ function* useCwd(directory: string): Operation { ); } -function run(fixture: Fixture, source: string): Operation { - return runWith(fixture, source, new InMemoryStream()); +function fixtureDocument(fixture: Fixture): string { + return join(fixture.workspace, "..", "doc.md"); +} + +function run(fixture: Fixture, source: string, stream = new InMemoryStream()): Operation { + return runWith(fixture, source, stream); } /** * What one run said: its rendered text, or the diagnostic it reported. A * refusal nothing recovers is the run's own outcome. */ -function said(fixture: Fixture, source: string): Operation { +function said(fixture: Fixture, source: string, stream?: InMemoryStream): Operation { return (function* () { try { - return String(yield* run(fixture, source)); + return String(yield* run(fixture, source, stream)); } catch (error) { return error instanceof Error ? error.message : String(error); } @@ -101,7 +106,7 @@ function runWith( return scoped(function* () { // The document lives beside the workspace, not inside it, so it is never // itself a match — a `**/*` in a test means only what the test laid out. - const path = join(fixture.workspace, "..", "doc.md"); + const path = fixtureDocument(fixture); if (source !== undefined) { yield* writeTextFile(path, source); } @@ -202,7 +207,23 @@ const ADVERSARIAL: Array<{ name: string; error: () => unknown }> = [ }, ]; -describe("Tier GB — Glob component", () => { +const SUITE = "Tier GB — Glob component"; + +function globCase( + name: string, + body: (fixture: Fixture, stream: InMemoryStream) => Operation, +): void { + it(name, function* () { + const fixture = yield* useFixture(); + yield* captureTestJournal( + { owner: "packages/core/tests/glob-component.test.ts", suite: SUITE, name }, + fixtureDocument(fixture), + (stream) => body(fixture, stream), + ); + }); +} + +describe(SUITE, () => { // GB1: props are validated like any component's — no name-specific check. it("GB1: include is required and undeclared props are rejected", function* () { const fixture = yield* useFixture(); @@ -216,10 +237,8 @@ describe("Tier GB — Glob component", () => { // GB2: an empty include list is not "match nothing" — it is a pattern list // that forgot to say anything, and the schema is where that is caught. - it("GB2: an empty include list is rejected", function* () { - const fixture = yield* useFixture(); - - const output = yield* said(fixture, ''); + globCase("GB2: an empty include list is rejected", function* (fixture, stream) { + const output = yield* said(fixture, '', stream); expect(output).toContain('"/include" must NOT have fewer than 1 items'); }); @@ -242,20 +261,17 @@ describe("Tier GB — Glob component", () => { // GB4: declaring `returns` is what requires `as` (§6.10). Nothing in the // component enforces it, which is the point — it is the value-component // contract, not a rule of its own. - it("GB4: invoking without as fails", function* () { - const fixture = yield* useFixture(); - - const output = yield* said(fixture, ''); + globCase("GB4: invoking without as fails", function* (fixture, stream) { + const output = yield* said(fixture, '', stream); expect(output).toContain("must be invoked with `as`"); }); // GB5: `exclude` is optional, and omitting it excludes nothing. - it("GB5: exclude defaults to empty", function* () { - const fixture = yield* useFixture(); + globCase("GB5: exclude defaults to empty", function* (fixture, stream) { yield* plant(fixture, ["a.md", "nested/b.md"]); - const output = text(yield* run(fixture, FIND_ALL)); + const output = text(yield* run(fixture, FIND_ALL, stream)); expect(output).toContain(found("a.md", "nested/b.md")); }); @@ -314,10 +330,8 @@ describe("Tier GB — Glob component", () => { // GB8: an empty pattern matches nothing by construction, so it is the same // authoring mistake as an absolute one. - it("GB8: an empty pattern fails", function* () { - const fixture = yield* useFixture(); - - const output = text(yield* run(fixture, '')); + globCase("GB8: an empty pattern fails", function* (fixture, stream) { + const output = text(yield* run(fixture, '', stream)); expect(output).toContain("empty pattern"); }); @@ -483,26 +497,27 @@ describe("Tier GB — Glob component", () => { // GB15b: a link back into the workspace is refused on the same terms. The // rule is about symlinks, not about where they point, so `` never has // to judge a destination. - it("GB15b: a directory symlink inside the workspace is not traversed either", function* () { - const fixture = yield* useFixture(); - yield* plant(fixture, ["real/a.md"]); - yield* until(symlink(join(fixture.workspace, "real"), join(fixture.workspace, "alias"))); + globCase( + "GB15b: a directory symlink inside the workspace is not traversed either", + function* (fixture, stream) { + yield* plant(fixture, ["real/a.md"]); + yield* until(symlink(join(fixture.workspace, "real"), join(fixture.workspace, "alias"))); - const output = text(yield* run(fixture, FIND_ALL)); + const output = text(yield* run(fixture, FIND_ALL, stream)); - expect(output).toContain(found("real/a.md")); - expect(output).not.toContain("alias/"); - }); + expect(output).toContain(found("real/a.md")); + expect(output).not.toContain("alias/"); + }, + ); // GB15c: the cycle that rule prevents. A link to its own parent would be an // unbounded walk if it were followed; the search finishes. - it("GB15c: a symlink cycle does not hang the search", function* () { - const fixture = yield* useFixture(); + globCase("GB15c: a symlink cycle does not hang the search", function* (fixture, stream) { yield* plant(fixture, ["a.md"]); yield* until(symlink(fixture.workspace, join(fixture.workspace, "loop"))); const output = text( - yield* race([run(fixture, FIND_ALL), timeout("GB15c: the search did not finish")]), + yield* race([run(fixture, FIND_ALL, stream), timeout("GB15c: the search did not finish")]), ); expect(output).toContain(found("a.md")); @@ -510,12 +525,11 @@ describe("Tier GB — Glob component", () => { // GB16: a symlink is a link rather than a file, so it is not a result even // when its destination is an ordinary file inside the workspace. - it("GB16: a symlink to a file is not a result", function* () { - const fixture = yield* useFixture(); + globCase("GB16: a symlink to a file is not a result", function* (fixture, stream) { yield* plant(fixture, ["a.md"]); yield* until(symlink(join(fixture.workspace, "a.md"), join(fixture.workspace, "link.md"))); - const output = text(yield* run(fixture, FIND_ALL)); + const output = text(yield* run(fixture, FIND_ALL, stream)); expect(output).toContain(found("a.md")); expect(output).not.toContain("link.md"); From 3421beefaaea4ed2d6885d9192d482eed62415b7 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:44:48 -0500 Subject: [PATCH 23/78] test: attribute guarded Agent function component journals --- .../tests/agent-function-components.test.ts | 331 ++++++++++-------- 1 file changed, 186 insertions(+), 145 deletions(-) diff --git a/packages/agent/tests/agent-function-components.test.ts b/packages/agent/tests/agent-function-components.test.ts index b8e6e75ea..8ed9fd4e0 100644 --- a/packages/agent/tests/agent-function-components.test.ts +++ b/packages/agent/tests/agent-function-components.test.ts @@ -8,6 +8,7 @@ * what a document gets. */ +import { fileJournalCases } from "../../test-support/journal-cases.ts"; import { beforeAll, describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { InMemoryStream, serializeDurableEvent } from "@executablemd/durable-streams"; @@ -373,9 +374,10 @@ interface RunOptions { function* runDoc( doc: string, options: RunOptions = {}, + fixture?: { directory: string; stream: InMemoryStream }, ): Operation<{ output: string; result: Result; trace: Trace; events: DurableEvent[] }> { const trace: Trace = options.trace ?? { prompts: [], agentLookups: [], timeouts: [] }; - const dir = path.join(os.tmpdir(), `xmd-af-test-${randomUUID()}`); + const dir = fixture?.directory ?? path.join(os.tmpdir(), `xmd-af-test-${randomUUID()}`); yield* ensureDir(dir); return yield* scoped(function* () { yield* ensure(() => rm(dir, { recursive: true, force: true })); @@ -427,7 +429,7 @@ function* runDoc( // `` names durable work after its own invocation, so the host // declares it to the execution rather than registering it. - const stream = new InMemoryStream(); + const stream = fixture?.stream ?? new InMemoryStream(); const execution = yield* executeInstalled( { path: docPath, @@ -451,20 +453,38 @@ function* runDoc( }); } +const guardedCase = fileJournalCases( + "packages/agent/tests/agent-function-components.test.ts", + "xmd-af-test-", + "doc.md", +); + +function promptCase( + name: string, + body: (run: (doc: string, options?: RunOptions) => ReturnType) => Operation, +): void { + guardedCase(name, (stream, directory) => + body((doc, options) => runDoc(doc, options, { directory, stream })), + ); +} + describe("Tier AF — the engine owns props", () => { beforeAll(() => useTempFileCompiler()); - it("AF1: an expression prop resolves, where the claimed handler rejected it", function* () { - const { output, result } = yield* runDoc( - ["```js eval", 'const who = "hello";', "```", "", "", ""].join("\n"), - ); + promptCase( + "AF1: an expression prop resolves, where the claimed handler rejected it", + function* (run) { + const { output, result } = yield* run( + ["```js eval", 'const who = "hello";', "```", "", "", ""].join("\n"), + ); - expect(result.ok).toBe(true); - expect(output).toContain("[hello]"); - }); + expect(result.ok).toBe(true); + expect(output).toContain("[hello]"); + }, + ); - it("AF2: a boolean expression prop resolves", function* () { - const { result } = yield* runDoc( + promptCase("AF2: a boolean expression prop resolves", function* (run) { + const { result } = yield* run( [ "```js eval", "const strict = false;", @@ -478,36 +498,42 @@ describe("Tier AF — the engine owns props", () => { expect(result.ok).toBe(true); }); - it("AF3: an expression resolving to the wrong type is a schema printed error, and nothing runs", function* () { - const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; - const { result } = yield* runDoc( - ["```js eval", "const who = 42;", "```", "", "", ""].join("\n"), - { trace }, - ); + promptCase( + "AF3: an expression resolving to the wrong type is a schema printed error, and nothing runs", + function* (run) { + const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; + const { result } = yield* run( + ["```js eval", "const who = 42;", "```", "", "", ""].join("\n"), + { trace }, + ); - expect(result.ok).toBe(false); - expect(result.ok ? "" : result.error.message).toContain( - "Prop validation failed for ", - ); - // Validation is the engine's, and it runs before the component does. - expect(trace.prompts).toEqual([]); - expect(trace.agentLookups).toEqual([]); - }); + expect(result.ok).toBe(false); + expect(result.ok ? "" : result.error.message).toContain( + "Prop validation failed for ", + ); + // Validation is the engine's, and it runs before the component does. + expect(trace.prompts).toEqual([]); + expect(trace.agentLookups).toEqual([]); + }, + ); - it("AF4: an unknown prop is rejected before the component performs anything", function* () { - const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; - const { output, result } = yield* runDoc( - 'body\n', - { trace }, - ); + promptCase( + "AF4: an unknown prop is rejected before the component performs anything", + function* (run) { + const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; + const { output, result } = yield* run( + 'body\n', + { trace }, + ); - expect(result.ok).toBe(false); - expect(result.ok ? "" : result.error.message).toContain( - "Prop validation failed for ", - ); - expect(output).not.toContain("body"); - expect(trace.prompts).toEqual([]); - }); + expect(result.ok).toBe(false); + expect(result.ok ? "" : result.error.message).toContain( + "Prop validation failed for ", + ); + expect(output).not.toContain("body"); + expect(trace.prompts).toEqual([]); + }, + ); }); describe("Tier AF — the engine owns `as`", () => { @@ -569,17 +595,17 @@ describe("Tier AF — the engine owns `as`", () => { expect(JSON.stringify(events)).not.toContain("permission_decision_result"); }); - it("AF5: the returned string is captured once and not also emitted", function* () { - const { output, result } = yield* runDoc('\n\nGot: {answer}\n'); + promptCase("AF5: the returned string is captured once and not also emitted", function* (run) { + const { output, result } = yield* run('\n\nGot: {answer}\n'); expect(result.ok).toBe(true); expect(output).toContain("Got: [hi]"); expect(output.indexOf("[hi]")).toBe(output.lastIndexOf("[hi]")); }); - it("AF6: an invalid `as` prevents every component effect", function* () { + promptCase("AF6: an invalid `as` prevents every component effect", function* (run) { const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; - const { result } = yield* runDoc('\n', { trace }); + const { result } = yield* run('\n', { trace }); expect(result.ok).toBe(false); expect(result.ok ? "" : result.error.message).toContain('Prop "as" on '); @@ -589,48 +615,54 @@ describe("Tier AF — the engine owns `as`", () => { }); describe("Tier AF — a prompt does nothing before its content renders", () => { - it("AF7: a failing wrapper performs no lookup, no prompt and no journal entry", function* () { - const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; - const { result } = yield* runDoc("\n\n\n", { trace }); - - expect(result.ok).toBe(false); - expect(result.ok ? "" : result.error.message).toContain("Failed to import component Missing"); - expect(trace.prompts).toEqual([]); - expect(trace.agentLookups).toEqual([]); - }); + promptCase( + "AF7: a failing wrapper performs no lookup, no prompt and no journal entry", + function* (run) { + const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; + const { result } = yield* run("\n\n\n", { trace }); + + expect(result.ok).toBe(false); + expect(result.ok ? "" : result.error.message).toContain("Failed to import component Missing"); + expect(trace.prompts).toEqual([]); + expect(trace.agentLookups).toEqual([]); + }, + ); - it("AF8: an empty wrapper still overrides the text prop", function* () { + promptCase("AF8: an empty wrapper still overrides the text prop", function* (run) { const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; - yield* runDoc('\n', { trace }); + yield* run('\n', { trace }); expect(trace.prompts).toEqual([""]); }); }); describe("Tier AF — failures that end the document", () => { - it("AF9: an unavailable agent stops the document, nested in another wrapper", function* () { - const { output, result } = yield* runDoc( - [ - "BEFORE", - "", - '', - ' ', - "", - "", - "AFTER", - "", - ].join("\n"), - { fail: false }, - ); + promptCase( + "AF9: an unavailable agent stops the document, nested in another wrapper", + function* (run) { + const { output, result } = yield* run( + [ + "BEFORE", + "", + '', + ' ', + "", + "", + "AFTER", + "", + ].join("\n"), + { fail: false }, + ); - // The nested case succeeds; the point is that the wrapper does not swallow. - expect(result.ok).toBe(true); - expect(output).toContain("BEFORE"); - expect(output).toContain("AFTER"); - }); + // The nested case succeeds; the point is that the wrapper does not swallow. + expect(result.ok).toBe(true); + expect(output).toContain("BEFORE"); + expect(output).toContain("AFTER"); + }, + ); - it("AF10: a throwOnError prompt inside still ends the document", function* () { - const { output, result } = yield* runDoc( + promptCase("AF10: a throwOnError prompt inside still ends the document", function* (run) { + const { output, result } = yield* run( [ "BEFORE", "", @@ -651,8 +683,8 @@ describe("Tier AF — failures that end the document", () => { expect(output).not.toContain("AFTER"); }); - it("AF11: the same holds two wrappers deep", function* () { - const { output, result } = yield* runDoc( + promptCase("AF11: the same holds two wrappers deep", function* (run) { + const { output, result } = yield* run( [ "BEFORE", "", @@ -673,62 +705,68 @@ describe("Tier AF — failures that end the document", () => { expect(output).not.toContain("AFTER"); }); - it("AF12: it survives a repository component projecting the prompt as content", function* () { - const { output, result } = yield* runDoc( - [ - "BEFORE", - "", - "", - ' ', - "", - "", - "AFTER", - "", - ].join("\n"), - { - fail: true, - files: { "Wrapper.md": "\n" }, - }, - ); + promptCase( + "AF12: it survives a repository component projecting the prompt as content", + function* (run) { + const { output, result } = yield* run( + [ + "BEFORE", + "", + "", + ' ', + "", + "", + "AFTER", + "", + ].join("\n"), + { + fail: true, + files: { "Wrapper.md": "\n" }, + }, + ); - expect(result.ok).toBe(false); - expect(result.ok === false && result.error).toBeInstanceOf(AgentPromptError); - expect(output).not.toContain("AFTER"); - }); + expect(result.ok).toBe(false); + expect(result.ok === false && result.error).toBeInstanceOf(AgentPromptError); + expect(output).not.toContain("AFTER"); + }, + ); }); describe("Tier AF — registered defaults a document can replace", () => { const names = ["AgentProvider", "Agent", "Prompt", "ApproveAll", "AskPermission"]; - it("AF24: a Session hands the exact value it was issued to every nested Prompt", function* () { - // The value is the capability. A `` resolves one and pins it around - // its body, and what the first nested Prompt is given has to be that exact - // object — a provider decides whether a session may be acted on by - // identity, and a rebuilt look-alike was issued by nobody. - const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; - const { result } = yield* runDoc( - [ - '', - ' ', - ' ', - "", - "", - ].join("\n"), - { trace }, - ); + promptCase( + "AF24: a Session hands the exact value it was issued to every nested Prompt", + function* (run) { + // The value is the capability. A `` resolves one and pins it around + // its body, and what the first nested Prompt is given has to be that exact + // object — a provider decides whether a session may be acted on by + // identity, and a rebuilt look-alike was issued by nobody. + const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; + const { result } = yield* run( + [ + '', + ' ', + ' ', + "", + "", + ].join("\n"), + { trace }, + ); - expect(result.ok).toBe(true); - // Resolved once, however many prompts are inside it. - expect(trace.sessions).toHaveLength(1); - const resolved = trace.sessions?.[0]; - expect(trace.promptSessions).toEqual([resolved, resolved]); - expect(trace.promptSessions?.[0]).toBe(resolved); - expect(trace.promptSessions?.[1]).toBe(resolved); - }); + expect(result.ok).toBe(true); + // Resolved once, however many prompts are inside it. + expect(trace.sessions).toHaveLength(1); + const resolved = trace.sessions?.[0]; + expect(trace.promptSessions).toEqual([resolved, resolved]); + expect(trace.promptSessions?.[0]).toBe(resolved); + expect(trace.promptSessions?.[1]).toBe(resolved); + }, + ); - it("AF25: a self-closing Session resolves one and renders nothing", function* () { + promptCase("AF25: a self-closing Session resolves one and renders nothing", function* (run) { const trace: Trace = { prompts: [], agentLookups: [], timeouts: [] }; - const { output, result } = yield* runDoc( + const { output, result } = yield* run( ["BEFORE", "", '', "", "AFTER", ""].join("\n"), { trace }, ); @@ -786,16 +824,16 @@ describe("Tier AF — registered defaults a document can replace", () => { }); describe("Tier AF — the scoped prompt-failure policy", () => { - it("AF16: without a policy a failing prompt is collected, not fatal", function* () { - const { output, result } = yield* runDoc('\n\nAFTER\n', { fail: true }); + promptCase("AF16: without a policy a failing prompt is collected, not fatal", function* (run) { + const { output, result } = yield* run('\n\nAFTER\n', { fail: true }); expect(result.ok).toBe(false); // aggregated at completion, as always expect(output).toContain("AFTER"); // but the document ran on }); - it("AF17: a policy that says yes ends the document at the prompt", function* () { + promptCase("AF17: a policy that says yes ends the document at the prompt", function* (run) { let asked = 0; - const { output } = yield* runDoc('\n\nAFTER\n', { + const { output } = yield* run('\n\nAFTER\n', { fail: true, // deno-lint-ignore require-yield policy: function* () { @@ -808,9 +846,9 @@ describe("Tier AF — the scoped prompt-failure policy", () => { expect(output).not.toContain("AFTER"); }); - it("AF18: an explicit throwOnError wins without consulting the policy", function* () { + promptCase("AF18: an explicit throwOnError wins without consulting the policy", function* (run) { let asked = 0; - const { output } = yield* runDoc('\n\nAFTER\n', { + const { output } = yield* run('\n\nAFTER\n', { fail: true, // deno-lint-ignore require-yield policy: function* () { @@ -823,8 +861,8 @@ describe("Tier AF — the scoped prompt-failure policy", () => { expect(output).not.toContain("AFTER"); }); - it("AF19: a policy that says no leaves the prompt collected", function* () { - const { output } = yield* runDoc('\n\nAFTER\n', { + promptCase("AF19: a policy that says no leaves the prompt collected", function* (run) { + const { output } = yield* run('\n\nAFTER\n', { fail: true, // deno-lint-ignore require-yield policy: function* () { @@ -835,9 +873,9 @@ describe("Tier AF — the scoped prompt-failure policy", () => { expect(output).toContain("AFTER"); }); - it("AF20: a repository Prompt never consults the policy", function* () { + promptCase("AF20: a repository Prompt never consults the policy", function* (run) { let asked = 0; - const { output } = yield* runDoc("\n\nAFTER\n", { + const { output } = yield* run("\n\nAFTER\n", { fail: true, files: { "Prompt.md": "LOCAL\n" }, // deno-lint-ignore require-yield @@ -854,30 +892,33 @@ describe("Tier AF — the scoped prompt-failure policy", () => { }); describe("Tier AF — prompt timeouts", () => { - it("AF21: a prompt nobody bounded carries no timeout", function* () { - const { trace } = yield* runDoc('\n'); + promptCase("AF21: a prompt nobody bounded carries no timeout", function* (run) { + const { trace } = yield* run('\n'); expect(trace.timeouts).toEqual([undefined]); }); - it("AF22a: a prompt inherits the subtree default an installs", function* () { - const { trace } = yield* runDoc('\n', { promptTimeout: 500 }); - expect(trace.timeouts).toEqual([500]); - }); + promptCase( + "AF22a: a prompt inherits the subtree default an installs", + function* (run) { + const { trace } = yield* run('\n', { promptTimeout: 500 }); + expect(trace.timeouts).toEqual([500]); + }, + ); - it("AF22b: a prompt's own timeout outranks the inherited one", function* () { - const { trace } = yield* runDoc('\n', { + promptCase("AF22b: a prompt's own timeout outranks the inherited one", function* (run) { + const { trace } = yield* run('\n', { promptTimeout: 500, }); expect(trace.timeouts).toEqual([250]); }); - it("AF22: a prompt's own timeout is the duration it declares", function* () { - const { trace } = yield* runDoc('\n'); + promptCase("AF22: a prompt's own timeout is the duration it declares", function* (run) { + const { trace } = yield* run('\n'); expect(trace.timeouts).toEqual([250]); }); - it("AF23: a malformed prompt timeout refuses instead of prompting", function* () { - const { result, trace } = yield* runDoc('\n'); + promptCase("AF23: a malformed prompt timeout refuses instead of prompting", function* (run) { + const { result, trace } = yield* run('\n'); expect(result.ok).toBe(false); expect(result.ok === false && result.error.message).toContain("must be a duration"); expect(trace.timeouts).toEqual([]); From 1143a70e2d5e9529cfe0a8bfc145ab512c44e5d7 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:46:39 -0500 Subject: [PATCH 24/78] test: retain separate journals for Testing session siblings --- packages/testing/tests/use-testing.test.ts | 127 ++++++++++++--------- 1 file changed, 71 insertions(+), 56 deletions(-) diff --git a/packages/testing/tests/use-testing.test.ts b/packages/testing/tests/use-testing.test.ts index a2099053f..4db240880 100644 --- a/packages/testing/tests/use-testing.test.ts +++ b/packages/testing/tests/use-testing.test.ts @@ -16,6 +16,7 @@ import type { Json } from "@executablemd/core"; import { Test, TestFailureError, testing } from "../src/test-api.ts"; import { useTesting } from "../src/use-testing.ts"; import { documentCases, failureOf, runDoc, withFreshDocument } from "./helpers.ts"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { journalCases } from "../../test-support/journal-cases.ts"; const OWNER = "packages/testing/tests/use-testing.test.ts"; @@ -142,7 +143,7 @@ describe("useTesting composition", () => { } }); - it("enforces one execute() call per session", function* () { + journalCase("enforces one execute() call per session", "README.md", function* (stream) { // Results are cumulative across a session: without the guard, a // zero-test second document would succeed on the strength of the first // document's passing test. @@ -153,7 +154,7 @@ describe("useTesting composition", () => { "empty.md": "no tests here\n", }); yield* useTesting(); - const execution = yield* execute({ path: "README.md", stream: new InMemoryStream() }); + const execution = yield* execute({ path: "README.md", stream }); const result = yield* execution; try { yield* execute({ path: "empty.md", stream: new InMemoryStream() }); @@ -179,70 +180,84 @@ describe("useTesting composition", () => { expect(error?.message).toContain("one session per execution scope"); }); - documentCase("removes all session middleware with its scope", function* (runFresh) { - yield* scoped(function* () { - yield* useStubFs({ "README.md": "\n" }); - yield* useTesting(); - const execution = yield* execute({ path: "README.md", stream: new InMemoryStream() }); - const result = yield* execution; - expect(result.ok).toBe(true); - }); + const middlewareCase = "removes all session middleware with its scope"; + documentCase(middlewareCase, function* (runFresh) { + yield* captureTestJournal( + { owner: OWNER, name: middlewareCase }, + "README.md", + function* (stream) { + yield* scoped(function* () { + yield* useStubFs({ "README.md": "\n" }); + yield* useTesting(); + const execution = yield* execute({ path: "README.md", stream }); + const result = yield* execution; + expect(result.ok).toBe(true); + }); - // Outside the session scope: activation, collectors, and policy are gone. - expect(yield* testing).toBe(false); - expect(yield* Test.operations.results()).toEqual([]); - const second = yield* runFresh({ "README.md": "\n" }); - expect(second.completion.ok).toBe(true); - expect(second.output).not.toContain("Assert"); - expect(second.results).toEqual([]); + // Outside the session scope: activation, collectors, and policy are gone. + expect(yield* testing).toBe(false); + expect(yield* Test.operations.results()).toEqual([]); + const second = yield* runFresh({ "README.md": "\n" }); + expect(second.completion.ok).toBe(true); + expect(second.output).not.toContain("Assert"); + expect(second.results).toEqual([]); + }, + ); }); // The supported multi-document shape: fixtures and providers live in an // enclosing scope, and each document gets a child scope with one session and // one execution. Wrapping a loop in a single session would instead make the // second document inherit the first document's outcomes. - it("runs sibling documents with shared fixtures and separate sessions", function* () { - const visited: string[] = []; - const outcome = yield* scoped(function* () { - yield* useStubFs({ - "first.md": '\n', - "second.md": '\n', - }); - yield* registerComponents([ - { - name: "Visit", - origin: "use-testing-fixture", - props: { - type: "object", - properties: { doc: { type: "string" } }, - additionalProperties: false, - }, - // deno-lint-ignore require-yield - *fn(props: Record): Operation { - visited.push(String(props.doc)); - return ""; - }, - }, - ]); + const siblings = "runs sibling documents with shared fixtures and separate sessions"; + it(siblings, function* () { + const label = { owner: OWNER, name: siblings }; + yield* captureTestJournal(label, "first.md", function* (firstStream) { + yield* captureTestJournal(label, "second.md", function* (secondStream) { + const visited: string[] = []; + const outcome = yield* scoped(function* () { + yield* useStubFs({ + "first.md": '\n', + "second.md": + '\n', + }); + yield* registerComponents([ + { + name: "Visit", + origin: "use-testing-fixture", + props: { + type: "object", + properties: { doc: { type: "string" } }, + additionalProperties: false, + }, + // deno-lint-ignore require-yield + *fn(props: Record): Operation { + visited.push(String(props.doc)); + return ""; + }, + }, + ]); - const first = yield* scoped(function* () { - const tests = yield* useTesting(); - const result = yield* yield* execute({ path: "first.md", stream: new InMemoryStream() }); - return { result, results: yield* tests.results }; - }); - const second = yield* scoped(function* () { - const tests = yield* useTesting(); - const result = yield* yield* execute({ path: "second.md", stream: new InMemoryStream() }); - return { result, results: yield* tests.results }; + const first = yield* scoped(function* () { + const tests = yield* useTesting(); + const result = yield* yield* execute({ path: "first.md", stream: firstStream }); + return { result, results: yield* tests.results }; + }); + const second = yield* scoped(function* () { + const tests = yield* useTesting(); + const result = yield* yield* execute({ path: "second.md", stream: secondStream }); + return { result, results: yield* tests.results }; + }); + return { first, second }; + }); + + expect(visited).toEqual(["first", "second"]); + expect(outcome.first.result.ok).toBe(false); + expect(outcome.first.results.map((r) => [r.name, r.status])).toEqual([["first", "fail"]]); + expect(outcome.second.result.ok).toBe(true); + expect(outcome.second.results.map((r) => [r.name, r.status])).toEqual([["second", "pass"]]); }); - return { first, second }; }); - - expect(visited).toEqual(["first", "second"]); - expect(outcome.first.result.ok).toBe(false); - expect(outcome.first.results.map((r) => [r.name, r.status])).toEqual([["first", "fail"]]); - expect(outcome.second.result.ok).toBe(true); - expect(outcome.second.results.map((r) => [r.name, r.status])).toEqual([["second", "pass"]]); }); it("completion returns Err instead of throwing for document failures", function* () { From b3105859e1b45a0ec19b93fb7dd8b4da8428b5b4 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:48:10 -0500 Subject: [PATCH 25/78] test: capture guarded Core prop evaluation journals --- packages/core/tests/expression-props.test.ts | 291 +++++++++---------- packages/core/tests/root-props.test.ts | 192 ++++++++---- 2 files changed, 271 insertions(+), 212 deletions(-) diff --git a/packages/core/tests/expression-props.test.ts b/packages/core/tests/expression-props.test.ts index e84a0d2c5..603d616c9 100644 --- a/packages/core/tests/expression-props.test.ts +++ b/packages/core/tests/expression-props.test.ts @@ -5,6 +5,7 @@ * parseExpressionValue changes, and integration with expansion/validation. */ +import { workspaceJournalCases } from "../../test-support/journal-cases.ts"; import { describe, it, beforeAll } from "@executablemd/test-support/bdd"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import { expect } from "@executablemd/test-support/expect"; @@ -152,10 +153,15 @@ describe("Tier ES — parseExpressionValue", () => { // Tier EP — Expression prop evaluation (integration) // ═══════════════════════════════════════════════════════════════════════════ +const expressionCase = workspaceJournalCases( + "packages/core/tests/expression-props.test.ts", + "doc.md", + () => useTempDirectory("expr-props-test-"), +); + describe("Tier EP — Expression prop evaluation", () => { beforeAll(() => useTempFileCompiler()); - it("EP1: bare identifier resolves from env", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP1: bare identifier resolves from env", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Display.md": [ "---", @@ -174,15 +180,13 @@ describe("Tier EP — Expression prop evaluation", () => { "\n", ), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); // {props.data} will be interpolated — for objects, it uses toString expect(output).toContain("received:"); expect(output).not.toContain("ERROR"); }); - it("EP2: member expression resolves", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP2: member expression resolves", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Show.md": [ "---", @@ -205,13 +209,11 @@ describe("Tier EP — Expression prop evaluation", () => { "", ].join("\n"), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("length=3"); }); - it("EP3: comparison expression resolves", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP3: comparison expression resolves", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Check.md": [ "---", @@ -234,13 +236,11 @@ describe("Tier EP — Expression prop evaluation", () => { '', ].join("\n"), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("active=true"); }); - it("EP5: arithmetic expression", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP5: arithmetic expression", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Sum.md": [ "---", @@ -264,13 +264,11 @@ describe("Tier EP — Expression prop evaluation", () => { "", ].join("\n"), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("total=30"); }); - it("EP6: JSON literal still resolves at scan time", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP6: JSON literal still resolves at scan time", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Num.md": [ "---", @@ -288,13 +286,11 @@ describe("Tier EP — Expression prop evaluation", () => { // No eval block — count={42} resolves at scan time "doc.md": "", }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("count=42"); }); - it("EP11: string attribute unaffected", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP11: string attribute unaffected", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Greet.md": [ "---", @@ -311,13 +307,11 @@ describe("Tier EP — Expression prop evaluation", () => { ].join("\n"), "doc.md": '', }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("hello world"); }); - it("EP13: undefined binding → error", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP13: undefined binding → error", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Show.md": [ "---", @@ -333,14 +327,12 @@ describe("Tier EP — Expression prop evaluation", () => { ].join("\n"), "doc.md": ["```js eval", "const x = 1;", "```", "", ""].join("\n"), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("Failed to evaluate expression prop"); expect(output).toContain("nonexistent"); }); - it("EP14: non-serializable result → error", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP14: non-serializable result → error", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Show.md": [ "---", @@ -362,13 +354,11 @@ describe("Tier EP — Expression prop evaluation", () => { "", ].join("\n"), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("non-serializable"); }); - it("EP15: no binding in env → reference error", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP15: no binding in env → reference error", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Show.md": [ "---", @@ -385,14 +375,12 @@ describe("Tier EP — Expression prop evaluation", () => { // No eval block defines someVar — ReferenceError at expansion time "doc.md": "", }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("Failed to evaluate expression prop"); expect(output).toContain("someVar"); }); - it("EP16: syntax error in expression → error", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP16: syntax error in expression → error", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Show.md": [ "---", @@ -408,13 +396,11 @@ describe("Tier EP — Expression prop evaluation", () => { ].join("\n"), "doc.md": ["```js eval", "const a = 1;", "```", "", ""].join("\n"), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("Failed to evaluate expression prop"); }); - it("EP17: mixed resolved and eval props", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP17: mixed resolved and eval props", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Mixed.md": [ "---", @@ -443,15 +429,13 @@ describe("Tier EP — Expression prop evaluation", () => { '', ].join("\n"), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("count=42"); expect(output).toContain("data=result"); expect(output).toContain("name=hello"); }); - it("EP18: expression prop passes validation", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP18: expression prop passes validation", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Typed.md": [ "---", @@ -468,14 +452,12 @@ describe("Tier EP — Expression prop evaluation", () => { ].join("\n"), "doc.md": ["```js eval", "const total = 5;", "```", "", ""].join("\n"), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("count=5"); expect(output).not.toContain("ERROR"); }); - it("EP19: expression prop fails validation", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP19: expression prop fails validation", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Typed.md": [ "---", @@ -494,13 +476,11 @@ describe("Tier EP — Expression prop evaluation", () => { "\n", ), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("must be number"); }); - it("EP20: expression prop with slot", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP20: expression prop with slot", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Layout.md": [ "---", @@ -530,7 +510,6 @@ describe("Tier EP — Expression prop evaluation", () => { ].join("\n"), "doc.md": ["", '', ""].join("\n"), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("data=hello"); expect(output).not.toContain("ERROR"); @@ -573,8 +552,7 @@ describe("Tier EP — Expression prop evaluation", () => { expect(output2).toBe(output1); }); - it("EP22: nested component receives expression prop", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP22: nested component receives expression prop", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Outer.md": [ "---", @@ -604,13 +582,11 @@ describe("Tier EP — Expression prop evaluation", () => { ].join("\n"), "doc.md": "", }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("inner-data=from-outer"); }); - it("EP23: children with expression props", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EP23: children with expression props", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Parent.md": [ "---", @@ -640,7 +616,6 @@ describe("Tier EP — Expression prop evaluation", () => { ].join("\n"), "doc.md": ["", "", ""].join("\n"), }); - const stream = new InMemoryStream(); const output = yield* said(tmpDir, stream); expect(output).toContain("child-data=from-parent"); }); @@ -679,34 +654,34 @@ describe("Tier EU — a prop that evaluates to undefined", () => { ].join("\n"); } - it("EU1: a member that is not there is a prop that is not there", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); - yield* writeFiles(tmpDir, { - "components/Probe.md": probe([" value: {}"]), - "doc.md": [ - "```js eval", - "const record = { present: 1 };", - "```", - "", - "", - ].join("\n"), - }); - const output = yield* said(tmpDir, new InMemoryStream()); - expect(output).toContain("own=false"); - }); + expressionCase( + "EU1: a member that is not there is a prop that is not there", + function* (stream, tmpDir) { + yield* writeFiles(tmpDir, { + "components/Probe.md": probe([" value: {}"]), + "doc.md": [ + "```js eval", + "const record = { present: 1 };", + "```", + "", + "", + ].join("\n"), + }); + const output = yield* said(tmpDir, stream); + expect(output).toContain("own=false"); + }, + ); - it("EU2: a literal `undefined` takes that same path", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EU2: a literal `undefined` takes that same path", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Probe.md": probe([" value: {}"]), "doc.md": "", }); - const output = yield* said(tmpDir, new InMemoryStream()); + const output = yield* said(tmpDir, stream); expect(output).toContain("own=false"); }); - it("EU3: a declared default answers the absence", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); + expressionCase("EU3: a declared default answers the absence", function* (stream, tmpDir) { yield* writeFiles(tmpDir, { "components/Probe.md": probe( [" value:", " type: string", ' default: "fallback"'], @@ -720,100 +695,108 @@ describe("Tier EU — a prop that evaluates to undefined", () => { "", ].join("\n"), }); - const output = yield* said(tmpDir, new InMemoryStream()); + const output = yield* said(tmpDir, stream); // Omission happens before validation, which is the only reason the schema // gets to supply its default. expect(output).toContain("own=true value=fallback"); }); - it("EU4: a required prop is missing, and the body does not run", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); - yield* writeFiles(tmpDir, { - "components/Probe.md": [ - "---", - "props:", - " type: object", - " properties:", - " value: {}", - " required:", - " - value", - " additionalProperties: false", - "---", - "THE BODY RAN", - ].join("\n"), - "doc.md": [ - "```js eval", - "const record = {};", - "```", - "", - "", - ].join("\n"), - }); - const output = yield* said(tmpDir, new InMemoryStream()); - expect(output).toContain("value"); - expect(output).toContain("required"); - expect(output).not.toContain("THE BODY RAN"); - }); + expressionCase( + "EU4: a required prop is missing, and the body does not run", + function* (stream, tmpDir) { + yield* writeFiles(tmpDir, { + "components/Probe.md": [ + "---", + "props:", + " type: object", + " properties:", + " value: {}", + " required:", + " - value", + " additionalProperties: false", + "---", + "THE BODY RAN", + ].join("\n"), + "doc.md": [ + "```js eval", + "const record = {};", + "```", + "", + "", + ].join("\n"), + }); + const output = yield* said(tmpDir, stream); + expect(output).toContain("value"); + expect(output).toContain("required"); + expect(output).not.toContain("THE BODY RAN"); + }, + ); - it("EU5: `null` is a value the author wrote, not an absence", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); - yield* writeFiles(tmpDir, { - "components/Probe.md": probe( - [" value:", ' type: ["string", "null"]'], - 'own=${Object.hasOwn(props, "value")} value=${String(props.value)};', - ), - "doc.md": [ - "```js eval", - "const record = {};", - "```", - "", - "", - "", - "", - ].join("\n"), - }); - const output = yield* said(tmpDir, new InMemoryStream()); - expect(output).toContain("own=true value=null;"); - expect(output).toContain("own=false value=undefined;"); - }); + expressionCase( + "EU5: `null` is a value the author wrote, not an absence", + function* (stream, tmpDir) { + yield* writeFiles(tmpDir, { + "components/Probe.md": probe( + [" value:", ' type: ["string", "null"]'], + 'own=${Object.hasOwn(props, "value")} value=${String(props.value)};', + ), + "doc.md": [ + "```js eval", + "const record = {};", + "```", + "", + "", + "", + "", + ].join("\n"), + }); + const output = yield* said(tmpDir, stream); + expect(output).toContain("own=true value=null;"); + expect(output).toContain("own=false value=undefined;"); + }, + ); - it("EU6: an expression that throws is still the failure it was", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); - yield* writeFiles(tmpDir, { - "components/Probe.md": probe([" value: {}"]), - "doc.md": [ - "```js eval", - "const record = { boom() { throw new Error('no value here'); } };", - "```", - "", - "", - ].join("\n"), - }); - const output = yield* said(tmpDir, new InMemoryStream()); - expect(output).toContain("Failed to evaluate expression prop"); - expect(output).toContain("no value here"); - }); + expressionCase( + "EU6: an expression that throws is still the failure it was", + function* (stream, tmpDir) { + yield* writeFiles(tmpDir, { + "components/Probe.md": probe([" value: {}"]), + "doc.md": [ + "```js eval", + "const record = { boom() { throw new Error('no value here'); } };", + "```", + "", + "", + ].join("\n"), + }); + const output = yield* said(tmpDir, stream); + expect(output).toContain("Failed to evaluate expression prop"); + expect(output).toContain("no value here"); + }, + ); - it("EU7: a nested `undefined` keeps its native JSON reading", function* () { - const tmpDir = yield* useTempDirectory("expr-props-test-"); - yield* writeFiles(tmpDir, { - "components/Probe.md": probe( - [" value:", " type: object"], - "json=${JSON.stringify(props.value)}", - ), - "doc.md": [ - "```js eval", - "const record = {};", - "```", - "", - "", - ].join("\n"), - }); - const output = yield* said(tmpDir, new InMemoryStream()); - // One `JSON.stringify` decides everything below the root, as it always - // has: an object member goes, an array entry becomes `null`. - expect(output).toContain('json={"b":[null,1],"c":2}'); - }); + expressionCase( + "EU7: a nested `undefined` keeps its native JSON reading", + function* (stream, tmpDir) { + yield* writeFiles(tmpDir, { + "components/Probe.md": probe( + [" value:", " type: object"], + "json=${JSON.stringify(props.value)}", + ), + "doc.md": [ + "```js eval", + "const record = {};", + "```", + "", + "", + ].join("\n"), + }); + const output = yield* said(tmpDir, stream); + // One `JSON.stringify` decides everything below the root, as it always + // has: an object member goes, an array entry becomes `null`. + expect(output).toContain('json={"b":[null,1],"c":2}'); + }, + ); it("EU8: nothing durable holds it, and replay reconstructs the same props", function* () { const document = [ diff --git a/packages/core/tests/root-props.test.ts b/packages/core/tests/root-props.test.ts index cad7a8cc0..9f0cf5023 100644 --- a/packages/core/tests/root-props.test.ts +++ b/packages/core/tests/root-props.test.ts @@ -5,6 +5,7 @@ * validated and defaulted before any body effect, then available through * `{props.name}`, bare binding interpolation, and eval blocks. */ +import { journalCases } from "../../test-support/journal-cases.ts"; import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { InMemoryStream } from "@executablemd/durable-streams"; @@ -80,60 +81,103 @@ const NESTED_CONCISE = [ "", ].join("\n"); -function* runPath(path: string, props?: Record) { - const execution = yield* execute({ path, stream: new InMemoryStream(), props }); +function* runPath(path: string, props?: Record, stream = new InMemoryStream()) { + const execution = yield* execute({ path, stream, props }); const output = yield* forEach(function* () {}, execution.output); const result = yield* execution; return { output, result }; } -function* runDoc(files: Record, path: string, props?: Record) { +function* runDoc( + files: Record, + path: string, + props?: Record, + stream?: InMemoryStream, +) { yield* useStubFs(files); - return yield* runPath(path, props); + return yield* runPath(path, props, stream); } +const rootCase = journalCases("packages/core/tests/root-props.test.ts"); + describe("Tier RP — root document properties", () => { - it("RP1: supplied props reach interpolation without bare prop bindings", function* () { - const { output, result } = yield* runDoc({ "hello.md": GREETING }, "hello.md", { - name: "Ada", - loud: true, - }); - expect(result.ok).toBe(true); - expect(output).toContain("Hello, Ada!"); - expect(output).toContain("loud=true"); - expect(output).toContain("bare={name}"); - }); + rootCase( + "RP1: supplied props reach interpolation without bare prop bindings", + "hello.md", + function* (stream) { + const { output, result } = yield* runDoc( + { "hello.md": GREETING }, + "hello.md", + { + name: "Ada", + loud: true, + }, + stream, + ); + expect(result.ok).toBe(true); + expect(output).toContain("Hello, Ada!"); + expect(output).toContain("loud=true"); + expect(output).toContain("bare={name}"); + }, + ); - it("RP2: schema defaults apply to the root", function* () { - const { output } = yield* runDoc({ "hello.md": GREETING }, "hello.md", { name: "Ada" }); + rootCase("RP2: schema defaults apply to the root", "hello.md", function* (stream) { + const { output } = yield* runDoc({ "hello.md": GREETING }, "hello.md", { name: "Ada" }, stream); expect(output).toContain("loud=false"); }); - it("RP3: a missing required property prevents every body effect", function* () { - const { output, result } = yield* runDoc({ "doc.md": SIDE_EFFECT }, "doc.md", {}); - expect(result.ok).toBe(false); - expect(output).not.toContain("SIDE_EFFECT_MARKER"); - }); + rootCase( + "RP3: a missing required property prevents every body effect", + "doc.md", + function* (stream) { + const { output, result } = yield* runDoc({ "doc.md": SIDE_EFFECT }, "doc.md", {}, stream); + expect(result.ok).toBe(false); + expect(output).not.toContain("SIDE_EFFECT_MARKER"); + }, + ); - it("RP4: an invalid property prevents every body effect", function* () { - const { output, result } = yield* runDoc({ "doc.md": SIDE_EFFECT }, "doc.md", { name: 12 }); + rootCase("RP4: an invalid property prevents every body effect", "doc.md", function* (stream) { + const { output, result } = yield* runDoc( + { "doc.md": SIDE_EFFECT }, + "doc.md", + { name: 12 }, + stream, + ); expect(result.ok).toBe(false); expect(output).not.toContain("SIDE_EFFECT_MARKER"); }); - it("RP5: an undeclared property is rejected by the root schema", function* () { - const { result } = yield* runDoc({ "doc.md": SIDE_EFFECT }, "doc.md", { - name: "Ada", - nope: 1, - }); - expect(result.ok).toBe(false); - }); + rootCase( + "RP5: an undeclared property is rejected by the root schema", + "doc.md", + function* (stream) { + const { result } = yield* runDoc( + { "doc.md": SIDE_EFFECT }, + "doc.md", + { + name: "Ada", + nope: 1, + }, + stream, + ); + expect(result.ok).toBe(false); + }, + ); - it("RP6: a document without props keeps its existing behavior", function* () { - const { output, result } = yield* runDoc({ "plain.md": NO_PROPS }, "plain.md"); - expect(result.ok).toBe(true); - expect(output).toContain("PLAIN_MARKER"); - }); + rootCase( + "RP6: a document without props keeps its existing behavior", + "plain.md", + function* (stream) { + const { output, result } = yield* runDoc( + { "plain.md": NO_PROPS }, + "plain.md", + undefined, + stream, + ); + expect(result.ok).toBe(true); + expect(output).toContain("PLAIN_MARKER"); + }, + ); }); describe("Tier RI — document inspection", () => { @@ -225,15 +269,24 @@ describe("Tier RI — document inspection", () => { }); describe("Tier RS — concise props declarations", () => { - it("RS1: a concise root receives props and applies defaults", function* () { - const { output, result } = yield* runDoc({ "hello.md": GREETING_CONCISE }, "hello.md", { - name: "Ada", - }); - expect(result.ok).toBe(true); - expect(output).toContain("Hello, Ada!"); - expect(output).toContain("loud=false"); - expect(output).toContain("bare={name}"); - }); + rootCase( + "RS1: a concise root receives props and applies defaults", + "hello.md", + function* (stream) { + const { output, result } = yield* runDoc( + { "hello.md": GREETING_CONCISE }, + "hello.md", + { + name: "Ada", + }, + stream, + ); + expect(result.ok).toBe(true); + expect(output).toContain("Hello, Ada!"); + expect(output).toContain("loud=false"); + expect(output).toContain("bare={name}"); + }, + ); it("RS2: the concise and full spellings behave identically", function* () { yield* useStubFs({ "concise.md": GREETING_CONCISE, "full.md": GREETING }); @@ -242,22 +295,45 @@ describe("Tier RS — concise props declarations", () => { expect(concise.output).toBe(full.output); }); - it("RS3: a missing required property prevents every body effect", function* () { - const { output, result } = yield* runDoc({ "hello.md": GREETING_CONCISE }, "hello.md", {}); - expect(result.ok).toBe(false); - expect(output).not.toContain("Hello"); - }); + rootCase( + "RS3: a missing required property prevents every body effect", + "hello.md", + function* (stream) { + const { output, result } = yield* runDoc( + { "hello.md": GREETING_CONCISE }, + "hello.md", + {}, + stream, + ); + expect(result.ok).toBe(false); + expect(output).not.toContain("Hello"); + }, + ); - it("RS4: the implicit closed object rejects an undeclared property", function* () { - const { result } = yield* runDoc({ "hello.md": GREETING_CONCISE }, "hello.md", { - name: "Ada", - nope: 1, - }); - expect(result.ok).toBe(false); - }); + rootCase( + "RS4: the implicit closed object rejects an undeclared property", + "hello.md", + function* (stream) { + const { result } = yield* runDoc( + { "hello.md": GREETING_CONCISE }, + "hello.md", + { + name: "Ada", + nope: 1, + }, + stream, + ); + expect(result.ok).toBe(false); + }, + ); - it("RS5: object defaults fill recursively", function* () { - const { output, result } = yield* runDoc({ "nested.md": NESTED_CONCISE }, "nested.md", {}); + rootCase("RS5: object defaults fill recursively", "nested.md", function* (stream) { + const { output, result } = yield* runDoc( + { "nested.md": NESTED_CONCISE }, + "nested.md", + {}, + stream, + ); expect(result.ok).toBe(true); expect(output).toContain("port=8080"); }); From dbb05715b72c505ecfefcdaeee4f7cf97d7d99a0 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:59:01 -0500 Subject: [PATCH 26/78] test: preserve independently bounded subprocess journals --- packages/cli/src/test-diagnostics.ts | 14 +- packages/cli/tests/agent-adapters.test.ts | 187 ++++++++++-------- .../cli/tests/fixtures/agent-assemblies.ts | 9 +- .../git/tests/run-composition-managed.test.ts | 11 +- .../tests/support/run-composition-child.ts | 5 +- packages/test-support/subprocess-journal.ts | 102 ++++++++-- .../tests/subprocess-journal.test.ts | 58 ++++-- 7 files changed, 256 insertions(+), 130 deletions(-) diff --git a/packages/cli/src/test-diagnostics.ts b/packages/cli/src/test-diagnostics.ts index 9762e194a..2e0620e70 100644 --- a/packages/cli/src/test-diagnostics.ts +++ b/packages/cli/src/test-diagnostics.ts @@ -60,7 +60,7 @@ export interface TestDiagnostics { * the file each execution saves is named by its own position in this * command, so two executions never share one. */ - execution(kind: "root" | "child", source: string): ExecutionDiagnostics; + execution(kind: "root" | "child", source: string, profile?: string): ExecutionDiagnostics; /** The first failure to deliver a progress line, or `Ok` when none failed. */ delivery(): Result; } @@ -137,12 +137,12 @@ export function useTestDiagnostics( const counts = { root: 0, child: 0 }; yield* provide({ - execution(kind, source) { + execution(kind, source, profile) { const ordinal = ++counts[kind]; const stem = join(directory, `${kind}-${ordinal}`); const file = `${stem}.jsonl`; const displayedSource = shown(source); - const named = `${kind} ${ordinal} ${displayedSource}`; + const named = `${kind} ${ordinal} ${displayedSource}${profile === undefined ? "" : ` (${profile})`}`; const context = kind === "root" ? "" : `${named}: `; return { observe: () => observe(owner, shown, (line) => emit(`${context}${line}`)), @@ -153,7 +153,13 @@ export function useTestDiagnostics( if (attribution !== undefined) { yield* writeTextFile( `${stem}.case.json`, - JSON.stringify({ ...attribution, kind, ordinal, source: displayedSource }) + "\n", + JSON.stringify({ + ...attribution, + kind, + ordinal, + source: displayedSource, + profile, + }) + "\n", ); } yield* writeTextFile(file, events.map(serializeDurableEvent).join("")); diff --git a/packages/cli/tests/agent-adapters.test.ts b/packages/cli/tests/agent-adapters.test.ts index 7c2aa08eb..0271c0e86 100644 --- a/packages/cli/tests/agent-adapters.test.ts +++ b/packages/cli/tests/agent-adapters.test.ts @@ -1,3 +1,4 @@ +import { Writable } from "node:stream"; import { mkdtemp, chmod, realpath } from "node:fs/promises"; import { cliBase } from "@executablemd/test-support/launch"; import { fileURLToPath } from "node:url"; @@ -44,6 +45,7 @@ import { ASSEMBLY_PROFILES, ASSEMBLY_SOURCE } from "./support/assembly-profiles. import { checkSubprocessJournals, parseSubprocessJournal, + readSubprocessSnapshot, } from "../../test-support/subprocess-journal.ts"; import type { SubprocessJournal } from "../../test-support/subprocess-journal.ts"; @@ -265,14 +267,11 @@ function checkEnvironment(environmentPreserved: unknown): void { } function assemblyJournals(value: unknown): SubprocessJournal[] { - if (!Array.isArray(value) || value.length !== ASSEMBLY_PROFILES.length) { - return []; - } - const journals = value.map((entry) => ({ + return ASSEMBLY_PROFILES.map((profile, index) => ({ source: ASSEMBLY_SOURCE, - events: parseSubprocessJournal(entry), + profile, + snapshot: readSubprocessSnapshot(value, index), })); - return journals.every(({ events }) => events.length > 0) ? journals : []; } function* assemblyInputs( @@ -280,6 +279,7 @@ function* assemblyInputs( name: string, verify = checkEnvironment, inspect?: (journals: readonly SubprocessJournal[]) => void, + options: { oversizedPlan?: boolean; sink?: Writable } = {}, ): Operation { const root = yield* until(realpath(yield* until(mkdtemp(join(tmpdir(), "xmd assemblies "))))); yield* ensure(() => rm(root, { recursive: true, force: true })); @@ -296,6 +296,7 @@ function* assemblyInputs( root, agent, "--capture-journal", + ...(options.oversizedPlan ? ["--oversized-plan"] : []), ], env: { [variable]: host }, }); @@ -311,11 +312,11 @@ function* assemblyInputs( } const { results: rows, environmentPreserved, journals: rawJournals } = output; const journals = assemblyJournals(rawJournals); - inspect?.(journals); yield* checkSubprocessJournals( { owner: ASSEMBLY_OWNER, suite: ASSEMBLY_SUITE, name }, journals, lift(() => { + inspect?.(journals); verify(environmentPreserved); expect(rows.map((row: { profile: string }) => row.profile)).toEqual(ASSEMBLY_PROFILES); for (const row of rows) { @@ -331,6 +332,7 @@ function* assemblyInputs( } } }), + options.sink, ); } @@ -342,80 +344,107 @@ describe(ASSEMBLY_SUITE, () => { it(claude, () => assemblyInputs("claude", claude)); it(codex, () => assemblyInputs("codex", codex)); - const witness = "attributes each assembly profile when the joined parent assertion fails"; - it(witness, function* () { - const root = yield* useTempDirectory("xmd-assembly-journals-"); - function run( - artifacts: string, - verify: typeof checkEnvironment, - inspect?: Parameters[3], - ) { - return scoped(function* () { - yield* API.Env.around({ - *env([name], next) { - return name === "XMD_TEST_ARTIFACTS" ? artifacts : yield* next(name); - }, - }); - yield* assemblyInputs("claude", witness, verify, inspect); + for (const oversizedPlan of [false, true]) { + const witness = oversizedPlan + ? "keeps sibling journals when one joined assembly profile exceeds its budget" + : "attributes each assembly profile when the joined parent assertion fails"; + it(witness, function* () { + const messages: string[] = []; + const sink = new Writable({ + write(chunk, _encoding, callback) { + messages.push(String(chunk)); + callback(); + }, }); - } + const root = yield* useTempDirectory("xmd-assembly-journals-"); + function run( + artifacts: string, + verify: typeof checkEnvironment, + inspect?: Parameters[3], + ) { + return scoped(function* () { + yield* API.Env.around({ + *env([name], next) { + return name === "XMD_TEST_ARTIFACTS" ? artifacts : yield* next(name); + }, + }); + yield* assemblyInputs("claude", witness, verify, inspect, { oversizedPlan, sink }); + }); + } - const passed = join(root, "passed", ".xmd", "test-artifacts"); - yield* run(passed, checkEnvironment, (journals) => { - expect(journals).toHaveLength(ASSEMBLY_PROFILES.length); - }); - expect(yield* exists(passed)).toBe(false); - - const failed = join(root, "failed", ".xmd", "test-artifacts"); - let assertion: unknown; - let caught: unknown; - let received: readonly SubprocessJournal[] = []; - try { - yield* run( - failed, - (value) => { - checkEnvironment(value); - try { - checkEnvironment(false); - } catch (error) { - assertion = error; - throw error; - } - }, - (journals) => { - received = journals; - }, - ); - } catch (error) { - caught = error; - } - expect(assertion).toBeInstanceOf(Error); - expect(caught).toBe(assertion); - expect(received).toHaveLength(ASSEMBLY_PROFILES.length); - const invocations = yield* readdir(failed); - expect(invocations).toHaveLength(1); - const directory = join(failed, invocations[0]); - const expectedFiles = ASSEMBLY_PROFILES.flatMap((_, index) => [ - `child-${index + 1}.case.json`, - `child-${index + 1}.jsonl`, - ]); - expect((yield* readdir(directory)).sort()).toEqual(expectedFiles.sort()); - for (const [index, journal] of received.entries()) { - const ordinal = index + 1; - const stem = join(directory, `child-${ordinal}`); - expect(JSON.parse(yield* readTextFile(`${stem}.case.json`))).toEqual({ - owner: ASSEMBLY_OWNER, - suite: ASSEMBLY_SUITE, - name: witness, - kind: "child", - ordinal, - source: ASSEMBLY_SOURCE, + const passed = join(root, "passed", ".xmd", "test-artifacts"); + yield* run(passed, checkEnvironment, (journals) => { + expect(journals).toHaveLength(ASSEMBLY_PROFILES.length); }); - const events = parseSubprocessJournal( - (yield* readTextFile(`${stem}.jsonl`)).trimEnd().split("\n"), + expect(yield* exists(passed)).toBe(false); + expect(messages).toEqual([]); + + const failed = join(root, "failed", ".xmd", "test-artifacts"); + let assertion: unknown; + let caught: unknown; + let received: readonly SubprocessJournal[] = []; + try { + yield* run( + failed, + (value) => { + checkEnvironment(value); + try { + checkEnvironment(false); + } catch (error) { + assertion = error; + throw error; + } + }, + (journals) => { + received = journals; + }, + ); + } catch (error) { + caught = error; + } + expect(assertion).toBeInstanceOf(Error); + expect(caught).toBe(assertion); + expect(received).toHaveLength(ASSEMBLY_PROFILES.length); + const invocations = yield* readdir(failed); + expect(invocations).toHaveLength(1); + const directory = join(failed, invocations[0]); + const saved = received.flatMap(({ profile, snapshot }, index) => + typeof snapshot === "string" ? [] : [{ profile, events: snapshot, ordinal: index + 1 }], ); - expect(events).toEqual(journal.events); - expect(events.at(-1)).toMatchObject({ type: "close", coroutineId: "root" }); - } - }); + expect(saved.map(({ profile }) => profile)).toEqual( + ASSEMBLY_PROFILES.filter((profile) => !oversizedPlan || profile !== "plan"), + ); + const omissions = messages.filter((message) => message.includes("journal not saved")); + expect(omissions).toEqual( + oversizedPlan + ? [ + "[xmd test] journal not saved for child 2 assembly.md (plan): snapshot exceeds journal budget\n", + ] + : [], + ); + const expectedFiles = saved.flatMap(({ ordinal }) => [ + `child-${ordinal}.case.json`, + `child-${ordinal}.jsonl`, + ]); + expect((yield* readdir(directory)).sort()).toEqual(expectedFiles.sort()); + for (const journal of saved) { + const { ordinal, profile } = journal; + const stem = join(directory, `child-${ordinal}`); + expect(JSON.parse(yield* readTextFile(`${stem}.case.json`))).toEqual({ + owner: ASSEMBLY_OWNER, + suite: ASSEMBLY_SUITE, + name: witness, + kind: "child", + ordinal, + source: ASSEMBLY_SOURCE, + profile, + }); + const events = parseSubprocessJournal( + (yield* readTextFile(`${stem}.jsonl`)).trimEnd().split("\n"), + ); + expect(events).toEqual(journal.events); + expect(events.at(-1)).toMatchObject({ type: "close", coroutineId: "root" }); + } + }); + } }); diff --git a/packages/cli/tests/fixtures/agent-assemblies.ts b/packages/cli/tests/fixtures/agent-assemblies.ts index 23b8d8981..b6b6993fa 100644 --- a/packages/cli/tests/fixtures/agent-assemblies.ts +++ b/packages/cli/tests/fixtures/agent-assemblies.ts @@ -42,7 +42,12 @@ main(function* () { const journals: string[][] = []; for (const profile of ASSEMBLY_PROFILES) { const fake = createFakeAcp(); - fake.script({ reply: "assembled" }); + fake.script({ + reply: + capture && process.argv[5] === "--oversized-plan" && profile === "plan" + ? "assembled ".repeat(2_000) + : "assembled", + }); const stream = new InMemoryStream(); yield* scoped(function* () { const host = yield* useScope(); @@ -98,5 +103,5 @@ main(function* () { ...new Set([...Object.keys(environment), ...Object.keys(process.env)]), ].every((key) => environment[key] === process.env[key]); const result = { results, environmentPreserved }; - console.log(capture ? boundedJournalResult(result, { journals }) : JSON.stringify(result)); + console.log(capture ? boundedJournalResult(result, journals) : JSON.stringify(result)); }); diff --git a/packages/git/tests/run-composition-managed.test.ts b/packages/git/tests/run-composition-managed.test.ts index 45ee71651..6f8ad70a5 100644 --- a/packages/git/tests/run-composition-managed.test.ts +++ b/packages/git/tests/run-composition-managed.test.ts @@ -22,6 +22,7 @@ import { useTempDirectory } from "@executablemd/test-support/temp"; import { checkSubprocessJournals, parseSubprocessJournal, + readSubprocessSnapshot, } from "../../test-support/subprocess-journal.ts"; import { join } from "node:path"; import { git, useBareRemote } from "./support/git-remotes.ts"; @@ -546,7 +547,7 @@ describe(ORC12_SUITE, () => { cwd: string, source: string, capture = false, - ): Operation & { events: DurableEvent[] }> { + ): Operation }> { const outcome = spawnSync( process.execPath, [ @@ -587,7 +588,7 @@ describe(ORC12_SUITE, () => { reason: "reason" in result && typeof result.reason === "string" ? result.reason : undefined, message: "message" in result && typeof result.message === "string" ? result.message : undefined, - events: capture && "journal" in result ? parseSubprocessJournal(result.journal) : [], + snapshot: readSubprocessSnapshot("journals" in result ? result.journals : undefined, 0), }; } @@ -632,7 +633,7 @@ describe(ORC12_SUITE, () => { expect(refused.kind).toBe("refused"); expect(refused.reason).toBe("in-use"); expect(refused.message).toContain("another process is working in"); - expect(refused.events).toEqual([]); + expect(refused.snapshot).toBe("snapshot absent"); // And nothing under the slot moved. expect(yield* fingerprintTree(held.slot)).toEqual(bytes); @@ -689,11 +690,11 @@ describe(ORC12_SUITE, () => { const later = yield* elsewhere(root, checkout.root, document, true); yield* checkSubprocessJournals( { owner: OWNER, suite: ORC12_SUITE, name }, - [{ source: "", events: later.events }], + [{ source: "", snapshot: later.snapshot }], function* () { expect(later.kind).toBe("selected"); expect(later.bound).toBe(slot.checkout); - yield* check(slot, later.events); + yield* check(slot, typeof later.snapshot === "string" ? [] : later.snapshot); }, ); }); diff --git a/packages/git/tests/support/run-composition-child.ts b/packages/git/tests/support/run-composition-child.ts index 26c5e6ee6..2c78d7467 100644 --- a/packages/git/tests/support/run-composition-child.ts +++ b/packages/git/tests/support/run-composition-child.ts @@ -29,7 +29,6 @@ export interface ChildOutcome { /** The fixed word a managed-checkout refusal is reported under. */ readonly reason?: string; readonly message?: string; - readonly journal?: readonly string[]; } await main(function* () { @@ -67,9 +66,7 @@ await main(function* () { const line = capture === "--capture-journal" - ? boundedJournalResult(outcome, { - journal: (yield* stream.readAll()).map(serializeDurableEvent), - }) + ? boundedJournalResult(outcome, [(yield* stream.readAll()).map(serializeDurableEvent)]) : JSON.stringify(outcome); process.stdout.write(`${line}\n`); }); diff --git a/packages/test-support/subprocess-journal.ts b/packages/test-support/subprocess-journal.ts index 6a0319b15..8927fb44c 100644 --- a/packages/test-support/subprocess-journal.ts +++ b/packages/test-support/subprocess-journal.ts @@ -1,18 +1,63 @@ import { Buffer } from "node:buffer"; import process from "node:process"; -import { scoped } from "effection"; +import { ensure, scoped } from "effection"; import type { Operation } from "effection"; import { parseDurableEvent } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; import { withFailureJournal } from "@executablemd/testing"; import { useTestDiagnostics } from "../cli/src/test-diagnostics.ts"; +import type { DeliverySink } from "../cli/src/stdout-delivery.ts"; import type { JournalCase } from "../cli/src/test-diagnostics.ts"; const MAX_ENVELOPE_BYTES = 64 * 1024; -export function boundedJournalResult(result: object, evidence: object): string { - const enriched = JSON.stringify({ ...result, ...evidence }); - return Buffer.byteLength(enriched) + 1 <= MAX_ENVELOPE_BYTES ? enriched : JSON.stringify(result); +const MAX_SNAPSHOT_BYTES = 16 * 1024; +const OVERFLOW = "snapshot exceeds journal budget"; +const INVALID = "invalid snapshot"; +const MISSING = "snapshot absent"; + +type Snapshot = readonly DurableEvent[] | typeof OVERFLOW | typeof INVALID | typeof MISSING; + +function fitsEnvelope(text: string): boolean { + return Buffer.byteLength(text) + 1 <= MAX_ENVELOPE_BYTES; +} + +export function boundedJournalResult(result: object, snapshots: readonly string[][]): string { + // Reserve every omission slot before admitting any snapshot. + const journals: (string[] | typeof OVERFLOW)[] = snapshots.map(() => OVERFLOW); + const serialize = () => JSON.stringify({ ...result, journals }); + let envelope = serialize(); + if (!fitsEnvelope(envelope)) { + return JSON.stringify(result); + } + for (const [index, records] of snapshots.entries()) { + if (Buffer.byteLength(JSON.stringify(records)) > MAX_SNAPSHOT_BYTES) { + continue; + } + journals[index] = records; + const candidate = serialize(); + if (fitsEnvelope(candidate)) { + envelope = candidate; + } else { + journals[index] = OVERFLOW; + } + } + return envelope; +} + +export function readSubprocessSnapshot(value: unknown, index: number): Snapshot { + const entry: unknown = Array.isArray(value) ? value[index] : undefined; + if (entry === undefined) { + return MISSING; + } + if ( + entry === OVERFLOW || + (Array.isArray(entry) && Buffer.byteLength(JSON.stringify(entry)) > MAX_SNAPSHOT_BYTES) + ) { + return OVERFLOW; + } + const events = parseSubprocessJournal(entry); + return events.length === 0 ? INVALID : events; } export function parseSubprocessJournal(value: unknown): DurableEvent[] { @@ -35,7 +80,8 @@ export function parseSubprocessJournal(value: unknown): DurableEvent[] { export interface SubprocessJournal { readonly source: string; - readonly events: readonly DurableEvent[]; + readonly profile?: string; + readonly snapshot: Snapshot; } /** Hold settled records from a joined synthetic child through its parent's assertions. */ @@ -43,27 +89,41 @@ export function checkSubprocessJournals( testCase: JournalCase, journals: readonly SubprocessJournal[], check: () => Operation, + sink: DeliverySink = process.stderr, ): Operation { if (journals.length === 0) { return check(); } return scoped(function* () { - const diagnostics = yield* useTestDiagnostics(process.stderr, testCase); - const captures = journals.map((journal) => ({ - events: journal.events, - host: diagnostics.execution("child", journal.source).journal(() => false), + const diagnostics = yield* useTestDiagnostics(sink, testCase); + const captures = journals.map(({ snapshot, source, profile }) => ({ + snapshot, + host: diagnostics.execution("child", source, profile).journal(() => false), })); - const run = captures.reduceRight<() => Operation>( - (next, { events, host }) => - () => - withFailureJournal(host, function* (buffer) { - for (const event of events) { - yield* buffer.append(event); - } - return yield* next(); - }), - check, - ); - return yield* run(); + let passed = false; + yield* ensure(function* () { + if (!passed) { + for (const { snapshot, host } of captures) { + if (typeof snapshot === "string") { + yield* host.reportSaveFailure(new Error(snapshot)); + } + } + } + }); + const run = captures.reduceRight<() => Operation>((next, { snapshot, host }) => { + if (typeof snapshot === "string") { + return next; + } + return () => + withFailureJournal(host, function* (buffer) { + for (const event of snapshot) { + yield* buffer.append(event); + } + return yield* next(); + }); + }, check); + const result = yield* scoped(run); + passed = true; + return result; }); } diff --git a/packages/test-support/tests/subprocess-journal.test.ts b/packages/test-support/tests/subprocess-journal.test.ts index bc10c466a..3096bddbc 100644 --- a/packages/test-support/tests/subprocess-journal.test.ts +++ b/packages/test-support/tests/subprocess-journal.test.ts @@ -1,27 +1,55 @@ +import { Buffer } from "node:buffer"; import { describe, it } from "../bdd.ts"; import { expect } from "../expect.ts"; import { serializeDurableEvent } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; -import { boundedJournalResult, parseSubprocessJournal } from "../subprocess-journal.ts"; +import { boundedJournalResult, readSubprocessSnapshot } from "../subprocess-journal.ts"; + +const close: DurableEvent = { + type: "close", + coroutineId: "root", + result: { status: "ok", value: null }, +}; +const line = serializeDurableEvent(close); describe("private subprocess journal envelope", () => { // deno-lint-ignore require-yield - it("keeps the ordinary result when the UTF-8 envelope exceeds its limit", function* () { - const result = { kind: "selected" }; - expect(JSON.parse(boundedJournalResult(result, { journal: ["é".repeat(32 * 1024)] }))).toEqual( - result, - ); + it("preserves the original result when even the omission slots cannot fit", function* () { + const result = { kind: "selected", value: "é".repeat(32 * 1024) }; + const printed = JSON.parse(boundedJournalResult(result, [[line]])); + expect(printed).toEqual(result); + expect(readSubprocessSnapshot(printed.journals, 0)).toBe("snapshot absent"); + }); + + // deno-lint-ignore require-yield + it("keeps fixed slots and valid siblings across both byte limits", function* () { + const large = [ + serializeDurableEvent({ + ...close, + result: { status: "ok", value: "é".repeat(7 * 1024) }, + }), + ]; + const oversized = ["é".repeat(16 * 1024)]; + const printed = boundedJournalResult({ value: "é".repeat(12 * 1024) }, [ + large, + oversized, + large, + large, + [line], + ]); + expect(Buffer.byteLength(printed) + 1).toBeLessThanOrEqual(64 * 1024); + const { journals } = JSON.parse(printed); + expect(readSubprocessSnapshot(journals, 0)).toHaveLength(1); + expect(readSubprocessSnapshot(journals, 1)).toBe("snapshot exceeds journal budget"); + expect(readSubprocessSnapshot(journals, 2)).toHaveLength(1); + expect(readSubprocessSnapshot(journals, 3)).toBe("snapshot exceeds journal budget"); + expect(readSubprocessSnapshot(journals, 4)).toEqual([close]); }); // deno-lint-ignore require-yield - it("rejects a partially valid snapshot", function* () { - const event: DurableEvent = { - type: "close", - coroutineId: "root", - result: { status: "ok", value: null }, - }; - const line = serializeDurableEvent(event); - expect(parseSubprocessJournal([line])).toEqual([event]); - expect(parseSubprocessJournal([line, "malformed"])).toEqual([]); + it("rejects a partially valid snapshot without losing its sibling", function* () { + const { journals } = JSON.parse(boundedJournalResult({}, [[line, "malformed"], [line]])); + expect(readSubprocessSnapshot(journals, 0)).toBe("invalid snapshot"); + expect(readSubprocessSnapshot(journals, 1)).toEqual([close]); }); }); From c5deede5ba7a1a8599bb45a65232882d0c5c3a53 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 14:59:47 -0500 Subject: [PATCH 27/78] test: capture additional held host and hook journals --- .../tests/component-invocation-hooks.test.ts | 149 ++--- .../core/tests/host-generated-root.test.ts | 518 +++++++++--------- 2 files changed, 349 insertions(+), 318 deletions(-) diff --git a/packages/core/tests/component-invocation-hooks.test.ts b/packages/core/tests/component-invocation-hooks.test.ts index 8360c357b..f2fe6c461 100644 --- a/packages/core/tests/component-invocation-hooks.test.ts +++ b/packages/core/tests/component-invocation-hooks.test.ts @@ -28,8 +28,7 @@ const props = { type: "object", properties: {}, additionalProperties: false }; function declaration(body: () => Operation, name = "Observed"): IdentityComponent { return { name, origin: "test://observation", props, factory: () => body }; } -function* run(source: string, installation: ExecutionInstallation) { - const stream = new InMemoryStream(); +function* run(source: string, installation: ExecutionInstallation, stream = new InMemoryStream()) { const execution = yield* executeInstalled({ ...retainedSource("hooks.md", source), stream }, [ installation, ]); @@ -434,75 +433,91 @@ describe("Installation-owned component observation", () => { }); describe("Invocation observation settlement", () => { - it("R4a: successful component cleanup and after cleanup precede caller continuation", function* () { - const cleaning = withResolvers(); - const release = withResolvers(); - const notified = withResolvers(); - const afterRelease = withResolvers(); - let after = false; - let continued = false; - const execution = yield* spawn(function* () { - const result = yield* run('', { - components: [ - declaration(function* () { - yield* ensure(function* () { - cleaning.resolve(); - yield* release.operation; - }); - return { actual: true }; - }), - ], - componentInvocations: { - *after(_observation, result, cancelled) { - after = true; - expect(result.ok && result.value).toEqual({ actual: true }); - expect(cancelled).toBe(false); - yield* ensure(() => afterRelease.operation); - notified.resolve(); + heldHostCase( + "R4a: successful component cleanup and after cleanup precede caller continuation", + function* (stream) { + const cleaning = withResolvers(); + const release = withResolvers(); + const notified = withResolvers(); + const afterRelease = withResolvers(); + let after = false; + let continued = false; + const execution = yield* spawn(function* () { + const result = yield* run( + '', + { + components: [ + declaration(function* () { + yield* ensure(function* () { + cleaning.resolve(); + yield* release.operation; + }); + return { actual: true }; + }), + ], + componentInvocations: { + *after(_observation, result, cancelled) { + after = true; + expect(result.ok && result.value).toEqual({ actual: true }); + expect(cancelled).toBe(false); + yield* ensure(() => afterRelease.operation); + notified.resolve(); + }, + }, }, - }, + stream, + ); + expect(result.result.ok).toBe(true); + continued = true; }); - expect(result.result.ok).toBe(true); - continued = true; - }); - yield* cleaning.operation; - expect(after).toBe(false); - release.resolve(); - yield* notified.operation; - expect(continued).toBe(false); - afterRelease.resolve(); - yield* execution; - expect(continued).toBe(true); - }); + yield* cleaning.operation; + expect(after).toBe(false); + release.resolve(); + yield* notified.operation; + expect(continued).toBe(false); + afterRelease.resolve(); + yield* execution; + expect(continued).toBe(true); + }, + "hooks.md", + ); - it("R4d: nested notifications unwind and outer after survives inner after failure", function* () { - const order: string[] = []; - const failure = new Error("inner after"); - const components = [ - declaration(function* () { - return yield* content(); - }, "Outer"), - declaration(text, "Inner"), - ]; - const result = yield* run("", { - components, - componentInvocations: { - *before(observation) { - order.push(`before:${observation.component}`); - yield* sleep(0); - }, - *after(observation) { - order.push(`after:${observation.component}`); - if (observation.component === "Inner") { - throw failure; - } - yield* sleep(0); + heldHostCase( + "R4d: nested notifications unwind and outer after survives inner after failure", + function* (stream) { + const order: string[] = []; + const failure = new Error("inner after"); + const components = [ + declaration(function* () { + return yield* content(); + }, "Outer"), + declaration(text, "Inner"), + ]; + const result = yield* run( + "", + { + components, + componentInvocations: { + *before(observation) { + order.push(`before:${observation.component}`); + yield* sleep(0); + }, + *after(observation) { + order.push(`after:${observation.component}`); + if (observation.component === "Inner") { + throw failure; + } + yield* sleep(0); + }, + }, }, - }, - }); - expect(result.result.ok).toBe(false); - expect(order).toEqual(["before:Outer", "before:Inner", "after:Inner", "after:Outer"]); - }); + stream, + ); + expect(result.result.ok).toBe(false); + expect(order).toEqual(["before:Outer", "before:Inner", "after:Inner", "after:Outer"]); + }, + "hooks.md", + ); }); describe("Observed live protected returns", () => { diff --git a/packages/core/tests/host-generated-root.test.ts b/packages/core/tests/host-generated-root.test.ts index 5fdc041c2..59c29d8ed 100644 --- a/packages/core/tests/host-generated-root.test.ts +++ b/packages/core/tests/host-generated-root.test.ts @@ -479,34 +479,36 @@ describe("Tier E1 — only a live trusted handle evaluates a root", () => { expect(Object.keys(hostModule)).not.toContain("evaluateGeneratedXmdRoot"); }); - it("E1c: a completed handle refuses without component work or reopening", function* () { - const stream = new InMemoryStream(); - const invoked: string[] = []; - const held: { execution?: HostExecution } = {}; - const run = yield* withHeldHost( - { stream, installations: [selecting([probe()])] }, - function* (open) { - held.execution = open.execution; - }, - ); - expect(run.completion.ok).toBe(true); + heldHostCase( + "E1c: a completed handle refuses without component work or reopening", + function* (stream) { + const invoked: string[] = []; + const held: { execution?: HostExecution } = {}; + const run = yield* withHeldHost( + { stream, installations: [selecting([probe()])] }, + function* (open) { + held.execution = open.execution; + }, + ); + expect(run.completion.ok).toBe(true); - const execution = held.execution; - if (execution === undefined) { - throw new Error("the case never held an execution"); - } - const after = yield* execution.evaluateGeneratedXmdRoot( - request("\n\n\n", invoked), - ); + const execution = held.execution; + if (execution === undefined) { + throw new Error("the case never held an execution"); + } + const after = yield* execution.evaluateGeneratedXmdRoot( + request("\n\n\n", invoked), + ); - expect(after.ok).toBe(false); - expect(after.ok === false && after.error).toBeInstanceOf(HostExecutionError); - expect(after.ok === false && after.error.message).toContain("has finished"); - // Nothing ran and nothing was recorded: a refusal of availability is not an - // evaluation that failed. - expect(invoked).toEqual([]); - expect(admissions(yield* stream.readAll())).toHaveLength(0); - }); + expect(after.ok).toBe(false); + expect(after.ok === false && after.error).toBeInstanceOf(HostExecutionError); + expect(after.ok === false && after.error.message).toContain("has finished"); + // Nothing ran and nothing was recorded: a refusal of availability is not an + // evaluation that failed. + expect(invoked).toEqual([]); + expect(admissions(yield* stream.readAll())).toHaveLength(0); + }, + ); it("E1d: a document that ended before activating its runner refuses as well", function* () { const stream = new InMemoryStream(); @@ -591,53 +593,55 @@ const MARKER_PROSE = "## Marker\n\nTHE MARKER CHAPTER.\n"; describe("Tier E3 — the documentation this execution captured", () => { beforeAll(() => useTempFileCompiler()); - it("E3a: a named lookup renders a package chapter the root does not admit", function* () { - const stream = new InMemoryStream(); - const counted = { reads: 0 }; - const marked: string[] = []; - const invoked: string[] = []; - const lookup: { answer?: Result } = {}; - const attempted: { answer?: Result } = {}; + heldHostCase( + "E3a: a named lookup renders a package chapter the root does not admit", + function* (stream) { + const counted = { reads: 0 }; + const marked: string[] = []; + const invoked: string[] = []; + const lookup: { answer?: Result } = {}; + const attempted: { answer?: Result } = {}; - const run = yield* withHeldHost( - { - stream, - installations: [markerPackage(MARKER_PROSE, counted, marked), selecting([probe()])], - }, - function* (open) { - lookup.answer = yield* open.execution.evaluateGeneratedXmdRoot( - request('\n\n\n', invoked), - ); - attempted.answer = yield* open.execution.evaluateGeneratedXmdRoot( - request("\n\n\n", invoked, "turn-2"), - ); - }, - ); + const run = yield* withHeldHost( + { + stream, + installations: [markerPackage(MARKER_PROSE, counted, marked), selecting([probe()])], + }, + function* (open) { + lookup.answer = yield* open.execution.evaluateGeneratedXmdRoot( + request('\n\n\n', invoked), + ); + attempted.answer = yield* open.execution.evaluateGeneratedXmdRoot( + request("\n\n\n", invoked, "turn-2"), + ); + }, + ); - expect(run.completion.ok).toBe(true); - const described = rendered(lookup.answer ?? { ok: false, error: new Error("none") }).output; - - // The chapter this execution's package contributed, rendered in full. - // Reading core's own asset instead would answer for core and report this - // component as undocumented. - expect(described).toContain("THE MARKER CHAPTER."); - expect(described).not.toContain("No long-form documentation is available"); - // And the root may not run it. Reading about a component grants nothing, so - // the entry says it is unavailable here. - expect(described).toContain("Marker"); - expect(marked).toEqual([]); - - // Writing the name is refused, before anything runs. - expect(attempted.answer?.ok).toBe(false); - expect(attempted.answer?.ok === false && attempted.answer.error.message).toContain( - "did not admit", - ); - expect(marked).toEqual([]); + expect(run.completion.ok).toBe(true); + const described = rendered(lookup.answer ?? { ok: false, error: new Error("none") }).output; - // Collected once, by the execution, before its root import. Evaluating a - // root reads the captured reference rather than asking the chain again. - expect(counted.reads).toBe(1); - }); + // The chapter this execution's package contributed, rendered in full. + // Reading core's own asset instead would answer for core and report this + // component as undocumented. + expect(described).toContain("THE MARKER CHAPTER."); + expect(described).not.toContain("No long-form documentation is available"); + // And the root may not run it. Reading about a component grants nothing, so + // the entry says it is unavailable here. + expect(described).toContain("Marker"); + expect(marked).toEqual([]); + + // Writing the name is refused, before anything runs. + expect(attempted.answer?.ok).toBe(false); + expect(attempted.answer?.ok === false && attempted.answer.error.message).toContain( + "did not admit", + ); + expect(marked).toEqual([]); + + // Collected once, by the execution, before its root import. Evaluating a + // root reads the captured reference rather than asking the chain again. + expect(counted.reads).toBe(1); + }, + ); heldHostCase( "E3b: late Documentation middleware in the document's own scope changes nothing", @@ -920,80 +924,82 @@ function holding( describe("Tier E5 — cancelling joins before anything else starts", () => { beforeAll(() => useTempFileCompiler()); - it("E5a: a cancelled evaluation holds the caller's halt until its cleanup joins", function* () { - const stream = new InMemoryStream(); - const order: string[] = []; - const invoked: string[] = []; - const reached = withResolvers(); - const release = withResolvers(); - const overlapping: { answer?: Result } = {}; - const fresh: { answer?: Result } = {}; + heldHostCase( + "E5a: a cancelled evaluation holds the caller's halt until its cleanup joins", + function* (stream) { + const order: string[] = []; + const invoked: string[] = []; + const reached = withResolvers(); + const release = withResolvers(); + const overlapping: { answer?: Result } = {}; + const fresh: { answer?: Result } = {}; - yield* scoped(function* () { - const open = yield* useHeldHost({ - stream, - installations: [ - selecting([...declared(invoked), holding(reached, release.operation, order)]), - ], - }); - const held = { - id: "turn-1", - source: "\n\n\n", - }; - const running = yield* spawn(() => open.execution.evaluateGeneratedXmdRoot(held)); - // Entered, so this cancels work in flight rather than work that never - // started — and the admission is already acknowledged. - yield* reached.operation; - expect(admissions(yield* stream.readAll())).toHaveLength(1); + yield* scoped(function* () { + const open = yield* useHeldHost({ + stream, + installations: [ + selecting([...declared(invoked), holding(reached, release.operation, order)]), + ], + }); + const held = { + id: "turn-1", + source: "\n\n\n", + }; + const running = yield* spawn(() => open.execution.evaluateGeneratedXmdRoot(held)); + // Entered, so this cancels work in flight rather than work that never + // started — and the admission is already acknowledged. + yield* reached.operation; + expect(admissions(yield* stream.readAll())).toHaveLength(1); - const halting = yield* spawn(function* () { - yield* running.halt(); - order.push("halt returned"); - }); + const halting = yield* spawn(function* () { + yield* running.halt(); + order.push("halt returned"); + }); - // While the halt is pending, the execution is still busy: a second - // evaluation is refused rather than queued, and it performs nothing. - overlapping.answer = yield* open.execution.evaluateGeneratedXmdRoot( - request("\n\n\n", invoked, "turn-2"), - ); - expect(order).toEqual([]); - expect(invoked).toEqual([]); - expect(admissions(yield* stream.readAll())).toHaveLength(1); + // While the halt is pending, the execution is still busy: a second + // evaluation is refused rather than queued, and it performs nothing. + overlapping.answer = yield* open.execution.evaluateGeneratedXmdRoot( + request("\n\n\n", invoked, "turn-2"), + ); + expect(order).toEqual([]); + expect(invoked).toEqual([]); + expect(admissions(yield* stream.readAll())).toHaveLength(1); - release.resolve(); - yield* halting; + release.resolve(); + yield* halting; - // Only now is the handle free, and the next call is new work rather than - // the cancelled one resumed. - fresh.answer = yield* open.execution.evaluateGeneratedXmdRoot( - request("\n\n\n", invoked, "turn-3"), - ); - }); + // Only now is the handle free, and the next call is new work rather than + // the cancelled one resumed. + fresh.answer = yield* open.execution.evaluateGeneratedXmdRoot( + request("\n\n\n", invoked, "turn-3"), + ); + }); - expect(overlapping.answer?.ok).toBe(false); - expect(overlapping.answer?.ok === false && overlapping.answer.error).toBeInstanceOf( - HostExecutionError, - ); - expect(overlapping.answer?.ok === false && overlapping.answer.error.message).toContain( - "one at a time", - ); - // The cleanup joined before the halt returned, which is what a caller whose - // halt has come back is entitled to assume. - expect(order).toEqual(["evaluation cleanup", "halt returned"]); - expect(rendered(fresh.answer ?? { ok: false, error: new Error("none") }).output).toContain( - "probed", - ); - expect(invoked).toEqual(["probed"]); + expect(overlapping.answer?.ok).toBe(false); + expect(overlapping.answer?.ok === false && overlapping.answer.error).toBeInstanceOf( + HostExecutionError, + ); + expect(overlapping.answer?.ok === false && overlapping.answer.error.message).toContain( + "one at a time", + ); + // The cleanup joined before the halt returned, which is what a caller whose + // halt has come back is entitled to assume. + expect(order).toEqual(["evaluation cleanup", "halt returned"]); + expect(rendered(fresh.answer ?? { ok: false, error: new Error("none") }).output).toContain( + "probed", + ); + expect(invoked).toEqual(["probed"]); - const events = yield* stream.readAll(); - // The cancelled evaluation left its sequence unfinished, and the fresh call - // took a new address rather than continuing it. - expect(sequences(events)).toContain("generated_root:1"); - expect(sequences(events)).toContain("generated_root:2"); - expect( - events.some((event) => event.type === "close" && event.coroutineId === "generated_root:1"), - ).toBe(false); - }); + const events = yield* stream.readAll(); + // The cancelled evaluation left its sequence unfinished, and the fresh call + // took a new address rather than continuing it. + expect(sequences(events)).toContain("generated_root:1"); + expect(sequences(events)).toContain("generated_root:2"); + expect( + events.some((event) => event.type === "close" && event.coroutineId === "generated_root:1"), + ).toBe(false); + }, + ); heldHostCase( "E5b: closing the execution joins a held evaluation before closure completes", @@ -1642,62 +1648,66 @@ describe("Tier E8 — the captured selection holds canonical Syntax once", () => * than the selection machinery, because the collision was between two things * only a real capture produces. */ - it("E8a: a host that selected Syntax evaluates, and retains one Syntax row", function* () { - const stream = new InMemoryStream(); - const invoked: string[] = []; - const answered: { output?: string } = {}; - const run = yield* withHeldHost( - { stream, installations: [selectingWithSyntax([probe(invoked)])] }, - function* (open) { - answered.output = rendered( - yield* open.execution.evaluateGeneratedXmdRoot( - request("\n\n\n\n", invoked), - ), - ).output; - }, - ); + heldHostCase( + "E8a: a host that selected Syntax evaluates, and retains one Syntax row", + function* (stream) { + const invoked: string[] = []; + const answered: { output?: string } = {}; + const run = yield* withHeldHost( + { stream, installations: [selectingWithSyntax([probe(invoked)])] }, + function* (open) { + answered.output = rendered( + yield* open.execution.evaluateGeneratedXmdRoot( + request("\n\n\n\n", invoked), + ), + ).output; + }, + ); - expect(run.completion.ok).toBe(true); - // Ordinary Syntax evaluation, under the selection that used to collide: the - // vocabulary rendered and the admitted control ran. - expect(invoked).toEqual(["probed"]); - expect(answered.output).toContain("Probe"); - - // Once in the recorded policy, which is the admission's own account of what - // this root may write. - const rows = retainedRows(yield* stream.readAll()); - expect(rows.filter((row) => row.name === "Syntax")).toHaveLength(1); - expect(rows.map((row) => row.name)).toEqual(["Json", "Probe", "Syntax"]); - // And once in the descriptive vocabulary, which is the other reading of the - // same selection: a second entry would render a second section. - expect(occurrences(answered.output ?? "", "### ``")).toBe(1); - }); + expect(run.completion.ok).toBe(true); + // Ordinary Syntax evaluation, under the selection that used to collide: the + // vocabulary rendered and the admitted control ran. + expect(invoked).toEqual(["probed"]); + expect(answered.output).toContain("Probe"); + + // Once in the recorded policy, which is the admission's own account of what + // this root may write. + const rows = retainedRows(yield* stream.readAll()); + expect(rows.filter((row) => row.name === "Syntax")).toHaveLength(1); + expect(rows.map((row) => row.name)).toEqual(["Json", "Probe", "Syntax"]); + // And once in the descriptive vocabulary, which is the other reading of the + // same selection: a second entry would render a second section. + expect(occurrences(answered.output ?? "", "### ``")).toBe(1); + }, + ); - it("E8b: a host that selected none of it reaches core's own, also once", function* () { - const stream = new InMemoryStream(); - const invoked: string[] = []; - const answered: { output?: string } = {}; - const run = yield* withHeldHost( - { stream, installations: [selecting([probe(invoked)])] }, - function* (open) { - answered.output = rendered( - yield* open.execution.evaluateGeneratedXmdRoot( - request("\n\n\n\n", invoked), - ), - ).output; - }, - ); + heldHostCase( + "E8b: a host that selected none of it reaches core's own, also once", + function* (stream) { + const invoked: string[] = []; + const answered: { output?: string } = {}; + const run = yield* withHeldHost( + { stream, installations: [selecting([probe(invoked)])] }, + function* (open) { + answered.output = rendered( + yield* open.execution.evaluateGeneratedXmdRoot( + request("\n\n\n\n", invoked), + ), + ).output; + }, + ); - // The control, and the reason E8a is about *recognizing* a captured row - // rather than about dropping core's: a host that named nothing of it still - // gets the one protected answer a root may write. - expect(run.completion.ok).toBe(true); - expect(invoked).toEqual(["probed"]); - const rows = retainedRows(yield* stream.readAll()); - expect(rows.filter((row) => row.name === "Syntax")).toHaveLength(1); - expect(rows.map((row) => row.name)).toEqual(["Json", "Probe", "Syntax"]); - expect(occurrences(answered.output ?? "", "### ``")).toBe(1); - }); + // The control, and the reason E8a is about *recognizing* a captured row + // rather than about dropping core's: a host that named nothing of it still + // gets the one protected answer a root may write. + expect(run.completion.ok).toBe(true); + expect(invoked).toEqual(["probed"]); + const rows = retainedRows(yield* stream.readAll()); + expect(rows.filter((row) => row.name === "Syntax")).toHaveLength(1); + expect(rows.map((row) => row.name)).toEqual(["Json", "Probe", "Syntax"]); + expect(occurrences(answered.output ?? "", "### ``")).toBe(1); + }, + ); }); describe("Tier E9 — an availability refusal is the call's answer", () => { @@ -1713,72 +1723,78 @@ describe("Tier E9 — an availability refusal is the call's answer", () => { * failed canonical run for a question somebody asked it. The run's own * failures (E7) keep their authority; these two are not among them. */ - it("E9a: a host that selected no generated components refuses, and its document completes", function* () { - const stream = new InMemoryStream(); - const answer: { value?: Result } = {}; - const run = yield* withHeldHost({ stream }, function* (open) { - answer.value = yield* open.execution.evaluateGeneratedXmdRoot( - request("\nReady.\n\n"), - ); - }); + heldHostCase( + "E9a: a host that selected no generated components refuses, and its document completes", + function* (stream) { + const answer: { value?: Result } = {}; + const run = yield* withHeldHost({ stream }, function* (open) { + answer.value = yield* open.execution.evaluateGeneratedXmdRoot( + request("\nReady.\n\n"), + ); + }); - expect(answer.value?.ok).toBe(false); - expect(answer.value?.ok === false && answer.value.error).toBeInstanceOf(HostExecutionError); - expect(answer.value?.ok === false && answer.value.error.message).toContain( - "selected no generated components", - ); - // The document is the host's, and it finished on its own terms. - expect(run.completion.ok).toBe(true); - // Nothing was admitted, so nothing performed. - expect(admissions(yield* stream.readAll())).toHaveLength(0); - }); + expect(answer.value?.ok).toBe(false); + expect(answer.value?.ok === false && answer.value.error).toBeInstanceOf(HostExecutionError); + expect(answer.value?.ok === false && answer.value.error.message).toContain( + "selected no generated components", + ); + // The document is the host's, and it finished on its own terms. + expect(run.completion.ok).toBe(true); + // Nothing was admitted, so nothing performed. + expect(admissions(yield* stream.readAll())).toHaveLength(0); + }, + ); - it("E9b: a class this host installed nothing for refuses, and its document completes", function* () { - const stream = new InMemoryStream(); - const invoked: string[] = []; - const answer: { value?: Result } = {}; - const run = yield* withHeldHost( - { stream, installations: [selecting([probe(invoked)])] }, - function* (open) { - answer.value = yield* open.execution.evaluateGeneratedXmdRoot({ - id: "turn-1", - source: "\nReady.\n\n", - allow: ["write"], - }); - }, - ); + heldHostCase( + "E9b: a class this host installed nothing for refuses, and its document completes", + function* (stream) { + const invoked: string[] = []; + const answer: { value?: Result } = {}; + const run = yield* withHeldHost( + { stream, installations: [selecting([probe(invoked)])] }, + function* (open) { + answer.value = yield* open.execution.evaluateGeneratedXmdRoot({ + id: "turn-1", + source: "\nReady.\n\n", + allow: ["write"], + }); + }, + ); - expect(answer.value?.ok).toBe(false); - expect(answer.value?.ok === false && answer.value.error.message).toContain( - "installed no write table", - ); - expect(run.completion.ok).toBe(true); - expect(invoked).toEqual([]); - expect(admissions(yield* stream.readAll())).toHaveLength(0); - }); + expect(answer.value?.ok).toBe(false); + expect(answer.value?.ok === false && answer.value.error.message).toContain( + "installed no write table", + ); + expect(run.completion.ok).toBe(true); + expect(invoked).toEqual([]); + expect(admissions(yield* stream.readAll())).toHaveLength(0); + }, + ); - it("E9c: a class this host did install answers, and its document completes", function* () { - const stream = new InMemoryStream(); - const invoked: string[] = []; - const answer: { value?: Result } = {}; - const run = yield* withHeldHost( - { stream, installations: [selecting([probe(invoked)])] }, - function* (open) { - answer.value = yield* open.execution.evaluateGeneratedXmdRoot({ - id: "turn-1", - source: "\n\n\n", - allow: ["read"], - }); - }, - ); + heldHostCase( + "E9c: a class this host did install answers, and its document completes", + function* (stream) { + const invoked: string[] = []; + const answer: { value?: Result } = {}; + const run = yield* withHeldHost( + { stream, installations: [selecting([probe(invoked)])] }, + function* (open) { + answer.value = yield* open.execution.evaluateGeneratedXmdRoot({ + id: "turn-1", + source: "\n\n\n", + allow: ["read"], + }); + }, + ); - // The control for both arms above: the same method, the same document, and - // an available class reaches the work and records it. - expect(answer.value?.ok).toBe(true); - expect(run.completion.ok).toBe(true); - expect(invoked).toEqual(["probed"]); - expect(admissions(yield* stream.readAll())).toHaveLength(1); - }); + // The control for both arms above: the same method, the same document, and + // an available class reaches the work and records it. + expect(answer.value?.ok).toBe(true); + expect(run.completion.ok).toBe(true); + expect(invoked).toEqual(["probed"]); + expect(admissions(yield* stream.readAll())).toHaveLength(1); + }, + ); /** * The accepted public request, written the way a trusted host writes it. From 4e77e932cb0355602aea938c9568ce0131a48047 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:01:16 -0500 Subject: [PATCH 28/78] test: capture guarded root comparisons and eval lifetimes --- packages/core/tests/eval-persist.test.ts | 300 ++++++++++++----------- packages/core/tests/root-props.test.ts | 70 ++++-- 2 files changed, 201 insertions(+), 169 deletions(-) diff --git a/packages/core/tests/eval-persist.test.ts b/packages/core/tests/eval-persist.test.ts index da61060e0..82261e266 100644 --- a/packages/core/tests/eval-persist.test.ts +++ b/packages/core/tests/eval-persist.test.ts @@ -15,14 +15,16 @@ import { useStubFs, useEchoExec } from "@executablemd/runtime/test"; import { execute } from "../src/execute.ts"; import { collect } from "../src/collect.ts"; import { asText } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; import { unbox } from "effection"; import type { Result } from "effection"; +const journalCase = journalCases("packages/core/tests/eval-persist.test.ts"); + describe("Tier T6 — persist modifier", () => { beforeAll(() => useTempFileCompiler()); // T43: eval without persist → block completes normally - it("T43: eval without persist → block completes", function* () { - const stream = new InMemoryStream(); + journalCase("T43: eval without persist → block completes", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js eval\nconst x = 42;\n```\n", }); @@ -42,8 +44,7 @@ describe("Tier T6 — persist modifier", () => { }); // T44: persist eval → block completes normally - it("T44: persist eval → block completes normally", function* () { - const stream = new InMemoryStream(); + journalCase("T44: persist eval → block completes normally", "test.md", function* (stream) { yield* useStubFs({ "test.md": "```js persist eval\nconst server = 'running';\n```\n", }); @@ -63,26 +64,29 @@ describe("Tier T6 — persist modifier", () => { }); // T45: persist eval followed by eval → bindings available - it("T45: persist eval followed by eval → bindings available", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "test.md": - "```js persist eval\nconst server = 'started';\n```\n\n```js eval\nconst status = server;\n```\n", - }); - yield* useEchoExec(); + journalCase( + "T45: persist eval followed by eval → bindings available", + "test.md", + function* (stream) { + yield* useStubFs({ + "test.md": + "```js persist eval\nconst server = 'started';\n```\n\n```js eval\nconst status = server;\n```\n", + }); + yield* useEchoExec(); - const output = asText( - yield* collect( - yield* execute({ - path: "test.md", - stream, - }), - ), - ); + const output = asText( + yield* collect( + yield* execute({ + path: "test.md", + stream, + }), + ), + ); - expect(output.trim()).toBe(""); - expect(output).not.toContain("ERROR"); - }); + expect(output.trim()).toBe(""); + expect(output).not.toContain("ERROR"); + }, + ); // T46: persist on replay → no-op it("T46: persist on replay → normal replay", function* () { @@ -134,144 +138,156 @@ describe("Tier T6 — persist modifier", () => { // L2: without persist, a resource a block spawns is torn down when the block // completes — the negative that gives L3 its meaning. - it("L2: a non-persist eval block's resource is gone by the next block", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "test.md": [ - "```js eval", - "const status = { alive: false };", - "yield* spawn(function*() {", - " status.alive = true;", - " try { yield* suspend(); } finally { status.alive = false; }", - "});", - "yield* sleep(1);", - "```", - "", - "```js eval", - "const observed = status.alive;", - "output(`alive=${observed}`);", - "```", - ].join("\n"), - }); - yield* useEchoExec(); + journalCase( + "L2: a non-persist eval block's resource is gone by the next block", + "test.md", + function* (stream) { + yield* useStubFs({ + "test.md": [ + "```js eval", + "const status = { alive: false };", + "yield* spawn(function*() {", + " status.alive = true;", + " try { yield* suspend(); } finally { status.alive = false; }", + "});", + "yield* sleep(1);", + "```", + "", + "```js eval", + "const observed = status.alive;", + "output(`alive=${observed}`);", + "```", + ].join("\n"), + }); + yield* useEchoExec(); - const output = yield* collect(yield* execute({ path: "test.md", stream })); + const output = yield* collect(yield* execute({ path: "test.md", stream })); - expect(output).toContain("alive=false"); - }); + expect(output).toContain("alive=false"); + }, + ); // L3: a persist resource belongs to the invocation, so a block after the // component sees it gone while the document is still running. - it("L3: a persist resource stops when the invocation completes", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Holder.md": [ - "```js persist eval", - "globalThis.__l3 = { alive: false };", - "yield* spawn(function*() {", - " globalThis.__l3.alive = true;", - " try { yield* suspend(); } finally { globalThis.__l3.alive = false; }", - "});", - "yield* sleep(1);", - "```", - ].join("\n"), - "doc.md": [ - "", - "", - "```js eval", - "output(`alive=${globalThis.__l3.alive}`);", - "```", - ].join("\n"), - }); - yield* useEchoExec(); + journalCase( + "L3: a persist resource stops when the invocation completes", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Holder.md": [ + "```js persist eval", + "globalThis.__l3 = { alive: false };", + "yield* spawn(function*() {", + " globalThis.__l3.alive = true;", + " try { yield* suspend(); } finally { globalThis.__l3.alive = false; }", + "});", + "yield* sleep(1);", + "```", + ].join("\n"), + "doc.md": [ + "", + "", + "```js eval", + "output(`alive=${globalThis.__l3.alive}`);", + "```", + ].join("\n"), + }); + yield* useEchoExec(); - const output = yield* collect(yield* execute({ path: "doc.md", stream })); + const output = yield* collect(yield* execute({ path: "doc.md", stream })); - expect(output).toContain("alive=false"); - }); + expect(output).toContain("alive=false"); + }, + ); // L8: a persist block the caller projected into a component anchors in the // content scope, so it stops ahead of a persist resource the component // retained for itself — even though the component retained that one after // projecting, which is the order a single scope would release in reverse. - it("L8: a projected persist resource stops before the component's own", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "components/Holder.md": [ - "", - "", - "```js persist eval", - "globalThis.__l8.push('start:own');", - "yield* spawn(function*() {", - " try { yield* suspend(); } finally { globalThis.__l8.push('stop:own'); }", - "});", - "yield* sleep(1);", - "```", - ].join("\n"), - "doc.md": [ - "```js eval", - "globalThis.__l8 = [];", - "```", - "", - "", - "", - "```js persist eval", - "globalThis.__l8.push('start:projected');", - "yield* spawn(function*() {", - " try { yield* suspend(); } finally { globalThis.__l8.push('stop:projected'); }", - "});", - "yield* sleep(1);", - "```", - "", - "", - "", - "```js eval", - "output(globalThis.__l8.join(','));", - "```", - ].join("\n"), - }); - yield* useEchoExec(); + journalCase( + "L8: a projected persist resource stops before the component's own", + "doc.md", + function* (stream) { + yield* useStubFs({ + "components/Holder.md": [ + "", + "", + "```js persist eval", + "globalThis.__l8.push('start:own');", + "yield* spawn(function*() {", + " try { yield* suspend(); } finally { globalThis.__l8.push('stop:own'); }", + "});", + "yield* sleep(1);", + "```", + ].join("\n"), + "doc.md": [ + "```js eval", + "globalThis.__l8 = [];", + "```", + "", + "", + "", + "```js persist eval", + "globalThis.__l8.push('start:projected');", + "yield* spawn(function*() {", + " try { yield* suspend(); } finally { globalThis.__l8.push('stop:projected'); }", + "});", + "yield* sleep(1);", + "```", + "", + "", + "", + "```js eval", + "output(globalThis.__l8.join(','));", + "```", + ].join("\n"), + }); + yield* useEchoExec(); - const output = yield* collect(yield* execute({ path: "doc.md", stream })); + const output = yield* collect(yield* execute({ path: "doc.md", stream })); - expect(output).toContain("start:projected,start:own,stop:projected,stop:own"); - }); + expect(output).toContain("start:projected,start:own,stop:projected,stop:own"); + }, + ); // T49b: persist eval retains spawned resource across blocks // A background task spawned in a persist eval block sets status.ready // after 10ms. The next eval block uses when() to converge on it. - it("T49b: persist eval retains spawned resource across blocks", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "test.md": [ - "```js persist eval", - "const status = { ready: false };", - "yield* spawn(function*() {", - " yield* sleep(10);", - " status.ready = true;", - "});", - "```", - "", - "```js eval", - "yield* when(function*() {", - ' if (!status.ready) throw new Error("not ready");', - "});", - "const serverReady = status.ready;", - "```", - ].join("\n"), - }); - yield* useEchoExec(); + journalCase( + "T49b: persist eval retains spawned resource across blocks", + "test.md", + function* (stream) { + yield* useStubFs({ + "test.md": [ + "```js persist eval", + "const status = { ready: false };", + "yield* spawn(function*() {", + " yield* sleep(10);", + " status.ready = true;", + "});", + "```", + "", + "```js eval", + "yield* when(function*() {", + ' if (!status.ready) throw new Error("not ready");', + "});", + "const serverReady = status.ready;", + "```", + ].join("\n"), + }); + yield* useEchoExec(); - const output = asText( - yield* collect( - yield* execute({ - path: "test.md", - stream, - }), - ), - ); + const output = asText( + yield* collect( + yield* execute({ + path: "test.md", + stream, + }), + ), + ); - expect(output.trim()).toBe(""); - expect(output).not.toContain("ERROR"); - }); + expect(output.trim()).toBe(""); + expect(output).not.toContain("ERROR"); + }, + ); }); diff --git a/packages/core/tests/root-props.test.ts b/packages/core/tests/root-props.test.ts index 9f0cf5023..b1a7382b8 100644 --- a/packages/core/tests/root-props.test.ts +++ b/packages/core/tests/root-props.test.ts @@ -5,6 +5,7 @@ * validated and defaulted before any body effect, then available through * `{props.name}`, bare binding interpolation, and eval blocks. */ +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { journalCases } from "../../test-support/journal-cases.ts"; import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; @@ -98,7 +99,8 @@ function* runDoc( return yield* runPath(path, props, stream); } -const rootCase = journalCases("packages/core/tests/root-props.test.ts"); +const OWNER = "packages/core/tests/root-props.test.ts"; +const rootCase = journalCases(OWNER); describe("Tier RP — root document properties", () => { rootCase( @@ -245,7 +247,8 @@ describe("Tier RI — document inspection", () => { expect(failed).toBe(true); }); - it("RI6: inspection and execution agree on which roots are markdown", function* () { + const extensions = "RI6: inspection and execution agree on which roots are markdown"; + it(extensions, function* () { // Execution parses any non-TypeScript root as markdown, so inspection // must not require a `.md` suffix. const names = ["README", "notes.markdown", "doc.md"]; @@ -255,15 +258,17 @@ describe("Tier RI — document inspection", () => { const info = yield* inspectDocument({ path: name }); expect(info.props).toMatchObject({ required: ["name"] }); - const execution = yield* execute({ - path: name, - stream: new InMemoryStream(), - props: { name: "Ada" }, + yield* captureTestJournal({ owner: OWNER, name: extensions }, name, function* (stream) { + const execution = yield* execute({ + path: name, + stream, + props: { name: "Ada" }, + }); + const output = yield* forEach(function* () {}, execution.output); + const result = yield* execution; + expect(result.ok).toBe(true); + expect(output).toContain("Hello, Ada!"); }); - const output = yield* forEach(function* () {}, execution.output); - const result = yield* execution; - expect(result.ok).toBe(true); - expect(output).toContain("Hello, Ada!"); } }); }); @@ -288,11 +293,17 @@ describe("Tier RS — concise props declarations", () => { }, ); - it("RS2: the concise and full spellings behave identically", function* () { + const comparison = "RS2: the concise and full spellings behave identically"; + it(comparison, function* () { yield* useStubFs({ "concise.md": GREETING_CONCISE, "full.md": GREETING }); - const concise = yield* runPath("concise.md", { name: "Ada", loud: true }); - const full = yield* runPath("full.md", { name: "Ada", loud: true }); - expect(concise.output).toBe(full.output); + const label = { owner: OWNER, name: comparison }; + yield* captureTestJournal(label, "concise.md", function* (conciseStream) { + const concise = yield* runPath("concise.md", { name: "Ada", loud: true }, conciseStream); + yield* captureTestJournal(label, "full.md", function* (fullStream) { + const full = yield* runPath("full.md", { name: "Ada", loud: true }, fullStream); + expect(concise.output).toBe(full.output); + }); + }); }); rootCase( @@ -338,24 +349,29 @@ describe("Tier RS — concise props declarations", () => { expect(output).toContain("port=8080"); }); - it("RS6: an imported concise component validates props like the root", function* () { + const imported = "RS6: an imported concise component validates props like the root"; + it(imported, function* () { yield* useStubFs({ "supplied.md": '\n', "omitted.md": "\n", "Greeting.md": GREETING_CONCISE, }); - const supplied = yield* runPath("supplied.md"); - expect(supplied.result.ok).toBe(true); - expect(supplied.output).toContain("Hello, Ada!"); - - // Nothing recovers the component's prop failure, so it is the run's own - // outcome and the component renders nothing. - const omitted = yield* runPath("omitted.md"); - expect(omitted.result.ok).toBe(false); - const reported = omitted.result.ok ? "" : omitted.result.error.message; - expect(reported).toContain("Prop validation failed for "); - expect(reported).toContain("must have required property 'name'"); - expect(omitted.output).not.toContain("Hello, "); + const label = { owner: OWNER, name: imported }; + yield* captureTestJournal(label, "supplied.md", function* (stream) { + const supplied = yield* runPath("supplied.md", undefined, stream); + expect(supplied.result.ok).toBe(true); + expect(supplied.output).toContain("Hello, Ada!"); + }); + yield* captureTestJournal(label, "omitted.md", function* (stream) { + // Nothing recovers the component's prop failure, so it is the run's own + // outcome and the component renders nothing. + const omitted = yield* runPath("omitted.md", undefined, stream); + expect(omitted.result.ok).toBe(false); + const reported = omitted.result.ok ? "" : omitted.result.error.message; + expect(reported).toContain("Prop validation failed for "); + expect(reported).toContain("must have required property 'name'"); + expect(omitted.output).not.toContain("Hello, "); + }); }); it("RS7: inspection returns the normalized schema", function* () { From d0ed3041a94d284d805a0d7603b66fb361489426 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:02:32 -0500 Subject: [PATCH 29/78] test: capture complete Testing activation sessions --- .../testing/tests/testing-activation.test.ts | 126 ++++++++++-------- 1 file changed, 73 insertions(+), 53 deletions(-) diff --git a/packages/testing/tests/testing-activation.test.ts b/packages/testing/tests/testing-activation.test.ts index 190725bb6..86e48d7d5 100644 --- a/packages/testing/tests/testing-activation.test.ts +++ b/packages/testing/tests/testing-activation.test.ts @@ -9,6 +9,7 @@ * and "no results" is the vacuous failure mode rather than the evidence. */ +import { journalCases } from "../../test-support/journal-cases.ts"; import { describe, it, beforeAll } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { scoped } from "effection"; @@ -119,6 +120,8 @@ function useSentinel(sentinels: string[]): Operation { * this harness needs are already in place — the position from which a handler * would see everything a real one does. */ +const activationCase = journalCases("packages/testing/tests/testing-activation.test.ts"); + function runComposed( document: string, compose: Operation, @@ -419,65 +422,82 @@ describe("complete testing activation", () => { // The control, in the identical middleware order: a handler that delegates // observes the behavior and changes nothing about it. - it("leaves an ordinary TestBehavior handler composing under a complete session", function* () { - const behavior = loadedCopyBehaviorApi(); - const observed: string[] = []; - const attempt = yield* runComposed( - '\n', - (function* () { - yield* behavior.around({ - *test([props], next) { - observed.push(String(props.name)); - return yield* next(props); - }, - }); - yield* useTesting(); - })(), - ); - expect(observed).toEqual(["t"]); - expect(attempt.sentinels).toEqual(["body"]); - expect(attempt.completion.ok).toBe(true); - expect(attempt.results.map((result) => [result.name, result.status])).toEqual([["t", "pass"]]); - expect(testResultEvents(attempt.events)).toHaveLength(1); - }); + activationCase( + "leaves an ordinary TestBehavior handler composing under a complete session", + "README.md", + function* (stream) { + const behavior = loadedCopyBehaviorApi(); + const observed: string[] = []; + const attempt = yield* runComposed( + '\n', + (function* () { + yield* behavior.around({ + *test([props], next) { + observed.push(String(props.name)); + return yield* next(props); + }, + }); + yield* useTesting(); + })(), + stream, + ); + expect(observed).toEqual(["t"]); + expect(attempt.sentinels).toEqual(["body"]); + expect(attempt.completion.ok).toBe(true); + expect(attempt.results.map((result) => [result.name, result.status])).toEqual([ + ["t", "pass"], + ]); + expect(testResultEvents(attempt.events)).toHaveLength(1); + }, + ); // The other direction: under a real session the same public surface keeps // working, and observes results in discovery order. - it("leaves loaded-copy policy and recording composition working", function* () { - const attempt = yield* runComposed( - [ - '', - '', - "", - ].join("\n"), - useTesting(), - ); - expect(attempt.completion.ok).toBe(true); - expect(attempt.sentinels).toEqual(["first", "second"]); - expect(attempt.results.map((result) => [result.name, result.status])).toEqual([ - ["first", "pass"], - ["second", "pass"], - ]); - expect(testResultEvents(attempt.events)).toHaveLength(2); - }); + activationCase( + "leaves loaded-copy policy and recording composition working", + "README.md", + function* (stream) { + const attempt = yield* runComposed( + [ + '', + '', + "", + ].join("\n"), + useTesting(), + stream, + ); + expect(attempt.completion.ok).toBe(true); + expect(attempt.sentinels).toEqual(["first", "second"]); + expect(attempt.results.map((result) => [result.name, result.status])).toEqual([ + ["first", "pass"], + ["second", "pass"], + ]); + expect(testResultEvents(attempt.events)).toHaveLength(2); + }, + ); // Narrowing is what the public boolean is for, and it still works: a policy // that answers `false` leaves the test inactive rather than refused. - it("lets public policy narrow testing to false under a complete session", function* () { - const attempt = yield* runComposed( - '\n', - (function* () { - yield* useTesting(); - const policy = loadedCopyTestApi(); - yield* policy.around({ testing: () => false }); - })(), - ); - expect(attempt.sentinels).toEqual([]); - expect(attempt.results).toEqual([]); - // No tests were discovered, which is the session's own outcome — not the - // activation refusal. - expect(errorOf(attempt)?.message).toContain("no tests were discovered"); - }); + activationCase( + "lets public policy narrow testing to false under a complete session", + "README.md", + function* (stream) { + const attempt = yield* runComposed( + '\n', + (function* () { + yield* useTesting(); + const policy = loadedCopyTestApi(); + yield* policy.around({ testing: () => false }); + })(), + stream, + ); + expect(attempt.sentinels).toEqual([]); + expect(attempt.results).toEqual([]); + // No tests were discovered, which is the session's own outcome — not the + // activation refusal. + expect(errorOf(attempt)?.message).toContain("no tests were discovered"); + }, + ); // An ended boundary's credential is retired, so a `` written after it // is refused exactly as one written before it. From 389ab30a1f1298a5d883b30df9f6bfc53ceb9479 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:03:36 -0500 Subject: [PATCH 30/78] test: attribute guarded exec timeout fixture journals --- packages/core/tests/exec-timeout.test.ts | 227 ++++++++++++++--------- 1 file changed, 140 insertions(+), 87 deletions(-) diff --git a/packages/core/tests/exec-timeout.test.ts b/packages/core/tests/exec-timeout.test.ts index 8584b868b..66e69585f 100644 --- a/packages/core/tests/exec-timeout.test.ts +++ b/packages/core/tests/exec-timeout.test.ts @@ -13,12 +13,14 @@ import { describe, it, beforeAll } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { scoped } from "effection"; import type { Operation } from "effection"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import type { InMemoryStream } from "@executablemd/durable-streams"; import { ephemeral } from "@executablemd/durable-streams"; import { API, Config, timeoutExec } from "@executablemd/runtime"; import type { ConfigApi } from "@executablemd/runtime"; import { useStubFs } from "@executablemd/runtime/test"; import { execute } from "../src/execute.ts"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; import { collect } from "../src/collect.ts"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import type { ModifierFactory } from "../src/modifiers.ts"; @@ -35,6 +37,7 @@ interface Run { } function* run( + stream: InMemoryStream, body: string, options: { config?: Partial; modifiers?: Record } = {}, ): Operation { @@ -61,7 +64,7 @@ function* run( }); const execution = yield* execute({ path: "test.md", - stream: new InMemoryStream(), + stream, ...(options.modifiers ? { modifiers: options.modifiers } : {}), }); const result = yield* execution; @@ -80,107 +83,157 @@ function observer(seen: Record, key: string): Modifi const block = (info: string, command = "work") => `\`\`\`${info}\n${command}\n\`\`\`\n`; +const OWNER = "packages/core/tests/exec-timeout.test.ts"; +const timeoutCase = journalCases(OWNER); + describe("Tier XE — exec block timeouts", () => { beforeAll(() => useTempFileCompiler()); - it("XE1: a block nobody bounded runs with no timeout at all", function* () { - const { timeouts } = yield* run(block("bash exec")); - expect(timeouts).toEqual([undefined]); - }); - - it("XE2: the run's exec default bounds every block", function* () { - const { timeouts } = yield* run(`${block("bash exec")}\n${block("bash exec", "again")}`, { - config: { timeoutExec: 5_000 }, - }); - expect(timeouts).toEqual([5_000, 5_000]); - }); + timeoutCase( + "XE1: a block nobody bounded runs with no timeout at all", + "test.md", + function* (stream) { + const { timeouts } = yield* run(stream, block("bash exec")); + expect(timeouts).toEqual([undefined]); + }, + ); - it("XE3: a declared duration overrides the default for that block alone", function* () { + timeoutCase("XE2: the run's exec default bounds every block", "test.md", function* (stream) { const { timeouts } = yield* run( - `${block("bash timeout=250ms exec")}\n${block("bash exec", "again")}`, - { config: { timeoutExec: 5_000 } }, + stream, + `${block("bash exec")}\n${block("bash exec", "again")}`, + { + config: { timeoutExec: 5_000 }, + }, ); - expect(timeouts).toEqual([250, 5_000]); + expect(timeouts).toEqual([5_000, 5_000]); }); - it("XE4: a bare timeout takes the run's exec default", function* () { - const { timeouts } = yield* run(block("bash timeout exec"), { + timeoutCase( + "XE3: a declared duration overrides the default for that block alone", + "test.md", + function* (stream) { + const { timeouts } = yield* run( + stream, + `${block("bash timeout=250ms exec")}\n${block("bash exec", "again")}`, + { config: { timeoutExec: 5_000 } }, + ); + expect(timeouts).toEqual([250, 5_000]); + }, + ); + + timeoutCase("XE4: a bare timeout takes the run's exec default", "test.md", function* (stream) { + const { timeouts } = yield* run(stream, block("bash timeout exec"), { config: { timeoutExec: 5_000 }, }); expect(timeouts).toEqual([5_000]); }); - it("XE5: a bare timeout with no configured default refuses before the process starts", function* () { - const { output, timeouts } = yield* run(block("bash timeout exec")); - expect(timeouts).toEqual([]); - expect(output).toContain("names no duration"); - expect(output).toContain("--timeout-exec"); - }); - - it("XE6: `timeout=` is an empty duration, not a bare timeout", function* () { - const { output, timeouts } = yield* run(block("bash timeout= exec"), { - config: { timeoutExec: 5_000 }, - }); - expect(timeouts).toEqual([]); - expect(output).toContain("must be a duration"); - }); + timeoutCase( + "XE5: a bare timeout with no configured default refuses before the process starts", + "test.md", + function* (stream) { + const { output, timeouts } = yield* run(stream, block("bash timeout exec")); + expect(timeouts).toEqual([]); + expect(output).toContain("names no duration"); + expect(output).toContain("--timeout-exec"); + }, + ); + + timeoutCase( + "XE6: `timeout=` is an empty duration, not a bare timeout", + "test.md", + function* (stream) { + const { output, timeouts } = yield* run(stream, block("bash timeout= exec"), { + config: { timeoutExec: 5_000 }, + }); + expect(timeouts).toEqual([]); + expect(output).toContain("must be a duration"); + }, + ); - it("XE7: a malformed duration refuses before the process starts", function* () { + const malformed = "XE7: a malformed duration refuses before the process starts"; + it(malformed, function* () { for (const info of ["bash timeout=abc exec", "bash timeout=0s exec", "bash timeout=-5s exec"]) { - const { output, timeouts } = yield* run(block(info), { config: { timeoutExec: 5_000 } }); - expect({ info, timeouts }).toEqual({ info, timeouts: [] }); - expect(output).toContain("must be a duration"); + yield* captureTestJournal({ owner: OWNER, name: malformed }, "test.md", function* (stream) { + const { output, timeouts } = yield* run(stream, block(info), { + config: { timeoutExec: 5_000 }, + }); + expect({ info, timeouts }).toEqual({ info, timeouts: [] }); + expect(output).toContain("must be a duration"); + }); } }); - it("XE8: a timeout after the terminal is unreachable, so it is never applied", function* () { - // `exec` is terminal and never calls next(), so this modifier's factory is - // built but its middleware never runs — a malformed duration behind it - // cannot fail a run it was never part of. - const { output, timeouts } = yield* run(block("bash exec timeout=nonsense"), { - config: { timeoutExec: 5_000 }, - }); - expect(timeouts).toEqual([5_000]); - expect(output).not.toContain("must be a duration"); - }); - - it("XE9: nested timeouts follow wrapper order — the innermost reaches the terminal", function* () { - const { timeouts } = yield* run(block("bash timeout=5s timeout=250ms exec"), { - config: { timeoutExec: 9_000 }, - }); - expect(timeouts).toEqual([250]); - }); - - it("XE10: middleware outside the timeout sees the run's default, inside sees the block's", function* () { - const seen: Record = {}; - const { timeouts } = yield* run(block("bash outer timeout=250ms inner exec"), { - config: { timeoutExec: 5_000 }, - modifiers: { outer: observer(seen, "outer"), inner: observer(seen, "inner") }, - }); - expect(seen).toEqual({ outer: 5_000, inner: 250 }); - expect(timeouts).toEqual([250]); - }); - - it("XE11: replacing the timeout factory leaves no built-in behavior behind", function* () { - const seen: Record = {}; - const { timeouts } = yield* run(block("bash timeout=250ms exec"), { - config: { timeoutExec: 5_000 }, - modifiers: { timeout: observer(seen, "replacement") }, - }); - // The replacement delegates and declares nothing, so the block is bounded - // by the run's default. A hidden override elsewhere would show up as 250. - expect(seen).toEqual({ replacement: 5_000 }); - expect(timeouts).toEqual([5_000]); - }); - - it("XE12: a block's declaration does not leak to the block after it", function* () { - const { timeouts } = yield* run( - `${block("bash timeout=250ms exec")}\n${block("bash timeout=1s exec", "again")}\n${block( - "bash exec", - "third", - )}`, - { config: { timeoutExec: 5_000 } }, - ); - expect(timeouts).toEqual([250, 1_000, 5_000]); - }); + timeoutCase( + "XE8: a timeout after the terminal is unreachable, so it is never applied", + "test.md", + function* (stream) { + // `exec` is terminal and never calls next(), so this modifier's factory is + // built but its middleware never runs — a malformed duration behind it + // cannot fail a run it was never part of. + const { output, timeouts } = yield* run(stream, block("bash exec timeout=nonsense"), { + config: { timeoutExec: 5_000 }, + }); + expect(timeouts).toEqual([5_000]); + expect(output).not.toContain("must be a duration"); + }, + ); + + timeoutCase( + "XE9: nested timeouts follow wrapper order — the innermost reaches the terminal", + "test.md", + function* (stream) { + const { timeouts } = yield* run(stream, block("bash timeout=5s timeout=250ms exec"), { + config: { timeoutExec: 9_000 }, + }); + expect(timeouts).toEqual([250]); + }, + ); + + timeoutCase( + "XE10: middleware outside the timeout sees the run's default, inside sees the block's", + "test.md", + function* (stream) { + const seen: Record = {}; + const { timeouts } = yield* run(stream, block("bash outer timeout=250ms inner exec"), { + config: { timeoutExec: 5_000 }, + modifiers: { outer: observer(seen, "outer"), inner: observer(seen, "inner") }, + }); + expect(seen).toEqual({ outer: 5_000, inner: 250 }); + expect(timeouts).toEqual([250]); + }, + ); + + timeoutCase( + "XE11: replacing the timeout factory leaves no built-in behavior behind", + "test.md", + function* (stream) { + const seen: Record = {}; + const { timeouts } = yield* run(stream, block("bash timeout=250ms exec"), { + config: { timeoutExec: 5_000 }, + modifiers: { timeout: observer(seen, "replacement") }, + }); + // The replacement delegates and declares nothing, so the block is bounded + // by the run's default. A hidden override elsewhere would show up as 250. + expect(seen).toEqual({ replacement: 5_000 }); + expect(timeouts).toEqual([5_000]); + }, + ); + + timeoutCase( + "XE12: a block's declaration does not leak to the block after it", + "test.md", + function* (stream) { + const { timeouts } = yield* run( + stream, + `${block("bash timeout=250ms exec")}\n${block("bash timeout=1s exec", "again")}\n${block( + "bash exec", + "third", + )}`, + { config: { timeoutExec: 5_000 } }, + ); + expect(timeouts).toEqual([250, 1_000, 5_000]); + }, + ); }); From 3391a0f7bc0e5d1f0da9f1be42344cd0517a56fc Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:04:23 -0500 Subject: [PATCH 31/78] test: retain the activation expiry fixture journal --- packages/testing/tests/testing-activation.test.ts | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/testing/tests/testing-activation.test.ts b/packages/testing/tests/testing-activation.test.ts index 86e48d7d5..1dbee624d 100644 --- a/packages/testing/tests/testing-activation.test.ts +++ b/packages/testing/tests/testing-activation.test.ts @@ -113,6 +113,8 @@ function useSentinel(sentinels: string[]): Operation { ]); } +const activationCase = journalCases("packages/testing/tests/testing-activation.test.ts"); + /** * Run `document` under a composition of the caller's choosing. * @@ -120,8 +122,6 @@ function useSentinel(sentinels: string[]): Operation { * this harness needs are already in place — the position from which a handler * would see everything a real one does. */ -const activationCase = journalCases("packages/testing/tests/testing-activation.test.ts"); - function runComposed( document: string, compose: Operation, @@ -501,7 +501,7 @@ describe("complete testing activation", () => { // An ended boundary's credential is retired, so a `` written after it // is refused exactly as one written before it. - it("expires with the boundary that established it", function* () { + activationCase("expires with the boundary that established it", "README.md", function* (stream) { const attempt = yield* runComposed( [ "", @@ -511,6 +511,7 @@ describe("complete testing activation", () => { "", ].join("\n"), incompleteActivation(), + stream, ); expect(attempt.sentinels).toEqual(["inside"]); expect(errorOf(attempt)?.message).toContain(REFUSAL); From 90828d10eafe5e6337a7c8cfcb53d79657c1b1a3 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:11:42 -0500 Subject: [PATCH 32/78] test: attribute guarded Core document helpers --- .../core/tests/code-block-component.test.ts | 116 ++-- packages/core/tests/compiler-boundary.test.ts | 83 ++- packages/core/tests/eval-durable.test.ts | 69 ++- packages/core/tests/parse-components.test.ts | 264 ++++---- packages/core/tests/props-binding.test.ts | 578 ++++++++++-------- packages/core/tests/root-composition.test.ts | 185 +++--- 6 files changed, 737 insertions(+), 558 deletions(-) diff --git a/packages/core/tests/code-block-component.test.ts b/packages/core/tests/code-block-component.test.ts index fac4774ac..a9003c0a5 100644 --- a/packages/core/tests/code-block-component.test.ts +++ b/packages/core/tests/code-block-component.test.ts @@ -34,6 +34,9 @@ import { collect } from "../src/collect.ts"; import { execute } from "../src/execute.ts"; import { registerComponents } from "../src/components/registration.ts"; import type { Json } from "../src/types.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/code-block-component.test.ts"); interface Run { /** Everything the document emitted, before any output middleware. */ @@ -52,7 +55,11 @@ function reported(result: Run): string { } /** Run `source` as the document, with `values` reachable through ``. */ -function run(source: string, values: Record = {}): Operation { +function run( + stream: InMemoryStream | undefined, + source: string, + values: Record = {}, +): Operation { return scoped(function* () { const probed: string[] = []; let tripped = 0; @@ -100,7 +107,7 @@ function run(source: string, values: Record = {}): Operation = {}): Operation` invocation renders, with nothing around it. */ -function* directly(value: string, attributes = ""): Operation { - return yield* run(``, { v: value }); +function* directly( + stream: InMemoryStream | undefined, + value: string, + attributes = "", +): Operation { + return yield* run(stream, ``, { + v: value, + }); } /** The exact string `as` bound, at the capture boundary. */ -function* captured(value: string, attributes = ""): Operation { +function* captured( + stream: InMemoryStream | undefined, + value: string, + attributes = "", +): Operation { const result = yield* run( + stream, ``, { v: value }, ); @@ -130,23 +148,24 @@ function* captured(value: string, attributes = ""): Operation { describe("Tier CB — the envelope", () => { it("CB1: an empty value is three backticks, two line feeds and nothing else", function* () { - const result = yield* directly(""); + const result = yield* directly(undefined, ""); expect(result.failure).toBe(""); expect(result.output).toBe("```\n\n```"); - expect(yield* captured("")).toBe("```\n\n```"); + expect(yield* captured(undefined, "")).toBe("```\n\n```"); }); it("CB1: ordinary Markdown keeps its own lines, and gains no final line feed", function* () { const value = "# Title\n\n- one\n- two"; - const result = yield* directly(value); + const result = yield* directly(undefined, value); expect(result.output).toBe("```\n# Title\n\n- one\n- two\n```"); - expect(yield* captured(value)).toBe("```\n# Title\n\n- one\n- two\n```"); + expect(yield* captured(undefined, value)).toBe("```\n# Title\n\n- one\n- two\n```"); }); - it("CB1: the block lands where the element was written", function* () { + journalCase("CB1: the block lands where the element was written", "doc.md", function* (stream) { const result = yield* run( + stream, 'before\n\n\n\nafter\n', { v: "shown" }, ); @@ -174,7 +193,7 @@ describe("Tier CB — the fence the value cannot close", () => { ]; for (const [value, length] of cases) { - const block = yield* captured(value); + const block = yield* captured(undefined, value); const fence = "`".repeat(length); expect(block).toBe(`${fence}\n${value}\n${fence}`); @@ -187,8 +206,8 @@ describe("Tier CB — the fence the value cannot close", () => { it("CB2: a run broken by any other character is two runs, not one", function* () { // Counting backticks without resetting would read five here and open a // six-backtick fence. - expect(yield* captured("```\n``")).toBe("````\n```\n``\n````"); - expect(yield* captured("``x``x``")).toBe("```\n``x``x``\n```"); + expect(yield* captured(undefined, "```\n``")).toBe("````\n```\n``\n````"); + expect(yield* captured(undefined, "``x``x``")).toBe("```\n``x``x``\n```"); }); }); @@ -203,7 +222,7 @@ describe("Tier CB — the value is not read for anything else", () => { "`` two `````` six", "trailing spaces ", ].join("\n"); - const block = yield* captured(value); + const block = yield* captured(undefined, value); // The value's longest run is six backticks, so the fence is seven. const fence = "`".repeat(7); @@ -219,15 +238,19 @@ describe("Tier CB — the value is not read for anything else", () => { }); describe("Tier CB — the language token", () => { - it("CB4: an omitted language leaves the opening fence bare", function* () { - expect((yield* captured("plain")).split("\n")[0]).toBe("```"); - }); + journalCase( + "CB4: an omitted language leaves the opening fence bare", + "doc.md", + function* (stream) { + expect((yield* captured(stream, "plain")).split("\n")[0]).toBe("```"); + }, + ); it("CB4: every accepted token renders on the opening fence, unchanged", function* () { const accepted = ["markdown", "md", "json", "shell-session", "c++", "c#", "F", "x1._+#-"]; for (const language of accepted) { - const result = yield* directly("body", ` language="${language}"`); + const result = yield* directly(undefined, "body", ` language="${language}"`); expect(result.failure).toBe(""); expect(result.output).toBe("```" + language + "\nbody\n```"); @@ -261,6 +284,7 @@ describe("Tier CB — the language token", () => { for (const language of refused) { const result = yield* run( + undefined, '', { v: "body", lang: language }, ); @@ -274,45 +298,54 @@ describe("Tier CB — the language token", () => { }); describe("Tier CB — the invocation is refused before the body", () => { - it("CB5: a missing value is the engine's own required-prop refusal", function* () { - const result = yield* run(""); + journalCase( + "CB5: a missing value is the engine's own required-prop refusal", + "doc.md", + function* (stream) { + const result = yield* run(stream, ""); - expect(reported(result)).toContain("Prop validation failed for "); - expect(reported(result)).toContain("value"); - expect(result.output).not.toContain("```"); - }); + expect(reported(result)).toContain("Prop validation failed for "); + expect(reported(result)).toContain("value"); + expect(result.output).not.toContain("```"); + }, + ); it("CB5: a non-string value is refused rather than coerced", function* () { for (const value of ["42", "true", "null", "{ text: 'x' }", "['x']"]) { - const result = yield* run(``); + const result = yield* run(undefined, ``); expect(reported(result)).toContain("Prop validation failed for "); expect(result.output).not.toContain("```"); } }); - it("CB5: an unknown prop is refused, and nothing renders", function* () { - const result = yield* directly("body", ' fence="~~~"'); + journalCase("CB5: an unknown prop is refused, and nothing renders", "doc.md", function* (stream) { + const result = yield* directly(stream, "body", ' fence="~~~"'); expect(reported(result)).toContain("Prop validation failed for "); expect(reported(result)).toContain("fence"); expect(result.output).not.toContain("body"); }); - it("CB5: paired content is refused by form, and the content never expands", function* () { - const result = yield* run( - '', - { v: "body" }, - ); + journalCase( + "CB5: paired content is refused by form, and the content never expands", + "doc.md", + function* (stream) { + const result = yield* run( + stream, + '', + { v: "body" }, + ); - expect(reported(result)).toContain(""); - expect(result.tripped).toBe(0); - expect(result.output).not.toContain("TRIPPED"); - expect(result.output).not.toContain("```"); - }); + expect(reported(result)).toContain(""); + expect(result.tripped).toBe(0); + expect(result.output).not.toContain("TRIPPED"); + expect(result.output).not.toContain("```"); + }, + ); - it("CB5: empty paired content is still the paired form", function* () { - const result = yield* run('', { + journalCase("CB5: empty paired content is still the paired form", "doc.md", function* (stream) { + const result = yield* run(stream, '', { v: "body", }); @@ -338,7 +371,7 @@ const HOSTILE = [ describe("Tier CB — inertness and capture", () => { it("CB6: candidate-like content is shown, not run, and not escaped", function* () { - const result = yield* directly(HOSTILE); + const result = yield* directly(undefined, HOSTILE); expect(result.failure).toBe(""); expect(result.tripped).toBe(0); @@ -351,8 +384,9 @@ describe("Tier CB — inertness and capture", () => { }); it("CB6: `as` binds that exact string and emits nothing where it was written", function* () { - const direct = yield* directly(HOSTILE); + const direct = yield* directly(undefined, HOSTILE); const result = yield* run( + undefined, 'beforeafter', { v: HOSTILE }, ); diff --git a/packages/core/tests/compiler-boundary.test.ts b/packages/core/tests/compiler-boundary.test.ts index 4dfb4c1a1..99b575884 100644 --- a/packages/core/tests/compiler-boundary.test.ts +++ b/packages/core/tests/compiler-boundary.test.ts @@ -6,51 +6,72 @@ * no compiler, one with eval blocks says so plainly when none is installed, * and a compiler the caller installed is the one that runs. */ -import { describe, it } from "@executablemd/test-support/bdd"; +import { describe } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import type { Operation } from "effection"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import type { InMemoryStream } from "@executablemd/durable-streams"; import { useStubFs } from "@executablemd/runtime/test"; import { API } from "@executablemd/runtime"; import { asText, completion } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/compiler-boundary.test.ts"); /** What the run said: its rendered text, or the failure it reported. */ -function* runDoc(source: string): Operation { +function* runDoc(stream: InMemoryStream, source: string): Operation { yield* useStubFs({ "doc.md": source }); - const result = yield* completion({ path: "doc.md", stream: new InMemoryStream() }); + const result = yield* completion({ path: "doc.md", stream }); return result.ok ? asText(result.value) : result.error.message; } describe("Tier CB — compiler boundary", () => { - it("CB1: a document without eval blocks runs with no compiler installed", function* () { - const output = yield* runDoc("# Plain\n\nJust prose, no fences.\n"); - expect(output).toContain("Just prose, no fences."); - expect(output).not.toContain("ERROR"); - }); + journalCase( + "CB1: a document without eval blocks runs with no compiler installed", + "doc.md", + function* (stream) { + const output = yield* runDoc(stream, "# Plain\n\nJust prose, no fences.\n"); + expect(output).toContain("Just prose, no fences."); + expect(output).not.toContain("ERROR"); + }, + ); - it("CB2: an eval block without compiler middleware reports that explicitly", function* () { - const output = yield* runDoc(["# Doc", "", "```js eval", "env.x = 1;", "```", ""].join("\n")); - expect(output).toContain("compiler not installed"); - expect(output).toContain("API.Env.around()"); - }); + journalCase( + "CB2: an eval block without compiler middleware reports that explicitly", + "doc.md", + function* (stream) { + const output = yield* runDoc( + stream, + ["# Doc", "", "```js eval", "env.x = 1;", "```", ""].join("\n"), + ); + expect(output).toContain("compiler not installed"); + expect(output).toContain("API.Env.around()"); + }, + ); - it("CB3: execute() uses the caller's compiler rather than shadowing it", function* () { - const compiled: string[] = []; - yield* API.Env.around( - { - *compile([source]) { - compiled.push(source); - return function* () { - return undefined; - }; + journalCase( + "CB3: execute() uses the caller's compiler rather than shadowing it", + "doc.md", + function* (stream) { + const compiled: string[] = []; + yield* API.Env.around( + { + *compile([source]) { + compiled.push(source); + return function* () { + return undefined; + }; + }, }, - }, - { at: "min" }, - ); + { at: "min" }, + ); - const output = yield* runDoc(["# Doc", "", "```js eval", "env.x = 1;", "```", ""].join("\n")); - expect(output).not.toContain("compiler not installed"); - expect(compiled).toHaveLength(1); - expect(compiled[0]).toContain("env.x = 1;"); - }); + const output = yield* runDoc( + stream, + ["# Doc", "", "```js eval", "env.x = 1;", "```", ""].join("\n"), + ); + expect(output).not.toContain("compiler not installed"); + expect(compiled).toHaveLength(1); + expect(compiled[0]).toContain("env.x = 1;"); + }, + ); }); diff --git a/packages/core/tests/eval-durable.test.ts b/packages/core/tests/eval-durable.test.ts index a56d1d1f6..678055027 100644 --- a/packages/core/tests/eval-durable.test.ts +++ b/packages/core/tests/eval-durable.test.ts @@ -14,12 +14,14 @@ import { useStubFs, useEchoExec } from "@executablemd/runtime/test"; import { execute } from "../src/execute.ts"; import { collect } from "../src/collect.ts"; import { completion, failureMessage } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/eval-durable.test.ts"); describe("Tier T4 — eval factory and journal integration", () => { beforeAll(() => useTempFileCompiler()); // T31: Golden run — journal entry written with serializable exports - it("T31: golden run — journal records eval entry", function* () { - const stream = new InMemoryStream(); + journalCase("T31: golden run — journal records eval entry", "test.md", function* (stream) { const files = { "test.md": "```js eval\nconst x = 42;\n```\n", }; @@ -111,8 +113,7 @@ describe("Tier T4 — eval factory and journal integration", () => { }); // T36: Serializable binding — present in journal result - it("T36: serializable binding present in journal", function* () { - const stream = new InMemoryStream(); + journalCase("T36: serializable binding present in journal", "test.md", function* (stream) { const files = { "test.md": '```js eval\nconst port = 3000;\nconst host = "localhost";\n```\n', }; @@ -131,8 +132,7 @@ describe("Tier T4 — eval factory and journal integration", () => { }); // T37: Non-serializable binding — absent from journal, present live - it("T37: non-serializable binding omitted from journal", function* () { - const stream = new InMemoryStream(); + journalCase("T37: non-serializable binding omitted from journal", "test.md", function* (stream) { const files = { "test.md": "```js eval\nconst fn = () => 42;\nconst x = 1;\n```\n", }; @@ -152,31 +152,34 @@ describe("Tier T4 — eval factory and journal integration", () => { }); // T-import-1: eval block with user import — runs through full pipeline - it("T-import-1: eval block with user import runs correctly", function* () { - const stream = new InMemoryStream(); - // Import from a well-known Deno/Node built-in to avoid needing - // an actual package. We use a self-contained data: URI import - // that's resolvable at runtime. - const files = { - "test.md": [ - "```ts eval", - 'import { basename } from "node:path";', - "", - 'const name = basename("/foo/bar/baz.txt");', - "return name;", - "```", - ].join("\n"), - }; - yield* useStubFs(files); - yield* useEchoExec(); - - const output = yield* collect( - yield* execute({ - path: "test.md", - stream, - }), - ); - - expect(output).toContain("baz.txt"); - }); + journalCase( + "T-import-1: eval block with user import runs correctly", + "test.md", + function* (stream) { + // Import from a well-known Deno/Node built-in to avoid needing + // an actual package. We use a self-contained data: URI import + // that's resolvable at runtime. + const files = { + "test.md": [ + "```ts eval", + 'import { basename } from "node:path";', + "", + 'const name = basename("/foo/bar/baz.txt");', + "return name;", + "```", + ].join("\n"), + }; + yield* useStubFs(files); + yield* useEchoExec(); + + const output = yield* collect( + yield* execute({ + path: "test.md", + stream, + }), + ); + + expect(output).toContain("baz.txt"); + }, + ); }); diff --git a/packages/core/tests/parse-components.test.ts b/packages/core/tests/parse-components.test.ts index 523a90de0..452ee1efd 100644 --- a/packages/core/tests/parse-components.test.ts +++ b/packages/core/tests/parse-components.test.ts @@ -20,6 +20,9 @@ import { Execution, execute } from "../src/execute.ts"; import { collect } from "../src/collect.ts"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import type { Json } from "../src/types.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/parse-components.test.ts"); interface Run { /** Rendered output, or the failure message when the document aborted. */ @@ -37,7 +40,7 @@ interface Run { * A document failure is captured rather than thrown: several cases are about * *what* the failure says, and about what did not happen before it. */ -function run(source: string): Operation { +function run(journal: InMemoryStream | undefined, source: string): Operation { return scoped(function* () { const commands: string[] = []; yield* API.Process.around({ @@ -49,7 +52,7 @@ function run(source: string): Operation { }); yield* useStubFs({ "doc.md": source }); - const stream = new InMemoryStream(); + const stream = journal ?? new InMemoryStream(); const result = yield* execute({ path: "doc.md", stream }); const outcome = yield* result; const events = stream.snapshot(); @@ -106,58 +109,70 @@ const SCHEMA_INVALID = `{ "a": 1 } { beforeAll(() => useTempFileCompiler()); - it("PC1: schema is required", function* () { - const { output } = yield* run(`1`); + journalCase("PC1: schema is required", "doc.md", function* (stream) { + const { output } = yield* run(stream, `1`); expect(output).toContain("Parse"); expect(output).toContain("schema"); }); - it("PC2: a capture name is required", function* () { - const { output } = yield* run(`{ "a": "x" }`); + journalCase("PC2: a capture name is required", "doc.md", function* (stream) { + const { output } = yield* run(stream, `{ "a": "x" }`); expect(output).toContain("must be invoked"); expect(output).toContain('as="binding"'); }); - it("PC3: schema text that is not JSON fails", function* () { - const { output } = yield* run(`1`); + journalCase("PC3: schema text that is not JSON fails", "doc.md", function* (stream) { + const { output } = yield* run(stream, `1`); expect(output).toContain("schema text is not JSON"); }); - it("PC4: a schema that is not a valid draft-07 schema fails", function* () { - const { output } = yield* run(`1`); - expect(output).toContain("not a valid draft-07 JSON Schema"); - }); - - it("PC5: an asynchronous schema is rejected", function* () { + journalCase( + "PC4: a schema that is not a valid draft-07 schema fails", + "doc.md", + function* (stream) { + const { output } = yield* run( + stream, + `1`, + ); + expect(output).toContain("not a valid draft-07 JSON Schema"); + }, + ); + + journalCase("PC5: an asynchronous schema is rejected", "doc.md", function* (stream) { const { output } = yield* run( + stream, `{ }`, ); expect(output).toContain("asynchronous schema"); }); - it("PC6: a schema that is not an object is rejected", function* () { - const { output } = yield* run(`1`); + journalCase("PC6: a schema that is not an object is rejected", "doc.md", function* (stream) { + const { output } = yield* run(stream, `1`); expect(output).toContain("must be a JSON Schema object"); }); // The whole point of compiling first: an unusable schema must not let the // document do work whose result it would then refuse to judge. - it("PC7: the schema compiles before any child effect runs", function* () { - const source = [ - ``, - "", - "```sh exec", - "echo should-not-run", - "```", - "", - "", - ].join("\n"); - const { output, commands } = yield* run(source); - expect(output).toContain("not a valid draft-07 JSON Schema"); - expect(commands).toEqual([]); - }); + journalCase( + "PC7: the schema compiles before any child effect runs", + "doc.md", + function* (stream) { + const source = [ + ``, + "", + "```sh exec", + "echo should-not-run", + "```", + "", + "", + ].join("\n"); + const { output, commands } = yield* run(stream, source); + expect(output).toContain("not a valid draft-07 JSON Schema"); + expect(commands).toEqual([]); + }, + ); - it("PC8: SafeParse compiles before child effects too", function* () { + journalCase("PC8: SafeParse compiles before child effects too", "doc.md", function* (stream) { const source = [ ``, "", @@ -167,59 +182,79 @@ describe("Tier PC — Parse and SafeParse", { sanitizeOps: false, sanitizeResour "", "", ].join("\n"); - const { output, commands } = yield* run(source); + const { output, commands } = yield* run(stream, source); expect(output).toContain("asynchronous schema"); expect(commands).toEqual([]); }); // SafeParse absorbs JSON syntax and instance validation, and nothing else. - it("PC9: a child failure propagates through SafeParse unchanged", function* () { - const { output } = yield* run( - ``, - ); - expect(output).toContain("Missing"); - expect(output).not.toContain('"ok"'); - }); - - it("PC10: a Parse failure names the component and carries its issues", function* () { - const { output } = yield* run(`{ "a": 1 }\n`); - expect(output).toContain("Parse"); - expect(output).toContain("content failed its schema"); - expect(output).toContain("must be string"); - }); - - it("PC10: content the schema rejects fails the document and stops later work", function* () { - const { output, failed, commands, events } = yield* run(laterEffect(SCHEMA_INVALID)); - expect(failed).toBe(true); - expect(output).toContain("Parse"); - expect(output).toContain("content failed its schema"); - expect(output).toContain("must be string"); - expect(commands).toEqual([]); - - const outcome = retained(events); - expect(outcome.status).toBe("err"); - expect(outcome.output).toContain("PREFIX"); - expect(outcome.output).not.toContain("LATER_EFFECT"); - expect(outcome.bound).not.toContain("v"); - }); - - it("PC11: malformed JSON is reported as a parse failure", function* () { - const { output } = yield* run(`nope`); + journalCase( + "PC9: a child failure propagates through SafeParse unchanged", + "doc.md", + function* (stream) { + const { output } = yield* run( + stream, + ``, + ); + expect(output).toContain("Missing"); + expect(output).not.toContain('"ok"'); + }, + ); + + journalCase( + "PC10: a Parse failure names the component and carries its issues", + "doc.md", + function* (stream) { + const { output } = yield* run( + stream, + `{ "a": 1 }\n`, + ); + expect(output).toContain("Parse"); + expect(output).toContain("content failed its schema"); + expect(output).toContain("must be string"); + }, + ); + + journalCase( + "PC10: content the schema rejects fails the document and stops later work", + "doc.md", + function* (stream) { + const { output, failed, commands, events } = yield* run(stream, laterEffect(SCHEMA_INVALID)); + expect(failed).toBe(true); + expect(output).toContain("Parse"); + expect(output).toContain("content failed its schema"); + expect(output).toContain("must be string"); + expect(commands).toEqual([]); + + const outcome = retained(events); + expect(outcome.status).toBe("err"); + expect(outcome.output).toContain("PREFIX"); + expect(outcome.output).not.toContain("LATER_EFFECT"); + expect(outcome.bound).not.toContain("v"); + }, + ); + + journalCase("PC11: malformed JSON is reported as a parse failure", "doc.md", function* (stream) { + const { output } = yield* run(stream, `nope`); expect(output).toContain("content is not JSON"); }); - it("PC11: malformed JSON fails the document and stops later work", function* () { - const { output, failed, commands, events } = yield* run(laterEffect(MALFORMED)); - expect(failed).toBe(true); - expect(output).toContain("Parse"); - expect(output).toContain("content is not JSON"); - expect(commands).toEqual([]); - - const outcome = retained(events); - expect(outcome.status).toBe("err"); - expect(outcome.output).toContain("PREFIX"); - expect(outcome.bound).not.toContain("v"); - }); + journalCase( + "PC11: malformed JSON fails the document and stops later work", + "doc.md", + function* (stream) { + const { output, failed, commands, events } = yield* run(stream, laterEffect(MALFORMED)); + expect(failed).toBe(true); + expect(output).toContain("Parse"); + expect(output).toContain("content is not JSON"); + expect(commands).toEqual([]); + + const outcome = retained(events); + expect(outcome.status).toBe("err"); + expect(outcome.output).toContain("PREFIX"); + expect(outcome.bound).not.toContain("v"); + }, + ); // Completion is the execution's settlement, so it waits for everything the // execution owns — including cleanup a host established at initialization. @@ -305,7 +340,7 @@ describe("Tier PC — Parse and SafeParse", { sanitizeOps: false, sanitizeResour "", "", ].join("\n"); - const { output, failed, commands, events } = yield* run(source); + const { output, failed, commands, events } = yield* run(undefined, source); expect(failed).toBe(false); expect(output).toContain(`INPUT ${content}|${keyword}|${path}`); expect(commands).toHaveLength(1); @@ -314,49 +349,58 @@ describe("Tier PC — Parse and SafeParse", { sanitizeOps: false, sanitizeResour } }); - it("PC11c: an authored PrintErrors region recovers from a Parse failure", function* () { - const source = [ - "", - "", - SCHEMA_INVALID, - "", - "", - "", - 'UNBOUND', - "", - "```sh exec", - "echo LATER_EFFECT", - "```", - "", - ].join("\n"); - const { output, failed, commands, events } = yield* run(source); - expect(failed).toBe(false); - expect(output).toContain("content failed its schema"); - expect(output).toContain("must be string"); - expect(output).toContain("UNBOUND"); - expect(commands).toHaveLength(1); - expect(commands[0]).toContain("LATER_EFFECT"); - expect(retained(events).status).toBe("ok"); - }); + journalCase( + "PC11c: an authored PrintErrors region recovers from a Parse failure", + "doc.md", + function* (stream) { + const source = [ + "", + "", + SCHEMA_INVALID, + "", + "", + "", + 'UNBOUND', + "", + "```sh exec", + "echo LATER_EFFECT", + "```", + "", + ].join("\n"); + const { output, failed, commands, events } = yield* run(stream, source); + expect(failed).toBe(false); + expect(output).toContain("content failed its schema"); + expect(output).toContain("must be string"); + expect(output).toContain("UNBOUND"); + expect(commands).toHaveLength(1); + expect(commands[0]).toContain("LATER_EFFECT"); + expect(retained(events).status).toBe("ok"); + }, + ); - it("PC12: neither component renders output", function* () { + journalCase("PC12: neither component renders output", "doc.md", function* (stream) { const source = [ `1`, `2`, "done", ].join("\n\n"); - const { output, failed } = yield* run(source); + const { output, failed } = yield* run(stream, source); expect(failed).toBe(false); expect(output.trim()).toBe("done"); }); - it("PC13: an external reference fails with the documented limit", function* () { - const { output } = yield* run( - `1`, - ); - expect(output).toContain("could not resolve a schema reference"); - expect(output).toContain("#192"); - }); + journalCase( + "PC13: an external reference fails with the documented limit", + "doc.md", + function* (stream) { + const { output } = yield* run( + stream, + `1`, + ); + expect(output).toContain("could not resolve a schema reference"); + expect(output).toContain("#192"); + }, + ); // Parsing performs no effects and a built-in records no import, so a second // run over a completed journal must reproduce the result without appending. diff --git a/packages/core/tests/props-binding.test.ts b/packages/core/tests/props-binding.test.ts index 0003e50d3..ae7881438 100644 --- a/packages/core/tests/props-binding.test.ts +++ b/packages/core/tests/props-binding.test.ts @@ -1,6 +1,6 @@ -import { describe, it } from "@executablemd/test-support/bdd"; +import { describe } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import type { InMemoryStream } from "@executablemd/durable-streams"; import type { Json } from "@executablemd/durable-streams"; import { useEchoExec, useStubFs } from "@executablemd/runtime/test"; import { forEach } from "@effectionx/stream-helpers"; @@ -9,8 +9,12 @@ import { beforeAll } from "@executablemd/test-support/bdd"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import type { Operation, Result } from "effection"; import { Stdio } from "@effectionx/process"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/props-binding.test.ts"); function* runDocument( + stream: InMemoryStream, files: Record, props?: Record, ): Operation { @@ -25,7 +29,7 @@ function* runDocument( displayed += decoder.decode(bytes); }, }); - const execution = yield* execute({ path: "root.md", stream: new InMemoryStream(), props }); + const execution = yield* execute({ path: "root.md", stream, props }); const output = yield* forEach(function* () {}, execution.output); const result = yield* execution; return { output, displayed, result }; @@ -61,37 +65,43 @@ const ROOT_PROPS = [ describe("props binding", () => { beforeAll(() => useTempFileCompiler()); - it("installs root props for text, eval, expression, and executable interpolation", function* () { - const { output, displayed, result } = yield* runDocument( - { - "root.md": [ - ROOT_PROPS, - "", - "text={props.name} bare={name} dotted={props.release.version} tags={props.tags} missing={props.release.missing} escaped=\\{props.name}", - "", - "```js eval", - "return `eval=${props.name} dotted=${props.release.version} bare=${typeof declaredOnly}`;", - "```", - "", - "```bash exec", - "echo {props.name}/{props.release.version}", - "```", - "", - ].join("\n"), - }, - { name: "Ada", declaredOnly: "field", tags: ["a", "b"], release: { version: "1.2.3" } }, - ); + journalCase( + "installs root props for text, eval, expression, and executable interpolation", + "root.md", + function* (stream) { + const { output, displayed, result } = yield* runDocument( + stream, + { + "root.md": [ + ROOT_PROPS, + "", + "text={props.name} bare={name} dotted={props.release.version} tags={props.tags} missing={props.release.missing} escaped=\\{props.name}", + "", + "```js eval", + "return `eval=${props.name} dotted=${props.release.version} bare=${typeof declaredOnly}`;", + "```", + "", + "```bash exec", + "echo {props.name}/{props.release.version}", + "```", + "", + ].join("\n"), + }, + { name: "Ada", declaredOnly: "field", tags: ["a", "b"], release: { version: "1.2.3" } }, + ); - expect(result.ok).toBe(true); - expect(output).toContain( - "text=Ada bare={name} dotted=1.2.3 tags=a, b missing= escaped={props.name}", - ); - expect(output).toContain("eval=Ada dotted=1.2.3 bare=undefined"); - expect(displayed).toContain("Ada/1.2.3"); - }); + expect(result.ok).toBe(true); + expect(output).toContain( + "text=Ada bare={name} dotted=1.2.3 tags=a, b missing= escaped={props.name}", + ); + expect(output).toContain("eval=Ada dotted=1.2.3 bare=undefined"); + expect(displayed).toContain("Ada/1.2.3"); + }, + ); - it("keeps eval-created locals independent from props", function* () { + journalCase("keeps eval-created locals independent from props", "root.md", function* (stream) { const { output, displayed } = yield* runDocument( + stream, { "root.md": [ ROOT_PROPS, @@ -111,8 +121,9 @@ describe("props binding", () => { expect(output).toContain("local=local prop=Ada"); }); - it("does not begin body effects for invalid root props", function* () { + journalCase("does not begin body effects for invalid root props", "root.md", function* (stream) { const { output, displayed, result } = yield* runDocument( + stream, { "root.md": [ROOT_PROPS, "", "```bash exec", "echo BODY_EFFECT", "```", ""].join("\n"), }, @@ -123,277 +134,312 @@ describe("props binding", () => { expect(output).not.toContain("BODY_EFFECT"); }); - it("uses caller props for projected content and callee props for authored content", function* () { - const { output, displayed, result } = yield* runDocument( - { - "root.md": [ - ROOT_PROPS, - "", - "```js eval", - 'const label = "caller";', - "```", - '', - "projected={props.name}", - "projected-label={label}", - "", - "```bash exec", - "echo {props.name}", - "```", - "", - "", - ].join("\n"), - "Wrapper.md": [ + journalCase( + "uses caller props for projected content and callee props for authored content", + "root.md", + function* (stream) { + const { output, displayed, result } = yield* runDocument( + stream, + { + "root.md": [ + ROOT_PROPS, + "", + "```js eval", + 'const label = "caller";', + "```", + '', + "projected={props.name}", + "projected-label={label}", + "", + "```bash exec", + "echo {props.name}", + "```", + "", + "", + ].join("\n"), + "Wrapper.md": [ + "---", + "props:", + " type: object", + " properties:", + " name: { type: string }", + " forwarded: { type: string }", + " required: [name, forwarded]", + " additionalProperties: false", + "---", + "```js eval", + 'const label = "callee";', + "```", + "authored={props.name} forwarded={props.forwarded} authored-label={label}", + "```js eval", + "return `component-eval=${props.name}`;", + "```", + "```bash exec", + "echo authored-exec={props.name}", + "```", + "", + "```js eval", + 'return yield* render("rendered={props.name} label={label}");', + "```", + "", + "", + ].join("\n"), + "Child.md": [ + "---", + "props:", + " type: object", + " properties:", + " value: { type: string }", + " required: [value]", + " additionalProperties: false", + "---", + "child={props.value}", + "", + ].join("\n"), + }, + { name: "caller", release: { version: "1.2.3" } }, + ); + + expect(result.ok).toBe(true); + expect(output).toContain("authored=callee"); + expect(output).toContain("forwarded=caller"); + expect(output).toContain("authored-label=callee"); + expect(output).toContain("component-eval=callee"); + expect(displayed).toContain("authored-exec=callee"); + expect(output).toContain("rendered=callee label=callee"); + expect(output).toContain("projected=caller"); + expect(output).toContain("projected-label=callee"); + expect(output).toContain("child=caller"); + expect(output).toContain("caller"); + expect(output).not.toContain("ERROR"); + }, + ); + + journalCase( + "restores the enclosing props binding after scoped and nested expansion", + "root.md", + function* (stream) { + const { output, displayed, result } = yield* runDocument( + stream, + { + "root.md": [ + ROOT_PROPS, + "", + 'text={props.name}', + "```js eval", + "return `eval=${props.name}`;", + "```", + "```bash exec", + "echo exec={props.name}", + "```", + "", + "after={props.name}", + '', + "", + ].join("\n"), + "Outer.md": [ + "---", + "props:", + " name: { type: string }", + "required: [name]", + "---", + 'outer={props.name}after={props.name}', + "", + ].join("\n"), + "Inner.md": [ + "---", + "props:", + " name: { type: string }", + "required: [name]", + "---", + "inner={props.name}", + "", + ].join("\n"), + }, + { name: "caller", release: { version: "1.2.3" } }, + ); + + expect(result.ok).toBe(true); + expect(output).toContain("text=shadow"); + expect(output).toContain("eval=shadow"); + expect(displayed).toContain("exec=shadow"); + expect(output).toContain("after=caller"); + expect(output).toContain("outer=outer"); + expect(output).toContain("inner=inner"); + expect(output).toContain("after=outer"); + }, + ); + + journalCase( + "uses one validated object for the props binding and text interpolation", + "root.md", + function* (stream) { + const { output, displayed, result } = yield* runDocument(stream, { + "root.md": '\n', + "Mutator.md": [ "---", "props:", " type: object", " properties:", - " name: { type: string }", - " forwarded: { type: string }", - " required: [name, forwarded]", + " nested:", + " type: object", + " properties:", + " value: { type: string }", + " required: [value]", + " additionalProperties: false", + " required: [nested]", " additionalProperties: false", "---", "```js eval", - 'const label = "callee";', - "```", - "authored={props.name} forwarded={props.forwarded} authored-label={label}", - "```js eval", - "return `component-eval=${props.name}`;", - "```", - "```bash exec", - "echo authored-exec={props.name}", - "```", - "", - "```js eval", - 'return yield* render("rendered={props.name} label={label}");', + 'props.nested.value = "mutated";', + 'return yield* render("{props.nested.value}");', "```", - "", "", ].join("\n"), - "Child.md": [ + }); + + expect(result.ok).toBe(true); + expect(output).toContain("mutated"); + }, + ); + + journalCase( + "uses defaults before root and Markdown-component body effects", + "root.md", + function* (stream) { + const { output, displayed, result } = yield* runDocument(stream, { + "root.md": [ "---", "props:", " type: object", " properties:", - " value: { type: string }", - " required: [value]", + " name: { type: string, default: root-default }", " additionalProperties: false", "---", - "child={props.value}", - "", - ].join("\n"), - }, - { name: "caller", release: { version: "1.2.3" } }, - ); - - expect(result.ok).toBe(true); - expect(output).toContain("authored=callee"); - expect(output).toContain("forwarded=caller"); - expect(output).toContain("authored-label=callee"); - expect(output).toContain("component-eval=callee"); - expect(displayed).toContain("authored-exec=callee"); - expect(output).toContain("rendered=callee label=callee"); - expect(output).toContain("projected=caller"); - expect(output).toContain("projected-label=callee"); - expect(output).toContain("child=caller"); - expect(output).toContain("caller"); - expect(output).not.toContain("ERROR"); - }); - - it("restores the enclosing props binding after scoped and nested expansion", function* () { - const { output, displayed, result } = yield* runDocument( - { - "root.md": [ - ROOT_PROPS, - "", - 'text={props.name}', - "```js eval", - "return `eval=${props.name}`;", - "```", + "root-text={props.name}", "```bash exec", - "echo exec={props.name}", + "echo root-effect={props.name}", "```", - "", - "after={props.name}", - '', + "", "", ].join("\n"), - "Outer.md": [ + "Defaulted.md": [ "---", "props:", - " name: { type: string }", - "required: [name]", - "---", - 'outer={props.name}after={props.name}', - "", - ].join("\n"), - "Inner.md": [ - "---", - "props:", - " name: { type: string }", - "required: [name]", + " type: object", + " properties:", + " name: { type: string, default: component-default }", + " additionalProperties: false", "---", - "inner={props.name}", + "component-text={props.name}", + "```bash exec", + "echo component-effect={props.name}", + "```", "", ].join("\n"), - }, - { name: "caller", release: { version: "1.2.3" } }, - ); + }); - expect(result.ok).toBe(true); - expect(output).toContain("text=shadow"); - expect(output).toContain("eval=shadow"); - expect(displayed).toContain("exec=shadow"); - expect(output).toContain("after=caller"); - expect(output).toContain("outer=outer"); - expect(output).toContain("inner=inner"); - expect(output).toContain("after=outer"); - }); - - it("uses one validated object for the props binding and text interpolation", function* () { - const { output, displayed, result } = yield* runDocument({ - "root.md": '\n', - "Mutator.md": [ - "---", - "props:", - " type: object", - " properties:", - " nested:", - " type: object", - " properties:", - " value: { type: string }", - " required: [value]", - " additionalProperties: false", - " required: [nested]", - " additionalProperties: false", - "---", - "```js eval", - 'props.nested.value = "mutated";', - 'return yield* render("{props.nested.value}");', - "```", - "", - ].join("\n"), - }); - - expect(result.ok).toBe(true); - expect(output).toContain("mutated"); - }); - - it("uses defaults before root and Markdown-component body effects", function* () { - const { output, displayed, result } = yield* runDocument({ - "root.md": [ - "---", - "props:", - " type: object", - " properties:", - " name: { type: string, default: root-default }", - " additionalProperties: false", - "---", - "root-text={props.name}", - "```bash exec", - "echo root-effect={props.name}", - "```", - "", - "", - ].join("\n"), - "Defaulted.md": [ - "---", - "props:", - " type: object", - " properties:", - " name: { type: string, default: component-default }", - " additionalProperties: false", - "---", - "component-text={props.name}", - "```bash exec", - "echo component-effect={props.name}", - "```", - "", - ].join("\n"), - }); - - expect(result.ok).toBe(true); - expect(output).toContain("root-text=root-default"); - expect(displayed).toContain("root-effect=root-default"); - expect(output).toContain("component-text=component-default"); - expect(displayed).toContain("component-effect=component-default"); - }); - - it("does not begin a Markdown-component body effect for invalid props", function* () { - const { output, displayed, result } = yield* runDocument({ - "root.md": "\n", - "Invalid.md": [ - "---", - "props:", - " type: object", - " properties:", - " name: { type: string }", - " required: [name]", - " additionalProperties: false", - "---", - "```bash exec", - "echo INVALID_BODY_EFFECT", - "```", - "body={props.name}", - "", - ].join("\n"), - }); - - // Rejected before the body, and nothing recovers it, so it ends the run. - expect(result.ok).toBe(false); - expect(result.ok ? "" : result.error.message).toContain("Invalid"); - expect(displayed).not.toContain("INVALID_BODY_EFFECT"); - expect(output).not.toContain("INVALID_BODY_EFFECT"); - expect(output).not.toContain("body="); - }); + expect(result.ok).toBe(true); + expect(output).toContain("root-text=root-default"); + expect(displayed).toContain("root-effect=root-default"); + expect(output).toContain("component-text=component-default"); + expect(displayed).toContain("component-effect=component-default"); + }, + ); - it("uses one shadowed props binding for text, eval, and exec, then restores it", function* () { - const { output, displayed, result } = yield* runDocument( - { - "root.md": [ROOT_PROPS, "", "", "after={props.name}", ""].join("\n"), - "Shadow.md": [ + journalCase( + "does not begin a Markdown-component body effect for invalid props", + "root.md", + function* (stream) { + const { output, displayed, result } = yield* runDocument(stream, { + "root.md": "\n", + "Invalid.md": [ "---", "props:", " type: object", - " properties: {}", + " properties:", + " name: { type: string }", + " required: [name]", " additionalProperties: false", "---", - "```js eval", - 'const props = { name: "shadow" };', - "return `eval=${props.name}`;", - "```", - "text={props.name}", - "```js eval", - "return `after-eval=${props.name}`;", - "```", "```bash exec", - "echo exec={props.name}", + "echo INVALID_BODY_EFFECT", "```", + "body={props.name}", "", ].join("\n"), - }, - { name: "caller", release: { version: "1.2.3" } }, - ); + }); - expect(result.ok).toBe(true); - expect(output).toContain("eval=shadow"); - expect(output).toContain("after-eval=shadow"); - expect(output).toContain("text=shadow"); - expect(displayed).toContain("exec=shadow"); - expect(output).toContain("after=caller"); - }); + // Rejected before the body, and nothing recovers it, so it ends the run. + expect(result.ok).toBe(false); + expect(result.ok ? "" : result.error.message).toContain("Invalid"); + expect(displayed).not.toContain("INVALID_BODY_EFFECT"); + expect(output).not.toContain("INVALID_BODY_EFFECT"); + expect(output).not.toContain("body="); + }, + ); - it("allows an authored props binding to shadow the namespace locally", function* () { - const { output, displayed, result } = yield* runDocument( - { - "root.md": [ROOT_PROPS, "", 'shadowed{props} {props.name}', ""].join( - "\n", - ), - }, - { name: "caller", release: { version: "1.2.3" } }, - ); + journalCase( + "uses one shadowed props binding for text, eval, and exec, then restores it", + "root.md", + function* (stream) { + const { output, displayed, result } = yield* runDocument( + stream, + { + "root.md": [ROOT_PROPS, "", "", "after={props.name}", ""].join("\n"), + "Shadow.md": [ + "---", + "props:", + " type: object", + " properties: {}", + " additionalProperties: false", + "---", + "```js eval", + 'const props = { name: "shadow" };', + "return `eval=${props.name}`;", + "```", + "text={props.name}", + "```js eval", + "return `after-eval=${props.name}`;", + "```", + "```bash exec", + "echo exec={props.name}", + "```", + "", + ].join("\n"), + }, + { name: "caller", release: { version: "1.2.3" } }, + ); - expect(result.ok).toBe(true); - expect(output).toContain("shadowed"); - expect(output).not.toContain("caller"); - }); + expect(result.ok).toBe(true); + expect(output).toContain("eval=shadow"); + expect(output).toContain("after-eval=shadow"); + expect(output).toContain("text=shadow"); + expect(displayed).toContain("exec=shadow"); + expect(output).toContain("after=caller"); + }, + ); + + journalCase( + "allows an authored props binding to shadow the namespace locally", + "root.md", + function* (stream) { + const { output, displayed, result } = yield* runDocument( + stream, + { + "root.md": [ + ROOT_PROPS, + "", + 'shadowed{props} {props.name}', + "", + ].join("\n"), + }, + { name: "caller", release: { version: "1.2.3" } }, + ); + + expect(result.ok).toBe(true); + expect(output).toContain("shadowed"); + expect(output).not.toContain("caller"); + }, + ); }); diff --git a/packages/core/tests/root-composition.test.ts b/packages/core/tests/root-composition.test.ts index a209bac58..35d46b80f 100644 --- a/packages/core/tests/root-composition.test.ts +++ b/packages/core/tests/root-composition.test.ts @@ -24,15 +24,22 @@ import { inlineSource } from "../src/root-source.ts"; import { registerComponents } from "../src/components/registration.ts"; import { getExpansion } from "../src/expansion.ts"; import { Document, RootMetadata } from "../api.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/core/tests/root-composition.test.ts"); const NO_PROPS = { type: "object", properties: {}, additionalProperties: false }; /** Render one inline root, with whatever this scope installed around it. */ -function* render(source: string, props?: Record): Operation { +function* render( + stream: InMemoryStream | undefined, + source: string, + props?: Record, +): Operation { const value = yield* collect( yield* execute({ ...inlineSource(source), - stream: new InMemoryStream(), + stream: stream ?? new InMemoryStream(), ...(props === undefined ? {} : { props }), }), ); @@ -40,10 +47,14 @@ function* render(source: string, props?: Record): Operation): Operation { +function* settled( + stream: InMemoryStream | undefined, + source: string, + props?: Record, +): Operation { const execution = yield* execute({ ...inlineSource(source), - stream: new InMemoryStream(), + stream: stream ?? new InMemoryStream(), ...(props === undefined ? {} : { props }), }); yield* collect(execution); @@ -52,9 +63,9 @@ function* settled(source: string, props?: Record): Operation } /** Render one inline root, or the failure it raised, as text. */ -function* rendered(source: string): Operation { +function* rendered(stream: InMemoryStream | undefined, source: string): Operation { try { - return yield* render(source); + return yield* render(stream, source); } catch (error) { return error instanceof Error ? error.message : String(error); } @@ -93,11 +104,11 @@ const ROOT = ["# Heading", "", "body text", ""].join("\n"); describe("RC1 — with no document middleware the root is the root", () => { it("renders exactly what executing the document directly renders", function* () { - expect(yield* render(ROOT)).toBe(yield* scoped(() => render(ROOT))); - expect(yield* render(ROOT)).toContain("body text"); + expect(yield* render(undefined, ROOT)).toBe(yield* scoped(() => render(undefined, ROOT))); + expect(yield* render(undefined, ROOT)).toContain("body text"); }); - it("keeps the document's own props, returns and value", function* () { + journalCase("keeps the document's own props, returns and value", "", function* (stream) { const source = [ "---", "props:", @@ -111,28 +122,32 @@ describe("RC1 — with no document middleware the root is the root", () => { "", "", ].join("\n"); - expect(yield* settled(source, { who: "caller" })).toBe("caller"); + expect(yield* settled(stream, source, { who: "caller" })).toBe("caller"); }); }); describe("RC2 — a wrapper composes around the projected document", () => { - it("renders the envelope with the original document inside it", function* () { - const output = yield* scoped(function* () { - yield* useEnvelope("before\n\n", "\n\nafter"); - return yield* render(ROOT); - }); - expect(output).toContain("before"); - expect(output).toContain("body text"); - expect(output).toContain("after"); - expect(output.indexOf("before")).toBeLessThan(output.indexOf("body text")); - expect(output.indexOf("body text")).toBeLessThan(output.indexOf("after")); - }); + journalCase( + "renders the envelope with the original document inside it", + "", + function* (stream) { + const output = yield* scoped(function* () { + yield* useEnvelope("before\n\n", "\n\nafter"); + return yield* render(stream, ROOT); + }); + expect(output).toContain("before"); + expect(output).toContain("body text"); + expect(output).toContain("after"); + expect(output.indexOf("before")).toBeLessThan(output.indexOf("body text")); + expect(output.indexOf("body text")).toBeLessThan(output.indexOf("after")); + }, + ); - it("nests two wrappers with the first one outermost", function* () { + journalCase("nests two wrappers with the first one outermost", "", function* (stream) { const output = yield* scoped(function* () { yield* useEnvelope("one open\n\n", "\n\none close"); yield* useEnvelope("two open\n\n", "\n\ntwo close"); - return yield* render(ROOT); + return yield* render(stream, ROOT); }); const order = ["one open", "two open", "body text", "two close", "one close"]; const positions = order.map((token) => output.indexOf(token)); @@ -140,17 +155,21 @@ describe("RC2 — a wrapper composes around the projected document", () => { expect([...positions].sort((a, b) => a - b)).toEqual(positions); }); - it("projects the document once for every placeholder a wrapper writes", function* () { - const output = yield* scoped(function* () { - yield* Document.around({ - *document(_args, next) { - return `${yield* next()}\n\n${yield* next()}`; - }, + journalCase( + "projects the document once for every placeholder a wrapper writes", + "", + function* (stream) { + const output = yield* scoped(function* () { + yield* Document.around({ + *document(_args, next) { + return `${yield* next()}\n\n${yield* next()}`; + }, + }); + return yield* render(stream, "once\n"); }); - return yield* render("once\n"); - }); - expect(output.split("once").length - 1).toBe(2); - }); + expect(output.split("once").length - 1).toBe(2); + }, + ); }); describe("RC3 — projection preserves the document's own identity", () => { @@ -159,13 +178,13 @@ describe("RC3 — projection preserves the document's own identity", () => { const plain: { id: string; path?: string; line?: number }[] = []; yield* scoped(function* () { yield* useProbe(plain); - yield* render(source); + yield* render(undefined, source); }); const wrapped: { id: string; path?: string; line?: number }[] = []; yield* scoped(function* () { yield* useProbe(wrapped); yield* useEnvelope("envelope line one\n\nenvelope line two\n\n", "\n\ntail\n"); - yield* render(source); + yield* render(undefined, source); }); expect(plain).toHaveLength(1); expect(wrapped).toHaveLength(1); @@ -176,23 +195,27 @@ describe("RC3 — projection preserves the document's own identity", () => { expect(wrapped[0]?.id).toBe(plain[0]?.id); }); - it("leaves an authored an ordinary unresolved component", function* () { - // Nothing in the document's own segments is ever read for a placeholder: - // only the envelope this engine scanned is. So an author who writes the - // name reaches component resolution, and there is no component there. - const output = yield* rendered("\n"); - expect(output).not.toContain("\n"); - expect(output).toMatch(/Document/); - }); + journalCase( + "leaves an authored an ordinary unresolved component", + "", + function* (stream) { + // Nothing in the document's own segments is ever read for a placeholder: + // only the envelope this engine scanned is. So an author who writes the + // name reaches component resolution, and there is no component there. + const output = yield* rendered(stream, "\n"); + expect(output).not.toContain("\n"); + expect(output).toMatch(/Document/); + }, + ); }); describe("RC4 — the document's own contract survives a wrapper", () => { it("keeps selecting what renders", function* () { const source = ["hidden", "", "", "", "selected", "", "", ""].join("\n"); - const plain = yield* render(source); + const plain = yield* render(undefined, source); const wrapped = yield* scoped(function* () { yield* useEnvelope("envelope\n\n", ""); - return yield* render(source); + return yield* render(undefined, source); }); expect(plain).toContain("selected"); expect(plain).not.toContain("hidden"); @@ -202,38 +225,42 @@ describe("RC4 — the document's own contract survives a wrapper", () => { expect(wrapped).toBe(plain); }); - it("keeps a value root's settling the run's value", function* () { - const source = [ - "---", - "returns:", - " type: string", - "---", - "", - '', - "", - ].join("\n"); - const value = yield* scoped(function* () { - yield* useEnvelope("envelope\n\n", ""); - return yield* settled(source); - }); - expect(value).toBe("settled"); - }); + journalCase( + "keeps a value root's settling the run's value", + "", + function* (stream) { + const source = [ + "---", + "returns:", + " type: string", + "---", + "", + '', + "", + ].join("\n"); + const value = yield* scoped(function* () { + yield* useEnvelope("envelope\n\n", ""); + return yield* settled(stream, source); + }); + expect(value).toBe("settled"); + }, + ); }); describe("RC5 — RootMetadata changes the root's metadata and nothing else", () => { it("composes the record the document's own interpolation reads", function* () { const source = ["---", "title: authored", "---", "", "title is {meta.title}", ""].join("\n"); - expect(yield* render(source)).toContain("title is authored"); + expect(yield* render(undefined, source)).toContain("title is authored"); const composed = yield* scoped(function* () { yield* RootMetadata.around({ metadata: (_args, next) => ({ ...next(), title: "composed" }), }); - return yield* render(source); + return yield* render(undefined, source); }); expect(composed).toContain("title is composed"); }); - it("leaves an imported component's own metadata alone", function* () { + journalCase("leaves an imported component's own metadata alone", "", function* (stream) { const composed = yield* scoped(function* () { yield* RootMetadata.around({ metadata: () => ({ title: "composed" }) }); yield* registerComponents([ @@ -247,7 +274,7 @@ describe("RC5 — RootMetadata changes the root's metadata and nothing else", () }, }, ]); - return yield* render(["root {meta.title}", "", "", ""].join("\n")); + return yield* render(stream, ["root {meta.title}", "", "", ""].join("\n")); }); expect(composed).toContain("root composed"); expect(composed).toContain("inner body"); @@ -257,16 +284,20 @@ describe("RC5 — RootMetadata changes the root's metadata and nothing else", () }); describe("RC6 — a wrapper is held to the same structure a document is", () => { - it("diagnoses an envelope whose own structure a document could not write", function* () { - // `` in a text body is a structural violation wherever it is - // written, and the composed body is what the preflight walks — so a wrapper - // is refused on the terms the document would have been, and the document's - // own body never runs. - const failure = yield* scoped(function* () { - yield* useEnvelope('\n\n', ""); - return yield* rendered(ROOT); - }); - expect(failure).toContain(""); - expect(failure).not.toContain("body text"); - }); + journalCase( + "diagnoses an envelope whose own structure a document could not write", + "", + function* (stream) { + // `` in a text body is a structural violation wherever it is + // written, and the composed body is what the preflight walks — so a wrapper + // is refused on the terms the document would have been, and the document's + // own body never runs. + const failure = yield* scoped(function* () { + yield* useEnvelope('\n\n', ""); + return yield* rendered(stream, ROOT); + }); + expect(failure).toContain(""); + expect(failure).not.toContain("body text"); + }, + ); }); From e6d35896a74ae4f006e482cda3877392684e1d16 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:13:40 -0500 Subject: [PATCH 33/78] test: attribute guarded Agent package execution controls --- .../acp/tests/agent-certification.test.ts | 55 +++++---- packages/agent/tests/package-boundary.test.ts | 61 ++++++---- .../tests/cross-package-resolution.test.ts | 107 ++++++++++-------- 3 files changed, 131 insertions(+), 92 deletions(-) diff --git a/packages/acp/tests/agent-certification.test.ts b/packages/acp/tests/agent-certification.test.ts index f1ba5c1ee..1b0aa81a8 100644 --- a/packages/acp/tests/agent-certification.test.ts +++ b/packages/acp/tests/agent-certification.test.ts @@ -1,3 +1,4 @@ +import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { ensure, scoped, spawn, withResolvers } from "effection"; @@ -208,31 +209,39 @@ describe( }); for (const setting of ["model", "effort"]) { for (const kind of ["absent", "mismatch"]) { - it(`reports exact ${setting} ${kind} evidence before any Prompt`, function* () { + const name = `reports exact ${setting} ${kind} evidence before any Prompt`; + it(name, function* () { yield* withCertificationFixture(function* (f) { - const mode = kind + "-" + setting; - const report = reportFor(f.command(mode)); - const failures: unknown[] = []; - const value = setting === "model" ? "selected" : "high"; - const result = yield* document( - f, - mode, - ``, - report, - failures, - ); - expect(result.ok).toBe(false); - expect(failures).toEqual([ - { - reason: kind === "absent" ? "selector-unavailable" : "configuration-mismatch", - setting, + yield* captureTestJournal( + { owner: "packages/acp/tests/agent-certification.test.ts", name }, + join(f.dir, "document.md"), + function* (stream) { + const mode = kind + "-" + setting; + const report = reportFor(f.command(mode)); + const failures: unknown[] = []; + const value = setting === "model" ? "selected" : "high"; + const result = yield* document( + f, + mode, + ``, + report, + failures, + stream, + ); + expect(result.ok).toBe(false); + expect(failures).toEqual([ + { + reason: kind === "absent" ? "selector-unavailable" : "configuration-mismatch", + setting, + }, + ]); + const row = + setting === "model" ? report.capabilities.model : report.capabilities.effort; + expect(row.outcome).toBe(kind === "absent" ? "unsupported" : "failure"); + expect((yield* f.methods()).includes("session/prompt")).toBe(false); + expect(JSON.stringify(report)).not.toContain("must not send"); }, - ]); - const row = - setting === "model" ? report.capabilities.model : report.capabilities.effort; - expect(row.outcome).toBe(kind === "absent" ? "unsupported" : "failure"); - expect((yield* f.methods()).includes("session/prompt")).toBe(false); - expect(JSON.stringify(report)).not.toContain("must not send"); + ); }); }); } diff --git a/packages/agent/tests/package-boundary.test.ts b/packages/agent/tests/package-boundary.test.ts index 0c4e074ca..c11e999e3 100644 --- a/packages/agent/tests/package-boundary.test.ts +++ b/packages/agent/tests/package-boundary.test.ts @@ -1,3 +1,5 @@ +import { captureTestJournal } from "../../test-support/failure-journal.ts"; +import { fileJournalCases } from "../../test-support/journal-cases.ts"; /** * Tier PB — the boundary between Core and the Agent package. * @@ -18,7 +20,6 @@ import { randomUUID } from "node:crypto"; import * as os from "node:os"; import * as path from "node:path"; import { fileURLToPath } from "node:url"; -import { InMemoryStream } from "@executablemd/durable-streams"; import { execute } from "@executablemd/core"; import type { DocumentExecution, Json } from "@executablemd/core"; import { Agent } from "@executablemd/agent/api"; @@ -84,10 +85,10 @@ const echo: AgentProviderFactory = function* (options) { }; function* run( + dir: string, doc: string, start: (docPath: string) => Operation, ): Operation<{ output: string; result: Result }> { - const dir = path.join(os.tmpdir(), `xmd-pb-${randomUUID()}`); yield* ensureDir(dir); return yield* scoped(function* () { yield* ensure(() => rm(dir, { recursive: true, force: true })); @@ -103,6 +104,9 @@ function* run( }); } +const OWNER = "packages/agent/tests/package-boundary.test.ts"; +const fileCase = fileJournalCases(OWNER, "xmd-pb-", "doc.md"); + const DOCUMENT = '\n\n\n'; describe("Tier PB — Core resolves no Agent package", () => { @@ -135,34 +139,45 @@ describe("Tier PB — Core resolves no Agent package", () => { } }); - it("PB4: a Core-only execution cannot resolve the Agent vocabulary", function* () { + const vocabulary = "PB4: a Core-only execution cannot resolve the Agent vocabulary"; + it(vocabulary, function* () { for (const [doc, name] of [ [DOCUMENT, "Session"], ['\n', "Prompt"], ] as const) { - const { output, result } = yield* run(doc, (docPath) => - execute({ path: docPath, stream: new InMemoryStream() }), + const dir = path.join(os.tmpdir(), `xmd-pb-${randomUUID()}`); + yield* captureTestJournal( + { owner: OWNER, name: vocabulary }, + path.join(dir, "doc.md"), + function* (stream) { + const { output, result } = yield* run(dir, doc, (docPath) => + execute({ path: docPath, stream }), + ); + expect(output).not.toContain("[hello]"); + expect(!result.ok && result.error.message).toContain(`Cannot resolve component: ${name}`); + }, ); - expect(output).not.toContain("[hello]"); - expect(!result.ok && result.error.message).toContain(`Cannot resolve component: ${name}`); } }); - it("PB5: the Agent package installed over Core answers the same document", function* () { - const { output, result } = yield* run(DOCUMENT, function* (docPath) { - yield* installAgentComponents({ - rootProvider: { - factory: echo, - options: { defaultAgent: "pb", permissionMode: "deny-all" }, - }, + fileCase( + "PB5: the Agent package installed over Core answers the same document", + function* (stream, dir) { + const { output, result } = yield* run(dir, DOCUMENT, function* (docPath) { + yield* installAgentComponents({ + rootProvider: { + factory: echo, + options: { defaultAgent: "pb", permissionMode: "deny-all" }, + }, + }); + return yield* executeInstalled({ path: docPath, stream }, [ + { components: agentIdentityComponents() }, + ]); }); - return yield* executeInstalled({ path: docPath, stream: new InMemoryStream() }, [ - { components: agentIdentityComponents() }, - ]); - }); - if (!result.ok) { - throw result.error; - } - expect(output).toContain("[hello]"); - }); + if (!result.ok) { + throw result.error; + } + expect(output).toContain("[hello]"); + }, + ); }); diff --git a/packages/test-agent/tests/cross-package-resolution.test.ts b/packages/test-agent/tests/cross-package-resolution.test.ts index ec3243bc3..6a5e8a988 100644 --- a/packages/test-agent/tests/cross-package-resolution.test.ts +++ b/packages/test-agent/tests/cross-package-resolution.test.ts @@ -1,3 +1,5 @@ +import { captureTestJournal } from "../../test-support/failure-journal.ts"; +import { workspaceJournalCases } from "../../test-support/journal-cases.ts"; /** * Tier XP — cross-package resolution (issue #202 acceptance). * @@ -24,7 +26,7 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { mkdtemp, realpath } from "node:fs/promises"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import type { InMemoryStream } from "@executablemd/durable-streams"; import { collect, Component, @@ -155,7 +157,7 @@ function* writeStandIns(workspace: string): Operation { } /** Execute a document invoking every registered name, and return its text. */ -function runDocument(workspace: string, order: Order): Operation { +function runDocument(workspace: string, order: Order, stream: InMemoryStream): Operation { return scoped(function* () { const path = join(workspace, "doc.md"); // Self-closing, so nothing is handed content to expand. @@ -163,7 +165,7 @@ function runDocument(workspace: string, order: Order): Operation { yield* useTempFileCompiler(); yield* installAll(order); const output = yield* collect( - yield* executeInstalled({ path, stream: new InMemoryStream(), includes: [workspace] }, [ + yield* executeInstalled({ path, stream, includes: [workspace] }, [ { components: agentIdentityComponents() }, ]), ); @@ -216,6 +218,9 @@ function describeOrigin(info: ComponentInfo): string { } } +const OWNER = "packages/test-agent/tests/cross-package-resolution.test.ts"; +const workspaceCase = workspaceJournalCases(OWNER, "doc.md", useWorkspace); + describe("Tier XP — cross-package resolution", () => { /** * The inventory below is what every other case iterates, so a name missing @@ -235,32 +240,40 @@ describe("Tier XP — cross-package resolution", () => { expect(installed).toEqual([...AGENT, ...TESTING, ...TEST_AGENT].sort()); }); - it("XP1: a repository component runs in place of every registered default", function* () { - const workspace = yield* useWorkspace(); - yield* writeStandIns(workspace); + workspaceCase( + "XP1: a repository component runs in place of every registered default", + function* (stream, workspace) { + yield* writeStandIns(workspace); - const output = yield* runDocument(workspace, "agent-first"); + const output = yield* runDocument(workspace, "agent-first", stream); - // Rendered output, not a resolver answer: each marker is evidence that the - // repository file is what executed for that name. - for (const name of REGISTERED) { - expect(output).toContain(marker(name)); - } - }); + // Rendered output, not a resolver answer: each marker is evidence that the + // repository file is what executed for that name. + for (const name of REGISTERED) { + expect(output).toContain(marker(name)); + } + }, + ); - it("XP2: which installer ran first changes nothing about what executed", function* () { - const workspace = yield* useWorkspace(); + const orderCase = "XP2: which installer ran first changes nothing about what executed"; + workspaceCase(orderCase, function* (stream, workspace) { yield* writeStandIns(workspace); - const first = yield* runDocument(workspace, "agent-first"); - const second = yield* runDocument(workspace, "test-agent-first"); + const first = yield* runDocument(workspace, "agent-first", stream); + yield* captureTestJournal( + { owner: OWNER, name: orderCase }, + join(workspace, "doc.md"), + function* (secondStream) { + const second = yield* runDocument(workspace, "test-agent-first", secondStream); - // Installation order is not a resolution mechanism, so the two runs produce - // the same document — not merely the same set of resolved origins. - expect(second).toBe(first); - for (const name of REGISTERED) { - expect(second).toContain(marker(name)); - } + // Installation order is not a resolution mechanism, so the two runs produce + // the same document — not merely the same set of resolved origins. + expect(second).toBe(first); + for (const name of REGISTERED) { + expect(second).toContain(marker(name)); + } + }, + ); }); it("XP3: each package's names carry that package's origin, and none is reserved", function* () { @@ -282,30 +295,32 @@ describe("Tier XP — cross-package resolution", () => { expect([...(yield* resolveAll("test-agent-first")).entries()]).toEqual([...resolved.entries()]); }); - it("XP4: a structural name still outranks all three installers", function* () { - const workspace = yield* useWorkspace(); - yield* writeTextFile(join(workspace, "Each.md"), "SHOULD NOT RENDER\n"); - const path = join(workspace, "doc.md"); - yield* writeTextFile(path, '[{n}]\n'); + workspaceCase( + "XP4: a structural name still outranks all three installers", + function* (stream, workspace) { + yield* writeTextFile(join(workspace, "Each.md"), "SHOULD NOT RENDER\n"); + const path = join(workspace, "doc.md"); + yield* writeTextFile(path, '[{n}]\n'); - const observed = yield* scoped(function* () { - yield* useTempFileCompiler(); - yield* installAll("test-agent-first"); - return { - info: yield* inspectComponent({ name: "Each", includes: [workspace] }), - output: String( - yield* collect( - yield* executeInstalled({ path, stream: new InMemoryStream(), includes: [workspace] }, [ - { components: agentIdentityComponents() }, - ]), + const observed = yield* scoped(function* () { + yield* useTempFileCompiler(); + yield* installAll("test-agent-first"); + return { + info: yield* inspectComponent({ name: "Each", includes: [workspace] }), + output: String( + yield* collect( + yield* executeInstalled({ path, stream, includes: [workspace] }, [ + { components: agentIdentityComponents() }, + ]), + ), ), - ), - }; - }); + }; + }); - expect(describeOrigin(observed.info)).toBe("structural:Each"); - // The construct ran, not the file named after it. - expect(observed.output).toContain("[1][2]"); - expect(observed.output).not.toContain("SHOULD NOT RENDER"); - }); + expect(describeOrigin(observed.info)).toBe("structural:Each"); + // The construct ran, not the file named after it. + expect(observed.output).toContain("[1][2]"); + expect(observed.output).not.toContain("SHOULD NOT RENDER"); + }, + ); }); From 20636df047e07c03a2dc78951b56a7f552f35c49 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:17:10 -0500 Subject: [PATCH 34/78] test: attribute guarded Git and Workflow host probes --- packages/cli/tests/testing-activation.test.ts | 113 ++++++++++-------- packages/git/tests/git-add.test.ts | 8 +- packages/git/tests/git-commit-read.test.ts | 52 ++++---- packages/git/tests/git-commit.test.ts | 8 +- packages/git/tests/git-switch.test.ts | 8 +- packages/git/tests/github-activation.test.ts | 40 ++++--- .../tests/github-workflow-activation.test.ts | 80 +++++++------ .../git/tests/run-composition-lazy.test.ts | 33 ++--- 8 files changed, 191 insertions(+), 151 deletions(-) diff --git a/packages/cli/tests/testing-activation.test.ts b/packages/cli/tests/testing-activation.test.ts index aecda746a..da5fd0dcd 100644 --- a/packages/cli/tests/testing-activation.test.ts +++ b/packages/cli/tests/testing-activation.test.ts @@ -14,7 +14,6 @@ import { expect } from "@executablemd/test-support/expect"; import { scoped } from "effection"; import type { Operation } from "effection"; import { createApi } from "@effectionx/context-api"; -import { InMemoryStream } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; import { inlineSource, registerComponents, useTempFileCompiler } from "@executablemd/core"; import type { Json } from "@executablemd/core"; @@ -23,6 +22,9 @@ import { retainedWorkflowInstallation } from "@executablemd/workflow"; import { GitQuery } from "@executablemd/git/api"; import { installTestingComponents } from "@executablemd/testing"; import type { TestResult } from "@executablemd/testing"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/cli/tests/testing-activation.test.ts"); const RUN = Object.freeze({ runId: "issue-523", @@ -52,62 +54,67 @@ function publicTestPolicy() { } describe("workflow installation and testing activation", () => { - it("refuses a the installation did not activate, before its body runs", function* () { - const sentinels: string[] = []; - const results: TestResult[] = []; - const stream = new InMemoryStream(); + journalCase( + "refuses a the installation did not activate, before its body runs", + "", + function* (stream) { + const sentinels: string[] = []; + const results: TestResult[] = []; - const outcome = yield* scoped(function* () { - yield* useTempFileCompiler(); - yield* useForbiddenGit(); - yield* registerComponents([ - { - name: "Sentinel", - origin: "issue-523", - props: { type: "object", properties: {}, additionalProperties: false }, - // deno-lint-ignore require-yield - *fn(): Operation { - sentinels.push("body"); - return ""; + const outcome = yield* scoped(function* () { + yield* useTempFileCompiler(); + yield* useForbiddenGit(); + yield* registerComponents([ + { + name: "Sentinel", + origin: "issue-523", + props: { type: "object", properties: {}, additionalProperties: false }, + // deno-lint-ignore require-yield + *fn(): Operation { + sentinels.push("body"); + return ""; + }, }, - }, - ]); - const policy = publicTestPolicy(); - yield* policy.around({ - *record([result], next) { - results.push(result); - yield* next(result); - }, - }); + ]); + const policy = publicTestPolicy(); + yield* policy.around({ + *record([result], next) { + results.push(result); + yield* next(result); + }, + }); - // The whole of the composition: components registered, testing mode on, - // and a trusted host installation that is not a testing session. - yield* installTestingComponents(); - yield* policy.around({ testing: () => true }); + // The whole of the composition: components registered, testing mode on, + // and a trusted host installation that is not a testing session. + yield* installTestingComponents(); + yield* policy.around({ testing: () => true }); - const execution = yield* executeInstalled( - { - ...inlineSource('\n'), - stream, - }, - [retainedWorkflowInstallation(RUN)], - ); - return yield* execution; - }); + const execution = yield* executeInstalled( + { + ...inlineSource('\n'), + stream, + }, + [retainedWorkflowInstallation(RUN)], + ); + return yield* execution; + }); - expect(sentinels).toEqual([]); - expect(outcome.ok).toBe(false); - if (!outcome.ok) { - expect(outcome.error.message).toContain("complete testing activation"); - } - expect(results).toEqual([]); + expect(sentinels).toEqual([]); + expect(outcome.ok).toBe(false); + if (!outcome.ok) { + expect(outcome.error.message).toContain("complete testing activation"); + } + expect(results).toEqual([]); - // The run itself was prepared and journaled; what it holds is the workflow's - // own record and no test result. - const events: DurableEvent[] = yield* stream.readAll(); - expect(events.length).toBeGreaterThan(0); - expect( - events.filter((event) => event.type === "yield" && event.description.type === "test_result"), - ).toEqual([]); - }); + // The run itself was prepared and journaled; what it holds is the workflow's + // own record and no test result. + const events: DurableEvent[] = yield* stream.readAll(); + expect(events.length).toBeGreaterThan(0); + expect( + events.filter( + (event) => event.type === "yield" && event.description.type === "test_result", + ), + ).toEqual([]); + }, + ); }); diff --git a/packages/git/tests/git-add.test.ts b/packages/git/tests/git-add.test.ts index ae56ac225..da3792b2a 100644 --- a/packages/git/tests/git-add.test.ts +++ b/packages/git/tests/git-add.test.ts @@ -14,7 +14,6 @@ import { expect } from "@executablemd/test-support/expect"; import { registerComponents } from "@executablemd/core"; import { collect, execute, inlineSource } from "@executablemd/core"; import type { ComponentRegistration } from "@executablemd/core"; -import { InMemoryStream } from "@executablemd/durable-streams"; import type { Json } from "@executablemd/durable-streams"; import { scoped, sleep, spawn, until, withResolvers } from "effection"; import { tmpdir } from "node:os"; @@ -64,6 +63,9 @@ import { subcommands, } from "./support/composition.ts"; import { gitPluginAdmissions } from "./support/composition.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/git/tests/git-add.test.ts"); /** * A tracked file at the root, one in a subdirectory, and one more of each. @@ -598,7 +600,7 @@ describe("workflow Git.Add selection", () => { }); }); - it("does not turn a missing provider into a refusal", function* () { + journalCase("does not turn a missing provider into a refusal", "", function* (stream) { const failure = yield* raised( scoped(function* () { yield* useCompositionComponents(); @@ -606,7 +608,7 @@ describe("workflow Git.Add selection", () => { return yield* collect( yield* execute({ ...inlineSource(``), - stream: new InMemoryStream(), + stream, }), ); }), diff --git a/packages/git/tests/git-commit-read.test.ts b/packages/git/tests/git-commit-read.test.ts index 2f5367a18..d9515d9c3 100644 --- a/packages/git/tests/git-commit-read.test.ts +++ b/packages/git/tests/git-commit-read.test.ts @@ -15,7 +15,6 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import type { Json } from "@executablemd/durable-streams"; -import { InMemoryStream } from "@executablemd/durable-streams"; import { scoped, until } from "effection"; import type { Operation } from "effection"; import { spawnSync } from "node:child_process"; @@ -36,6 +35,9 @@ import { denoCommitVerifier } from "../src/deno/run-composition/verification.ts" import type { CommitVerifier } from "../src/deno/run-composition/verification.ts"; import { capturingProbe } from "./support/observations.ts"; import { raised, runOrdinaryDocument, useManagedRoot } from "./support/run-composition.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/git/tests/git-commit-read.test.ts"); /** Whether this host can sign and verify the SSH fixture commits at all. */ const SSH_KEYGEN = spawnSync("ssh-keygen", ["-?"]).error === undefined; @@ -801,29 +803,33 @@ describe("GCR6 — the selected checkout answers, and nothing changes (A6)", () }, ); - it("refuses with the absent-provider error on a host that installs no reads", function* () { - const failure = yield* raised( - scoped(function* () { - yield* useCompositionComponents(); - yield* Repository.around( - { - // deno-lint-ignore require-yield - *ambient(): Operation { - return SUPPLIED_SELECTION; + journalCase( + "refuses with the absent-provider error on a host that installs no reads", + "", + function* (stream) { + const failure = yield* raised( + scoped(function* () { + yield* useCompositionComponents(); + yield* Repository.around( + { + // deno-lint-ignore require-yield + *ambient(): Operation { + return SUPPLIED_SELECTION; + }, }, - }, - { at: "min" }, - ); - return yield* collect( - yield* execute({ - ...inlineSource(`\n`), - stream: new InMemoryStream(), - }), - ); - }), - ); - expect(failure instanceof GitObservationProviderError).toBe(true); - }); + { at: "min" }, + ); + return yield* collect( + yield* execute({ + ...inlineSource(`\n`), + stream, + }), + ); + }), + ); + expect(failure instanceof GitObservationProviderError).toBe(true); + }, + ); }); describe("GCR7 — the syntax reference describes both forms (A8)", () => { diff --git a/packages/git/tests/git-commit.test.ts b/packages/git/tests/git-commit.test.ts index 59a82025a..93c35798f 100644 --- a/packages/git/tests/git-commit.test.ts +++ b/packages/git/tests/git-commit.test.ts @@ -12,7 +12,6 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { collect, execute, inlineSource, registerComponents } from "@executablemd/core"; import type { ComponentRegistration } from "@executablemd/core"; -import { InMemoryStream } from "@executablemd/durable-streams"; import type { Json } from "@executablemd/durable-streams"; import { scoped, sleep, spawn, suspend, until, withResolvers } from "effection"; import type { Operation } from "effection"; @@ -74,6 +73,9 @@ import { gitPluginAdmissions } from "./support/composition.ts"; import { dropRootClose } from "./support/replay.ts"; import type { RepositorySelection } from "@executablemd/git/api"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/git/tests/git-commit.test.ts"); /** One tracked file at the root and one in a subdirectory. */ const REMOTE = { commits: [ @@ -939,7 +941,7 @@ describe("workflow Git.Commit selection", () => { }); }); - it("does not turn a missing provider into a refusal", function* () { + journalCase("does not turn a missing provider into a refusal", "", function* (stream) { const failure = yield* raised( scoped(function* () { yield* useCompositionComponents(); @@ -947,7 +949,7 @@ describe("workflow Git.Commit selection", () => { return yield* collect( yield* execute({ ...inlineSource(``), - stream: new InMemoryStream(), + stream, }), ); }), diff --git a/packages/git/tests/git-switch.test.ts b/packages/git/tests/git-switch.test.ts index bcd58e10b..57a1abaa5 100644 --- a/packages/git/tests/git-switch.test.ts +++ b/packages/git/tests/git-switch.test.ts @@ -17,7 +17,6 @@ import { expect } from "@executablemd/test-support/expect"; import { content, registerComponents } from "@executablemd/core"; import type { ComponentRegistration } from "@executablemd/core"; import { collect, execute, inlineSource } from "@executablemd/core"; -import { InMemoryStream } from "@executablemd/durable-streams"; import type { Json } from "@executablemd/durable-streams"; import { scoped, until } from "effection"; import { readTextFile, writeTextFile } from "@effectionx/fs"; @@ -74,6 +73,9 @@ import { committedRoot, dropRootClose, latestRoot, publishedRoots } from "./supp import { filteredRepositoryIdentity } from "../src/composition/selection.ts"; import { type RepositorySelection } from "@executablemd/git/api"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/git/tests/git-switch.test.ts"); /** * Two branches whose content differs, plus one file that does not. * @@ -711,7 +713,7 @@ describe("workflow Git.Switch selection", () => { }); }); - it("does not turn a missing provider into a refusal", function* () { + journalCase("does not turn a missing provider into a refusal", "", function* (stream) { const failure = yield* raised( scoped(function* () { yield* useCompositionComponents(); @@ -719,7 +721,7 @@ describe("workflow Git.Switch selection", () => { return yield* collect( yield* execute({ ...inlineSource(``), - stream: new InMemoryStream(), + stream, }), ); }), diff --git a/packages/git/tests/github-activation.test.ts b/packages/git/tests/github-activation.test.ts index 6901bb359..9713c2a55 100644 --- a/packages/git/tests/github-activation.test.ts +++ b/packages/git/tests/github-activation.test.ts @@ -30,7 +30,7 @@ import { API } from "@executablemd/runtime"; import type { Operation } from "effection"; import { collect, inlineSource } from "@executablemd/core"; import { executeInstalled } from "@executablemd/core/host"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import type { InMemoryStream } from "@executablemd/durable-streams"; import { gitPlugin } from "../src/plugin.ts"; import { IssueApi } from "@executablemd/git/api"; import { GITHUB, useGitHubIssues } from "../src/deno/issue/github.ts"; @@ -44,6 +44,9 @@ import type { } from "../src/deno/composition/github.ts"; import { GITHUB_ISSUES_ENV } from "../src/deno/issue/configuration.ts"; import { fakeGitHubAccess, gitHubStore } from "./support/github.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/git/tests/github-activation.test.ts"); /** Where every step this suite watches records itself, in the order it happened. */ type Step = "configuration" | "source" | "open" | "credential" | "transport"; @@ -153,8 +156,7 @@ function reviewing(steps: Step[]): (endpoint?: string) => GitHubSource { } /** One document, executed with the bundled Plugin installed and nothing else. */ -function* document(source: string): Operation { - const stream = new InMemoryStream(); +function* document(stream: InMemoryStream, source: string): Operation { const install = gitPlugin.install; if (install === undefined) { throw new Error("the Git Plugin installed nothing"); @@ -189,21 +191,25 @@ describe("what installing the bundled GitHub adapter costs", () => { }); }); - it("reads no configuration for a document that writes no GitHub vocabulary", function* () { - const rendered = yield* scoped(function* () { - yield* refusing(); - yield* useGitHubIssues({ - host: () => ({ - endpoint: "https://api.github.test", - *open(): Operation { - throw new Error("a credential was obtained"); - }, - }), + journalCase( + "reads no configuration for a document that writes no GitHub vocabulary", + "", + function* (stream) { + const rendered = yield* scoped(function* () { + yield* refusing(); + yield* useGitHubIssues({ + host: () => ({ + endpoint: "https://api.github.test", + *open(): Operation { + throw new Error("a credential was obtained"); + }, + }), + }); + return yield* document(stream, "nothing here reaches a service\n"); }); - return yield* document("nothing here reaches a service\n"); - }); - expect(String(rendered)).toContain("nothing here reaches a service"); - }); + expect(String(rendered)).toContain("nothing here reaches a service"); + }, + ); it("reads no configuration for a destination another provider owns", function* () { // Target recognition comes first, and it reads nothing outside the diff --git a/packages/git/tests/github-workflow-activation.test.ts b/packages/git/tests/github-workflow-activation.test.ts index ed5196a42..ec47b2a2a 100644 --- a/packages/git/tests/github-workflow-activation.test.ts +++ b/packages/git/tests/github-workflow-activation.test.ts @@ -26,7 +26,7 @@ import { useRunComposition } from "../src/deno/run-composition/provider.ts"; import { gitPlugin } from "../src/plugin.ts"; import { collect, inlineSource } from "@executablemd/core"; import { executeInstalled } from "@executablemd/core/host"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import type { InMemoryStream } from "@executablemd/durable-streams"; import { useTempDirectory } from "@executablemd/test-support/temp"; import type { GitHubSource } from "../src/deno/composition/github.ts"; import { runWorkflowDocument } from "./support/composition.ts"; @@ -37,6 +37,9 @@ import { withExecutorRun, withRunHost, } from "../../workflow/tests/support/storage.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/git/tests/github-workflow-activation.test.ts"); /** A transport factory that refuses to be built at all. */ function forbidden(): GitHubSource { @@ -59,8 +62,7 @@ function* refusing(): Operation { } /** One document, executed with the bundled Plugin installed and nothing else. */ -function* document(source: string): Operation { - const stream = new InMemoryStream(); +function* document(stream: InMemoryStream, source: string): Operation { const install = gitPlugin.install; if (install === undefined) { throw new Error("the Git Plugin installed nothing"); @@ -74,41 +76,49 @@ function* document(source: string): Operation { } describe("the bundled profile, assembled", () => { - it("installs the whole ordinary-run profile without reading any of it", function* () { - // The real assembly this time, not the adapters alone: `useRunComposition` - // is what `xmd run` installs, and it brings the repository provider, the - // Git capability, both GitHub adapters and the retained lifecycles with it. - // Every outward boundary refuses, so installing any of them wrongly is a - // failure here rather than a count checked afterwards. - const rendered = yield* scoped(function* () { - yield* refusing(); - yield* useRunComposition({ - root: yield* useTempDirectory("xmd-zero-root"), - cwd: yield* useTempDirectory("xmd-zero-cwd"), - gitHubIssues: { host: forbidden }, - gitHubPullRequests: { host: forbidden }, + journalCase( + "installs the whole ordinary-run profile without reading any of it", + "", + function* (stream) { + // The real assembly this time, not the adapters alone: `useRunComposition` + // is what `xmd run` installs, and it brings the repository provider, the + // Git capability, both GitHub adapters and the retained lifecycles with it. + // Every outward boundary refuses, so installing any of them wrongly is a + // failure here rather than a count checked afterwards. + const rendered = yield* scoped(function* () { + yield* refusing(); + yield* useRunComposition({ + root: yield* useTempDirectory("xmd-zero-root"), + cwd: yield* useTempDirectory("xmd-zero-cwd"), + gitHubIssues: { host: forbidden }, + gitHubPullRequests: { host: forbidden }, + }); + return yield* document(stream, "a plain document that reaches nothing\n"); }); - return yield* document("a plain document that reaches nothing\n"); - }); - expect(String(rendered)).toContain("a plain document that reaches nothing"); - }); + expect(String(rendered)).toContain("a plain document that reaches nothing"); + }, + ); - it("does local Git work without reading any GitHub configuration", function* () { - // `` is Git's own and reaches no service. A profile that read GitHub - // configuration to do local work would be reading it for every run. - const rendered = yield* scoped(function* () { - yield* refusing(); - yield* useHostFiles(); - yield* useRunComposition({ - root: yield* useTempDirectory("xmd-zero-root"), - cwd: yield* useTempDirectory("xmd-zero"), - gitHubIssues: { host: forbidden }, - gitHubPullRequests: { host: forbidden }, + journalCase( + "does local Git work without reading any GitHub configuration", + "", + function* (stream) { + // `` is Git's own and reaches no service. A profile that read GitHub + // configuration to do local work would be reading it for every run. + const rendered = yield* scoped(function* () { + yield* refusing(); + yield* useHostFiles(); + yield* useRunComposition({ + root: yield* useTempDirectory("xmd-zero-root"), + cwd: yield* useTempDirectory("xmd-zero"), + gitHubIssues: { host: forbidden }, + gitHubPullRequests: { host: forbidden }, + }); + return yield* document(stream, 'local work only\n'); }); - return yield* document('local work only\n'); - }); - expect(String(rendered)).toContain("local work only"); - }); + expect(String(rendered)).toContain("local work only"); + }, + ); it("runs a version-2 source-bundle workflow outside Git without reaching GitHub", function* () { // The real lifecycle, not a test-shaped run: a source-bundle creation diff --git a/packages/git/tests/run-composition-lazy.test.ts b/packages/git/tests/run-composition-lazy.test.ts index 0f391f1ac..258e6617b 100644 --- a/packages/git/tests/run-composition-lazy.test.ts +++ b/packages/git/tests/run-composition-lazy.test.ts @@ -30,12 +30,15 @@ import { repositoryOperationsOver } from "../src/deno/repository-operations.ts"; import type { DenoRepositoryOperations } from "../deno.ts"; import type { HelperAssembly } from "../credential-helper.ts"; import { collect, execute, inlineSource } from "@executablemd/core"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import type { InMemoryStream } from "@executablemd/durable-streams"; import { useHostFiles } from "@executablemd/runtime"; import { useRunComposition } from "../src/deno/run-composition/provider.ts"; import { useCompositionComponents } from "../src/composition/installation.ts"; import { Repository } from "@executablemd/git/api"; import type { RepositoryHost, GitInvocation, GitOutcome } from "../src/deno/composition/host.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const journalCase = journalCases("packages/git/tests/run-composition-lazy.test.ts"); /** Every acquisition this provider can make, counted where it happens. */ interface Acquisitions { @@ -76,7 +79,7 @@ function counting(seen: Acquisitions, directory: string): RepositoryHost { } /** One document, run with the provider installed over a counting host. */ -function* run(source: string, seen: Acquisitions): Operation { +function* run(stream: InMemoryStream, source: string, seen: Acquisitions): Operation { const directory = yield* useTempDirectory("xmd-lazy"); const root = yield* useTempDirectory("xmd-lazy-root"); return String( @@ -95,9 +98,7 @@ function* run(source: string, seen: Acquisitions): Operation { return undefined; }, }); - return yield* collect( - yield* execute({ ...inlineSource(source), stream: new InMemoryStream() }), - ); + return yield* collect(yield* execute({ ...inlineSource(source), stream })); }), ); } @@ -113,17 +114,21 @@ describe("what the ordinary repository provider acquires, and when", () => { expect(seen).toEqual({ directories: 0, commands: [], identities: 0 }); }); - it("acquires nothing for a document that writes no repository component", function* () { - const seen = counters(); - const rendered = yield* run("a plain document\n", seen); - // The document really ran — an empty render would satisfy every count. - expect(rendered).toContain("a plain document"); - expect(seen).toEqual({ directories: 0, commands: [], identities: 0 }); - }); + journalCase( + "acquires nothing for a document that writes no repository component", + "", + function* (stream) { + const seen = counters(); + const rendered = yield* run(stream, "a plain document\n", seen); + // The document really ran — an empty render would satisfy every count. + expect(rendered).toContain("a plain document"); + expect(seen).toEqual({ directories: 0, commands: [], identities: 0 }); + }, + ); - it("acquires no repository capability for a bare ", function* () { + journalCase("acquires no repository capability for a bare ", "", function* (stream) { const seen = counters(); - const rendered = yield* run('local work only\n', seen); + const rendered = yield* run(stream, 'local work only\n', seen); expect(rendered).toContain("local work only"); // `` makes a directory. It selects no repository, runs no `git`, opens // no session and reads no identity. From 1dc1607fc8eb42e164c3e91c86a46ae9bcdff9a9 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:18:13 -0500 Subject: [PATCH 35/78] test: attribute guarded Plan and Upgrade documents --- .../cli/tests/plan-command-document.test.ts | 312 ++++++++++-------- .../tests/upgrade-command-document.test.ts | 246 ++++++++------ 2 files changed, 316 insertions(+), 242 deletions(-) diff --git a/packages/cli/tests/plan-command-document.test.ts b/packages/cli/tests/plan-command-document.test.ts index 17b8626b9..dc4c99a76 100644 --- a/packages/cli/tests/plan-command-document.test.ts +++ b/packages/cli/tests/plan-command-document.test.ts @@ -1,3 +1,4 @@ +import { journalCases } from "../../test-support/journal-cases.ts"; /** * The packaged plan command document, executed as itself. * @@ -175,7 +176,10 @@ interface RunOptions { symbols?: SyntaxSymbols; } -function* runDocument(options: RunOptions = {}): Operation { +function* runDocument( + options: RunOptions = {}, + stream = new InMemoryStream(), +): Operation { const source = yield* readPackagedDocument(PLAN_COMMAND_DOCUMENT); let value: Json | undefined; @@ -235,7 +239,7 @@ function* runDocument(options: RunOptions = {}): Operation { const execution = yield* executeInstalled( { ...retainedSource(PLAN_COMMAND_IDENTITY, source), - stream: new InMemoryStream(), + stream, includes: [], secretDetection: true, props: { @@ -340,36 +344,42 @@ function unattributed(chunks: readonly string[]): string[] { return kept; } -describe("the packaged plan command document", () => { - it("C2: returns the approved candidate's exact bytes and never reaches exhaustion", function* () { - const run = yield* useWorkingDirectory(function* () { - return yield* runDocument(); - }); - - // The root this document ran under is the internal one the host declares: - // no path selects it, and a position naming it says the source is the - // CLI's own. - expect(PLAN_COMMAND_IDENTITY).toBe(""); - - // Approving the first valid candidate is one turn and one question. A - // repair or revision turn here would mean the loops ran when they had - // nothing to fix. - expect(run.prompts).toHaveLength(1); - expect(run.reviews).toHaveLength(1); +const journalCase = journalCases("packages/cli/tests/plan-command-document.test.ts"); - // Both gates inside the Component saw the Agent's complete close value, - // unaltered: the draft check while the conversation was still standing, and - // the admission after the whole Plan writer frame had gone. They are the same - // question asked twice, of the same exact bytes. - expect(run.validated).toEqual([CANDIDATE, CANDIDATE]); +describe("the packaged plan command document", () => { + journalCase( + "C2: returns the approved candidate's exact bytes and never reaches exhaustion", + PLAN_COMMAND_IDENTITY, + function* (stream) { + const run = yield* useWorkingDirectory(function* () { + return yield* runDocument(undefined, stream); + }); - // The document settled with a value rather than an authored failure. Before - // the control-flow correction this was the ten-draft exhaustion message: a - // `` selects a value but does not end the body, so the unconditional - // `` after the Session ran and won over every approval. - expect(run.failure).toBe(undefined); - expect(run.value).toBe(CANDIDATE); - }); + // The root this document ran under is the internal one the host declares: + // no path selects it, and a position naming it says the source is the + // CLI's own. + expect(PLAN_COMMAND_IDENTITY).toBe(""); + + // Approving the first valid candidate is one turn and one question. A + // repair or revision turn here would mean the loops ran when they had + // nothing to fix. + expect(run.prompts).toHaveLength(1); + expect(run.reviews).toHaveLength(1); + + // Both gates inside the Component saw the Agent's complete close value, + // unaltered: the draft check while the conversation was still standing, and + // the admission after the whole Plan writer frame had gone. They are the same + // question asked twice, of the same exact bytes. + expect(run.validated).toEqual([CANDIDATE, CANDIDATE]); + + // The document settled with a value rather than an authored failure. Before + // the control-flow correction this was the ten-draft exhaustion message: a + // `` selects a value but does not end the body, so the unconditional + // `` after the Session ran and won over every approval. + expect(run.failure).toBe(undefined); + expect(run.value).toBe(CANDIDATE); + }, + ); /** * The review this document asks has to be servable as a browser form, which @@ -384,38 +394,46 @@ describe("the packaged plan command document", () => { * `xmd plan` completed its turn and then ended at the review with * ` schema could not be compiled for the browser`. */ - it("C9: every conditional branch of the review schema declares its own type", function* () { - const run = yield* useWorkingDirectory(function* () { - return yield* runDocument(); - }); - - const schema = Object(run.reviews[0]?.schema); - expect(Reflect.get(Object(Reflect.get(schema, "if")), "type")).toBe("object"); - expect(Reflect.get(Object(Reflect.get(schema, "then")), "type")).toBe("object"); - }); + journalCase( + "C9: every conditional branch of the review schema declares its own type", + PLAN_COMMAND_IDENTITY, + function* (stream) { + const run = yield* useWorkingDirectory(function* () { + return yield* runDocument(undefined, stream); + }); - it("PO1: every phase precedes the work it announces, and arrives while it runs", function* () { - const run = yield* useWorkingDirectory(function* () { - return yield* runDocument(); - }); + const schema = Object(run.reviews[0]?.schema); + expect(Reflect.get(Object(Reflect.get(schema, "if")), "type")).toBe("object"); + expect(Reflect.get(Object(Reflect.get(schema, "then")), "type")).toBe("object"); + }, + ); - // Each phase stands before the operation it describes. `catalog` is the - // marker the harness records where `` builds the vocabulary, so - // Preparing being ahead of it is the whole claim: before this was moved - // behind ``, no authored phase could precede that work at all. - expect(timeline(run.events)).toEqual([ - "phase: Preparing the Plan", - "catalog", - "phase: Drafting the Plan", - "phase: Checking the draft", - "phase: Waiting for your review", - "phase: Finalizing the Plan", - ]); + journalCase( + "PO1: every phase precedes the work it announces, and arrives while it runs", + PLAN_COMMAND_IDENTITY, + function* (stream) { + const run = yield* useWorkingDirectory(function* () { + return yield* runDocument(undefined, stream); + }); - // And the adapter contributed nothing of its own: every non-blank line in - // the transcript belongs to a phase this document authored. - expect(unattributed(run.progress)).toEqual([]); - }); + // Each phase stands before the operation it describes. `catalog` is the + // marker the harness records where `` builds the vocabulary, so + // Preparing being ahead of it is the whole claim: before this was moved + // behind ``, no authored phase could precede that work at all. + expect(timeline(run.events)).toEqual([ + "phase: Preparing the Plan", + "catalog", + "phase: Drafting the Plan", + "phase: Checking the draft", + "phase: Waiting for your review", + "phase: Finalizing the Plan", + ]); + + // And the adapter contributed nothing of its own: every non-blank line in + // the transcript belongs to a phase this document authored. + expect(unattributed(run.progress)).toEqual([]); + }, + ); it("PO1: an early phase reaches the operator while the turn is still blocked", function* () { // The negative control for buffering. A turn that never settles holds the @@ -712,24 +730,28 @@ describe("the packaged plan command document", () => { expect(loudText).not.toContain(REQUEST); }); - it("PO15: the packaged adapter builds the catalog once, and says nothing itself", function* () { - const run = yield* useWorkingDirectory(function* () { - return yield* runDocument(); - }); + journalCase( + "PO15: the packaged adapter builds the catalog once, and says nothing itself", + PLAN_COMMAND_IDENTITY, + function* (stream) { + const run = yield* useWorkingDirectory(function* () { + return yield* runDocument(undefined, stream); + }); - expect(run.events.filter((event) => event === "catalog")).toHaveLength(1); - // The adapter's own body is projection and return. Its former explanatory - // prose would arrive here the moment the transcript is drained. - const source = yield* readPackagedDocument(PLAN_COMMAND_DOCUMENT); - const body = source.slice(source.lastIndexOf("---\n") + 4); - expect( - body - .trim() - .split("\n") - .filter((line) => !line.startsWith("<")), - ).toEqual([]); - expect(unattributed(run.progress)).toEqual([]); - }); + expect(run.events.filter((event) => event === "catalog")).toHaveLength(1); + // The adapter's own body is projection and return. Its former explanatory + // prose would arrive here the moment the transcript is drained. + const source = yield* readPackagedDocument(PLAN_COMMAND_DOCUMENT); + const body = source.slice(source.lastIndexOf("---\n") + 4); + expect( + body + .trim() + .split("\n") + .filter((line) => !line.startsWith("<")), + ).toEqual([]); + expect(unattributed(run.progress)).toEqual([]); + }, + ); }); /** @@ -1014,62 +1036,83 @@ describe("Tier PI — read-only information requests", () => { expect(run.reviews).toHaveLength(2); }); - it("PI1: named documentation comes back, then an ordinary Plan", function* () { - const run = yield* runDocument({ - // Two of the three names this case's vocabulary has, asked for together. - // The third is the control: a selection that returned it would be a - // catalog injection wearing a selection's clothes. - turns: [{ reply: '\n' }, { reply: CANDIDATE }], - symbols: SELECTABLE, - }); + journalCase( + "PI1: named documentation comes back, then an ordinary Plan", + PLAN_COMMAND_IDENTITY, + function* (stream) { + const run = yield* runDocument( + { + // Two of the three names this case's vocabulary has, asked for together. + // The third is the control: a selection that returned it would be a + // catalog injection wearing a selection's clothes. + turns: [{ reply: '\n' }, { reply: CANDIDATE }], + symbols: SELECTABLE, + }, + stream, + ); - expect(run.failure).toBe(undefined); - const asked = run.prompts[0] ?? ""; - const followUp = run.prompts[1] ?? ""; - // Both selected entries' documentation came back — including the paired - // form `` also has, which reading about does not confer. - expect(followUp).toContain("File"); - expect(followUp).toContain("Elicit"); - expect(followUp).toContain("paired"); - // And it is a *selection*: the unnamed third entry is not in it, though the - // drafting prompt that carried the whole vocabulary did name it. - expect(asked).toContain("Loop"); - expect(followUp).not.toContain("Loop"); - // The turn after the findings produced a draft that reached review. - expect(run.reviews).toHaveLength(1); - }); + expect(run.failure).toBe(undefined); + const asked = run.prompts[0] ?? ""; + const followUp = run.prompts[1] ?? ""; + // Both selected entries' documentation came back — including the paired + // form `` also has, which reading about does not confer. + expect(followUp).toContain("File"); + expect(followUp).toContain("Elicit"); + expect(followUp).toContain("paired"); + // And it is a *selection*: the unnamed third entry is not in it, though the + // drafting prompt that carried the whole vocabulary did name it. + expect(asked).toContain("Loop"); + expect(followUp).not.toContain("Loop"); + // The turn after the findings produced a draft that reached review. + expect(run.reviews).toHaveLength(1); + }, + ); - it("PI10: an unknown documented name is one retry, not a stopped invocation", function* () { - const run = yield* runDocument({ - turns: [{ reply: '\n' }, { reply: CANDIDATE }], - }); + journalCase( + "PI10: an unknown documented name is one retry, not a stopped invocation", + PLAN_COMMAND_IDENTITY, + function* (stream) { + const run = yield* runDocument( + { + turns: [{ reply: '\n' }, { reply: CANDIDATE }], + }, + stream, + ); - // Recoverable: the workflow asked again rather than ending, and the reason - // quotes only the name the candidate itself wrote. - expect(run.failure).toBe(undefined); - const followUp = run.prompts[1] ?? ""; - expect(followUp).toContain("That request was refused"); - expect(followUp).toContain("NoSuchComponent"); - expect(run.reviews).toHaveLength(1); - }); + // Recoverable: the workflow asked again rather than ending, and the reason + // quotes only the name the candidate itself wrote. + expect(run.failure).toBe(undefined); + const followUp = run.prompts[1] ?? ""; + expect(followUp).toContain("That request was refused"); + expect(followUp).toContain("NoSuchComponent"); + expect(run.reviews).toHaveLength(1); + }, + ); - it("PI2: an empty match renders as an empty array", function* () { - const files = recordedFiles({ "notes.md": "the retained note\n" }); - const run = yield* runDocument({ - turns: [ - { reply: '\n\n' }, - { reply: CANDIDATE }, - ], - generated: { File: ["self-closing"], Glob: ["self-closing"], Syntax: ["self-closing"] }, - files, - }); + journalCase( + "PI2: an empty match renders as an empty array", + PLAN_COMMAND_IDENTITY, + function* (stream) { + const files = recordedFiles({ "notes.md": "the retained note\n" }); + const run = yield* runDocument( + { + turns: [ + { reply: '\n\n' }, + { reply: CANDIDATE }, + ], + generated: { File: ["self-closing"], Glob: ["self-closing"], Syntax: ["self-closing"] }, + files, + }, + stream, + ); - expect(run.failure).toBe(undefined); - // The search ran and found nothing, and nothing is a result rather than a - // failure: the next turn is handed `[]`. - expect(files.performed).toEqual(["glob absent.md"]); - expect(run.prompts[1] ?? "").toContain("[]"); - }); + expect(run.failure).toBe(undefined); + // The search ran and found nothing, and nothing is a result rather than a + // failure: the next turn is handed `[]`. + expect(files.performed).toEqual(["glob absent.md"]); + expect(run.prompts[1] ?? "").toContain("[]"); + }, + ); it("PI4: a prohibited operation anywhere in the request refuses before any read", function* () { const files = recordedFiles({ "notes.md": "the retained note\n" }); @@ -1314,13 +1357,16 @@ describe("Tier PI — read-only information requests", () => { expect(run.reviews).toHaveLength(1); }); - it("PI3: a titled draft is never evaluated", function* () { + journalCase("PI3: a titled draft is never evaluated", PLAN_COMMAND_IDENTITY, function* (stream) { const files = recordedFiles({ "notes.md": "the retained note\n" }); - const run = yield* runDocument({ - turns: [{ reply: CANDIDATE }], - generated: { File: ["self-closing"], Glob: ["self-closing"], Syntax: ["self-closing"] }, - files, - }); + const run = yield* runDocument( + { + turns: [{ reply: CANDIDATE }], + generated: { File: ["self-closing"], Glob: ["self-closing"], Syntax: ["self-closing"] }, + files, + }, + stream, + ); expect(run.failure).toBe(undefined); // One turn, no evaluation, no information phase at all. diff --git a/packages/cli/tests/upgrade-command-document.test.ts b/packages/cli/tests/upgrade-command-document.test.ts index 9dcd18ff4..4f6d4e174 100644 --- a/packages/cli/tests/upgrade-command-document.test.ts +++ b/packages/cli/tests/upgrade-command-document.test.ts @@ -1,3 +1,5 @@ +import { journalCases } from "../../test-support/journal-cases.ts"; +import { UPGRADE_COMMAND_IDENTITY } from "../src/upgrade.ts"; /** * Tier UG — the packaged upgrade command document, executed as itself. * @@ -262,7 +264,7 @@ function* refuseHostCapabilities(): Operation { }); } -function* upgrade(scenario: Scenario): Operation { +function* upgrade(scenario: Scenario, stream = new InMemoryStream()): Operation { const run: Run = { releaseReads: [], downloads: [], @@ -308,7 +310,7 @@ function* upgrade(scenario: Scenario): Operation { allowPrerelease: scenario.allowPrerelease === true, }, assembly, - stream: new InMemoryStream(), + stream, // deno-lint-ignore require-yield *consume(chunk) { chunks.push(chunk); @@ -348,103 +350,121 @@ function transcript(run: Run): string[] { .filter((line) => line.length > 0); } +const journalCase = journalCases("packages/cli/tests/upgrade-command-document.test.ts"); + describe("Tier UG — the packaged upgrade command document", () => { beforeAll(() => useTempFileCompiler()); - it("UG1: an authorized install renders its milestones in source order", function* () { - const run = yield* upgrade({}); - - // The draft above it and the prerelease above that are both skipped, and - // the choice was made from the facts rather than by the host. - expect(run.releaseReads).toEqual([null]); - expect(run.downloads).toEqual(["admitted-2"]); - // Each phase received only what the previous one handed back. - expect(run.verifies).toEqual(["candidate-of-admitted-2"]); - expect(run.replacements).toEqual(["candidate-of-admitted-2"]); - expect(run.compiles).toBeGreaterThan(0); - expect(run.failure).toBe(undefined); - - // The approved transcript, in order: an opening, the selection, then one - // milestone per completed phase. This is the whole terminal experience — - // there is no separate summary. - expect(transcript(run)).toEqual([ - "# Upgrade XMD", - "Installs the latest published stable version of XMD. Verifies the release before", - "replacing the standalone binary that ran this command.", - "## Select a release", - "Checks that the installed XMD binary can be replaced atomically and takes its", - "installation lock without waiting. Reads release information from", - "`taras/executable.md`. Ignores drafts and releases with invalid tags.", - "## Install selected release", - "The selected release passed the comparison and consent checks.", - "Selected release: v0.11.0 (newer than installed version 0.10.2)", - "Downloads the checksum file and target binary from the selected GitHub release.", - "Stages the binary beside the installed one without making it executable.", - `Downloaded binary: xmd-${TARGET}`, - "Verifies the binary against its published SHA-256 checksum. Makes it executable", - "only after the checksum passes, then checks that it reports the selected", - "version.", - "Verified: SHA-256 checksum and version 0.11.0", - "Atomically replaces the installed binary with the verified binary. Until", - "replacement succeeds, the installed binary remains unchanged.", - "Installed xmd 0.11.0 (replaced 0.10.2).", - `Binary: ${EXECUTABLE}`, - "Release notes: https://github.com/taras/executable.md/releases/tag/v0.11.0", - ]); - }); - - it("UG2: an exact tag names itself in the opening", function* () { - const run = yield* upgrade({ tag: "v0.11.0" }); - - expect(transcript(run).slice(0, 3)).toEqual([ - "# Upgrade XMD", - "Installs XMD release v0.11.0. Verifies the release before replacing", - "the standalone binary that ran this command.", - ]); - }); - - it("UG3: --status reports the comparison and reaches no install phase", function* () { - const run = yield* upgrade({ status: true }); - - expect({ - downloads: run.downloads, - verifies: run.verifies, - replacements: run.replacements, - }).toEqual({ downloads: [], verifies: [], replacements: [] }); - expect(transcript(run)).toEqual([ - "# Upgrade XMD", - "Compares the installed XMD version with the selected release without downloading", - "a binary or changing the installation.", - "## Select a release", - "Reads release information from `taras/executable.md`. Ignores drafts and", - "releases with invalid tags.", - "## Release status", - "The installed and selected versions were compared using semantic version", - "precedence.", - "Installed version: 0.10.2", - "Selected release: v0.11.0 (newer)", - "Release notes: https://github.com/taras/executable.md/releases/tag/v0.11.0", - "No files were changed.", - ]); - // Status says nothing about locking, because status takes no lock. - expect(run.output).not.toContain("installation lock"); - }); + journalCase( + "UG1: an authorized install renders its milestones in source order", + UPGRADE_COMMAND_IDENTITY, + function* (stream) { + const run = yield* upgrade({}, stream); + + // The draft above it and the prerelease above that are both skipped, and + // the choice was made from the facts rather than by the host. + expect(run.releaseReads).toEqual([null]); + expect(run.downloads).toEqual(["admitted-2"]); + // Each phase received only what the previous one handed back. + expect(run.verifies).toEqual(["candidate-of-admitted-2"]); + expect(run.replacements).toEqual(["candidate-of-admitted-2"]); + expect(run.compiles).toBeGreaterThan(0); + expect(run.failure).toBe(undefined); + + // The approved transcript, in order: an opening, the selection, then one + // milestone per completed phase. This is the whole terminal experience — + // there is no separate summary. + expect(transcript(run)).toEqual([ + "# Upgrade XMD", + "Installs the latest published stable version of XMD. Verifies the release before", + "replacing the standalone binary that ran this command.", + "## Select a release", + "Checks that the installed XMD binary can be replaced atomically and takes its", + "installation lock without waiting. Reads release information from", + "`taras/executable.md`. Ignores drafts and releases with invalid tags.", + "## Install selected release", + "The selected release passed the comparison and consent checks.", + "Selected release: v0.11.0 (newer than installed version 0.10.2)", + "Downloads the checksum file and target binary from the selected GitHub release.", + "Stages the binary beside the installed one without making it executable.", + `Downloaded binary: xmd-${TARGET}`, + "Verifies the binary against its published SHA-256 checksum. Makes it executable", + "only after the checksum passes, then checks that it reports the selected", + "version.", + "Verified: SHA-256 checksum and version 0.11.0", + "Atomically replaces the installed binary with the verified binary. Until", + "replacement succeeds, the installed binary remains unchanged.", + "Installed xmd 0.11.0 (replaced 0.10.2).", + `Binary: ${EXECUTABLE}`, + "Release notes: https://github.com/taras/executable.md/releases/tag/v0.11.0", + ]); + }, + ); + + journalCase( + "UG2: an exact tag names itself in the opening", + UPGRADE_COMMAND_IDENTITY, + function* (stream) { + const run = yield* upgrade({ tag: "v0.11.0" }, stream); + + expect(transcript(run).slice(0, 3)).toEqual([ + "# Upgrade XMD", + "Installs XMD release v0.11.0. Verifies the release before replacing", + "the standalone binary that ran this command.", + ]); + }, + ); - it("UG4: an already-installed selection downloads nothing and says so", function* () { - const run = yield* upgrade({ tag: "v0.10.2" }); + journalCase( + "UG3: --status reports the comparison and reaches no install phase", + UPGRADE_COMMAND_IDENTITY, + function* (stream) { + const run = yield* upgrade({ status: true }, stream); - expect(run.downloads).toEqual([]); - expect(run.failure).toBe(undefined); - expect(transcript(run).slice(-7)).toEqual([ - "## Installing existing version", - "The selected release was compared with the installed version. They are the same,", - "so no download or replacement was needed.", - "xmd 0.10.2 is already installed.", - `Binary: ${EXECUTABLE}`, - "Release notes: https://github.com/taras/executable.md/releases/tag/v0.10.2", - "No download or replacement was needed.", - ]); - }); + expect({ + downloads: run.downloads, + verifies: run.verifies, + replacements: run.replacements, + }).toEqual({ downloads: [], verifies: [], replacements: [] }); + expect(transcript(run)).toEqual([ + "# Upgrade XMD", + "Compares the installed XMD version with the selected release without downloading", + "a binary or changing the installation.", + "## Select a release", + "Reads release information from `taras/executable.md`. Ignores drafts and", + "releases with invalid tags.", + "## Release status", + "The installed and selected versions were compared using semantic version", + "precedence.", + "Installed version: 0.10.2", + "Selected release: v0.11.0 (newer)", + "Release notes: https://github.com/taras/executable.md/releases/tag/v0.11.0", + "No files were changed.", + ]); + // Status says nothing about locking, because status takes no lock. + expect(run.output).not.toContain("installation lock"); + }, + ); + + journalCase( + "UG4: an already-installed selection downloads nothing and says so", + UPGRADE_COMMAND_IDENTITY, + function* (stream) { + const run = yield* upgrade({ tag: "v0.10.2" }, stream); + + expect(run.downloads).toEqual([]); + expect(run.failure).toBe(undefined); + expect(transcript(run).slice(-7)).toEqual([ + "## Installing existing version", + "The selected release was compared with the installed version. They are the same,", + "so no download or replacement was needed.", + "xmd 0.10.2 is already installed.", + `Binary: ${EXECUTABLE}`, + "Release notes: https://github.com/taras/executable.md/releases/tag/v0.10.2", + "No download or replacement was needed.", + ]); + }, + ); it("UG5: an untaken branch contributes no prose at all", function* () { // The defect this catches is reference documentation leaking: every branch @@ -698,15 +718,19 @@ describe("Tier UG — the packaged upgrade command document", () => { } }); - it("UG16: a compiled binary the release does not target refuses too", function* () { - const run = yield* upgrade({ target: null }); + journalCase( + "UG16: a compiled binary the release does not target refuses too", + UPGRADE_COMMAND_IDENTITY, + function* (stream) { + const run = yield* upgrade({ target: null }, stream); - expect(run.releaseReads).toEqual([]); - expect(run.compiles).toBe(0); - expect(run.failure).toContain( - "No xmd release is published for darwin/arm64. Build xmd from a checkout for this platform,", - ); - }); + expect(run.releaseReads).toEqual([]); + expect(run.compiles).toBe(0); + expect(run.failure).toContain( + "No xmd release is published for darwin/arm64. Build xmd from a checkout for this platform,", + ); + }, + ); it("UG17: every release-read failure code reaches its own answer", function* () { const expected: [string, string][] = [ @@ -879,14 +903,18 @@ describe("Tier UG — the packaged upgrade command document", () => { } }); - it("UG21: a running binary that reports no release version is refused", function* () { - const run = yield* upgrade({ currentVersion: "0.10.2-dirty+local" }); + journalCase( + "UG21: a running binary that reports no release version is refused", + UPGRADE_COMMAND_IDENTITY, + function* (stream) { + const run = yield* upgrade({ currentVersion: "0.10.2-dirty+local" }, stream); - expect(run.releaseReads).toEqual([]); - expect(run.failure).toContain( - "The installed binary reports version 0.10.2-dirty+local, which is not a valid release version.", - ); - }); + expect(run.releaseReads).toEqual([]); + expect(run.failure).toContain( + "The installed binary reports version 0.10.2-dirty+local, which is not a valid release version.", + ); + }, + ); it("UG22: a published release whose own tag is malformed is never selected", function* () { const implicit = yield* upgrade({ releases: [{ tag: "release-2" }, { tag: "v0.11.0" }] }); From c84628f71c10fe531b08df0e4af3bd436c53dae1 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:19:16 -0500 Subject: [PATCH 36/78] test: attribute fresh REPL source ownership runs --- packages/cli/tests/repl-model.test.ts | 250 ++++++++++++++------------ 1 file changed, 135 insertions(+), 115 deletions(-) diff --git a/packages/cli/tests/repl-model.test.ts b/packages/cli/tests/repl-model.test.ts index ab73ba344..860b2ca0e 100644 --- a/packages/cli/tests/repl-model.test.ts +++ b/packages/cli/tests/repl-model.test.ts @@ -19,6 +19,7 @@ import { * binding in a scope that never published it. */ +import { journalCases } from "../../test-support/journal-cases.ts"; import { captureTestJournal } from "../../test-support/failure-journal.ts"; import { beforeAll, describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; @@ -1480,90 +1481,105 @@ describe("REPL model: which call of a repeated source owns its work", () => { }); }); +const SOURCE_OWNER = "packages/cli/tests/repl-model.test.ts"; +const sourceCase = journalCases(SOURCE_OWNER); + describe("REPL source ownership by import coordinate (#976)", () => { beforeAll(() => useTempFileCompiler()); - it("SO1: sequential nested calls keep their own answers at every prefix and after serialization", function* () { - const run = yield* ownerRun(); - expect(run.output.trim()).toBe("first/second"); - for (let end = 1; end <= run.events.length; end++) { - const events = run.events.slice(0, end); - const model = projected(events); - expect(projected(copied(events))).toEqual(model); - const wrappers = only(model)?.scopes ?? []; - for (const [index, wrapper] of wrappers.entries()) { - const leaf = wrapper.scopes[0]; - expect(leaf?.name ?? "OwnerLeaf").toBe("OwnerLeaf"); - for (const question of leaf?.elicitations ?? []) { - expect(question).toMatchObject({ answer: index === 0 ? "first" : "second" }); + sourceCase( + "SO1: sequential nested calls keep their own answers at every prefix and after serialization", + "", + function* (stream) { + const run = yield* ownerRun(undefined, stream); + expect(run.output.trim()).toBe("first/second"); + for (let end = 1; end <= run.events.length; end++) { + const events = run.events.slice(0, end); + const model = projected(events); + expect(projected(copied(events))).toEqual(model); + const wrappers = only(model)?.scopes ?? []; + for (const [index, wrapper] of wrappers.entries()) { + const leaf = wrapper.scopes[0]; + expect(leaf?.name ?? "OwnerLeaf").toBe("OwnerLeaf"); + for (const question of leaf?.elicitations ?? []) { + expect(question).toMatchObject({ answer: index === 0 ? "first" : "second" }); + } } } - } - const leafImports = run.events.filter( - (event) => event.type === "yield" && event.description.name === "OwnerLeaf", - ); - expect( - leafImports.map((event) => - event.type === "yield" ? event.description[OWNER_FIELD] : undefined, - ), - ).toEqual([ - { coroutineId: "root", index: 1 }, - { coroutineId: "root", index: 5 }, - ]); - const entry = only(projected(run.events)); - expect(entry?.scopes.map((wrapper) => wrapper.scopes.map((leaf) => leaf.name))).toEqual([ - ["OwnerLeaf"], - ["OwnerLeaf"], - ]); - expect(entry?.bindings).toEqual([ - { name: "first", value: "first" }, - { name: "second", value: "second" }, - ]); - }); + const leafImports = run.events.filter( + (event) => event.type === "yield" && event.description.name === "OwnerLeaf", + ); + expect( + leafImports.map((event) => + event.type === "yield" ? event.description[OWNER_FIELD] : undefined, + ), + ).toEqual([ + { coroutineId: "root", index: 1 }, + { coroutineId: "root", index: 5 }, + ]); + const entry = only(projected(run.events)); + expect(entry?.scopes.map((wrapper) => wrapper.scopes.map((leaf) => leaf.name))).toEqual([ + ["OwnerLeaf"], + ["OwnerLeaf"], + ]); + expect(entry?.bindings).toEqual([ + { name: "first", value: "first" }, + { name: "second", value: "second" }, + ]); + }, + ); - it("SO2: repeated loop sites and caller Content keep their lexical source owner", function* () { - const source = - '\n'; - const run = yield* ownerRun(source); - const entry = only(projected(run.events)); - expect(entry?.scopes.map((scope) => scope.name)).toEqual([ - "OwnerWrapper", - "OwnerWrapper", - "OwnerContent", - "OwnerWrapper", - ]); - expect(entry?.scopes[2].scopes).toEqual([]); - expect( - entry?.scopes - .filter((scope) => scope.name === "OwnerWrapper") - .map((scope) => scope.scopes[0]?.elicitations[0]), - ).toMatchObject([{ answer: "same" }, { answer: "same" }, { answer: "caller" }]); - const wrappers = run.events.filter( - (event) => event.type === "yield" && event.description.name === "OwnerWrapper", - ); - expect(wrappers).toHaveLength(3); - const yields = run.events.filter((event) => event.type === "yield"); - const wrapperCoordinates = yields.flatMap((event, index) => - event.description.name === "OwnerWrapper" ? [{ coroutineId: event.coroutineId, index }] : [], - ); - const leafOwners = yields - .filter((event) => event.description.name === "OwnerLeaf") - .map((event) => event.description[OWNER_FIELD]); - expect(leafOwners).toEqual(wrapperCoordinates); - expect( - wrappers[0].type === "yield" && wrappers[0].description["executablemd.source-position"], - ).toEqual( - wrappers[1].type === "yield" && wrappers[1].description["executablemd.source-position"], - ); + sourceCase( + "SO2: repeated loop sites and caller Content keep their lexical source owner", + "", + function* (stream) { + const source = + '\n'; + const run = yield* ownerRun(source, stream); + const entry = only(projected(run.events)); + expect(entry?.scopes.map((scope) => scope.name)).toEqual([ + "OwnerWrapper", + "OwnerWrapper", + "OwnerContent", + "OwnerWrapper", + ]); + expect(entry?.scopes[2].scopes).toEqual([]); + expect( + entry?.scopes + .filter((scope) => scope.name === "OwnerWrapper") + .map((scope) => scope.scopes[0]?.elicitations[0]), + ).toMatchObject([{ answer: "same" }, { answer: "same" }, { answer: "caller" }]); + const wrappers = run.events.filter( + (event) => event.type === "yield" && event.description.name === "OwnerWrapper", + ); + expect(wrappers).toHaveLength(3); + const yields = run.events.filter((event) => event.type === "yield"); + const wrapperCoordinates = yields.flatMap((event, index) => + event.description.name === "OwnerWrapper" + ? [{ coroutineId: event.coroutineId, index }] + : [], + ); + const leafOwners = yields + .filter((event) => event.description.name === "OwnerLeaf") + .map((event) => event.description[OWNER_FIELD]); + expect(leafOwners).toEqual(wrapperCoordinates); + expect( + wrappers[0].type === "yield" && wrappers[0].description["executablemd.source-position"], + ).toEqual( + wrappers[1].type === "yield" && wrappers[1].description["executablemd.source-position"], + ); - for (const event of wrappers) { - if (event.type === "yield") { - expect(event.description[OWNER_FIELD]).toEqual({ coroutineId: "root", index: 0 }); + for (const event of wrappers) { + if (event.type === "yield") { + expect(event.description[OWNER_FIELD]).toEqual({ coroutineId: "root", index: 0 }); + } } - } - }); + }, + ); - it("SO7: ordinary middleware copies preserve evaluated blocks' source ownership", function* () { + const copiedSource = + "SO7: ordinary middleware copies preserve evaluated blocks' source ownership"; + it(copiedSource, function* () { const source = [ '', '', @@ -1575,46 +1591,50 @@ describe("REPL source ownership by import coordinate (#976)", () => { "{first}/{second}", ].join("\n"); for (const copy of [false, true]) { - yield* scoped(function* () { - let forwarded = 0; - if (copy) { - yield* Component.around({ - *applyModifiers([modifiers, block], next) { - forwarded += 1; - return yield* next(modifiers, { ...block }); - }, - }); - } - const run = yield* ownerRun(source); - expect(run.output.trim()).toBe("first/second"); - expect(forwarded).toBe(copy ? 3 : 0); - const evaluations = run.events.filter( - (event) => event.type === "yield" && event.description.type === "eval", - ); - expect( - evaluations.map((event) => - event.type === "yield" ? event.description[OWNER_FIELD] : undefined, - ), - ).toEqual([ - { coroutineId: "root", index: 1 }, - { coroutineId: "root", index: 3 }, - { coroutineId: "root", index: 0 }, - ]); - for (let end = 1; end <= run.events.length; end++) { - const prefix = run.events.slice(0, end); - expect(projected(copied(prefix))).toEqual(projected(prefix)); - } - const entry = only(projected(copied(run.events))); - if (entry === undefined) { - throw new Error("the journal admits one entry"); - } - expect(entry.scopes.map((scope) => scope.bindings)).toEqual([ - [{ name: "value", value: "first" }], - [{ name: "value", value: "second" }], - [], - ]); - expect(binding(entry, "callerValue")).toBe("caller"); - }); + yield* captureTestJournal( + { owner: SOURCE_OWNER, name: copiedSource }, + "", + function* (stream) { + let forwarded = 0; + if (copy) { + yield* Component.around({ + *applyModifiers([modifiers, block], next) { + forwarded += 1; + return yield* next(modifiers, { ...block }); + }, + }); + } + const run = yield* ownerRun(source, stream); + expect(run.output.trim()).toBe("first/second"); + expect(forwarded).toBe(copy ? 3 : 0); + const evaluations = run.events.filter( + (event) => event.type === "yield" && event.description.type === "eval", + ); + expect( + evaluations.map((event) => + event.type === "yield" ? event.description[OWNER_FIELD] : undefined, + ), + ).toEqual([ + { coroutineId: "root", index: 1 }, + { coroutineId: "root", index: 3 }, + { coroutineId: "root", index: 0 }, + ]); + for (let end = 1; end <= run.events.length; end++) { + const prefix = run.events.slice(0, end); + expect(projected(copied(prefix))).toEqual(projected(prefix)); + } + const entry = only(projected(copied(run.events))); + if (entry === undefined) { + throw new Error("the journal admits one entry"); + } + expect(entry.scopes.map((scope) => scope.bindings)).toEqual([ + [{ name: "value", value: "first" }], + [{ name: "value", value: "second" }], + [], + ]); + expect(binding(entry, "callerValue")).toBe("caller"); + }, + ); } }); From d9a16f3b065fe17140cdb60febaadd69d73cbf92 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:27:34 -0500 Subject: [PATCH 37/78] test: attribute fresh Git binding and Issue envelopes --- .../composition-component-binding.test.ts | 293 ++++++++++-------- packages/git/tests/issue-owned.test.ts | 254 ++++++++------- .../git/tests/repository-components.test.ts | 164 +++++----- 3 files changed, 387 insertions(+), 324 deletions(-) diff --git a/packages/git/tests/composition-component-binding.test.ts b/packages/git/tests/composition-component-binding.test.ts index dffdcba94..118286e0d 100644 --- a/packages/git/tests/composition-component-binding.test.ts +++ b/packages/git/tests/composition-component-binding.test.ts @@ -1,3 +1,4 @@ +import { captureTestJournal } from "../../test-support/failure-journal.ts"; /** * One registry, one authored body, and the invocation an owning execution * authenticates for it. @@ -36,7 +37,7 @@ import { collect, Component, registerComponents } from "@executablemd/core"; import type { ComponentRegistration, Json } from "@executablemd/core"; import { executeInstalled } from "@executablemd/core/host"; import type { ExecutionInstallation, IdentityComponent } from "@executablemd/core/host"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import type { InMemoryStream } from "@executablemd/durable-streams"; import { COMPOSITION_REGISTRATIONS } from "../src/composition/installation.ts"; import { pushDeclaration } from "../src/composition/components/GitPush.ts"; import { issueDeclaration } from "../src/composition/components/Issue.ts"; @@ -141,12 +142,13 @@ interface Ran { /** One document, through canonical execution, under this row's declarations. */ function run( root: string, + path: string, + stream: InMemoryStream, source: string, installations: readonly ExecutionInstallation[], before?: () => Operation, ): Operation { return scoped(function* (): Operation { - const path = join(root, `entry-${crypto.randomUUID()}.md`); yield* writeTextFile(path, source); // The whole vocabulary, as the Plugin registers it for every command. What // a row declares below is attached inside the execution, over the ordinary @@ -162,9 +164,7 @@ function run( try { output = String( yield* collect( - yield* executeInstalled({ path, stream: new InMemoryStream(), includes: [root] }, [ - ...installations, - ]), + yield* executeInstalled({ path, stream, includes: [root] }, [...installations]), ), ); } catch (error) { @@ -217,6 +217,21 @@ function paired(name: string): { }; } +function bindingCase( + name: string, + check: (root: string, path: string, stream: InMemoryStream) => Operation, +): void { + it(name, function* () { + const root = yield* useRoot(); + const path = join(root, `entry-${crypto.randomUUID()}.md`); + yield* captureTestJournal( + { owner: "packages/git/tests/composition-component-binding.test.ts", name }, + path, + (stream) => check(root, path, stream), + ); + }); +} + describe("one registry for every repository operation, and the policy an execution owns", () => { it("A1: describes one component whichever path carries it", function* (): Operation { // The whole vocabulary is registered ordinarily, and an execution that owns @@ -273,136 +288,152 @@ describe("one registry for every repository operation, and the policy an executi expect(declarations.map((entry) => entry.name)).toEqual(["Issue"]); }); - it("A1: canonical dispatch decides the form, whatever a contextual answer says", function* (): Operation { - const root = yield* useRoot(); - const seen = watched(); - - // A handler that reports the opposite shape to anything that asks. The form - // this element was written as is the scan's, so the read body runs and the - // upsert body does not. - const lying = function* (): Operation { - yield* Component.around({ - // deno-lint-ignore require-yield - *hasContent(): Operation { - return true; - }, - }); - }; - - const ran = yield* run( - root, - [ - ``, - ``, - ``, - "", - ].join("\n"), - [declaring({ issue: fakeIssuePolicy(seen) })], - lying, - ); - - expect(ran.refusal).toBe(undefined); - expect(seen.performed).toEqual([`read ${TRACKER}/issues/7`]); - }); - - it("A2: a nested read finishes before the upsert around it is performed", function* (): Operation { - const root = yield* useRoot(); - const seen = watched(); - - const ran = yield* run( - root, - [ - ``, - ``, - `what the inner read found: {inner.url}`, - ``, - ``, - "", - ].join("\n"), - [declaring({ issue: fakeIssuePolicy(seen) })], - ); + bindingCase( + "A1: canonical dispatch decides the form, whatever a contextual answer says", + function* (root, path, stream): Operation { + const seen = watched(); + + // A handler that reports the opposite shape to anything that asks. The form + // this element was written as is the scan's, so the read body runs and the + // upsert body does not. + const lying = function* (): Operation { + yield* Component.around({ + // deno-lint-ignore require-yield + *hasContent(): Operation { + return true; + }, + }); + }; - expect(ran.refusal).toBe(undefined); - // The child's own operation first: an upsert renders its description before - // it is offered, so a child that retains work of its own finishes first. - expect(seen.performed).toEqual([`read ${TRACKER}/issues/3`, `upsert ${TRACKER}`]); - // Two invocations, two facades, two sites — the outer one built first. - expect(seen.sites).toHaveLength(2); - expect(new Set(seen.sites).size).toBe(2); - }); + const ran = yield* run( + root, + path, + stream, + [ + ``, + ``, + ``, + "", + ].join("\n"), + [declaring({ issue: fakeIssuePolicy(seen) })], + lying, + ); - it("A2: two concurrent invocations keep their own sites", function* (): Operation { - const root = yield* useRoot(); - const seen = watched(); - - const ran = yield* run( - root, - [ - ``, - ``, - `first`, - `second`, - ``, - ``, - "", - ].join("\n"), - [declaring({ issue: fakeIssuePolicy(seen) })], - ); + expect(ran.refusal).toBe(undefined); + expect(seen.performed).toEqual([`read ${TRACKER}/issues/7`]); + }, + ); + + bindingCase( + "A2: a nested read finishes before the upsert around it is performed", + function* (root, path, stream): Operation { + const seen = watched(); + + const ran = yield* run( + root, + path, + stream, + [ + ``, + ``, + `what the inner read found: {inner.url}`, + ``, + ``, + "", + ].join("\n"), + [declaring({ issue: fakeIssuePolicy(seen) })], + ); - expect(ran.refusal).toBe(undefined); - expect(seen.sites).toHaveLength(2); - expect(new Set(seen.sites).size).toBe(2); - }); + expect(ran.refusal).toBe(undefined); + // The child's own operation first: an upsert renders its description before + // it is offered, so a child that retains work of its own finishes first. + expect(seen.performed).toEqual([`read ${TRACKER}/issues/3`, `upsert ${TRACKER}`]); + // Two invocations, two facades, two sites — the outer one built first. + expect(seen.sites).toHaveLength(2); + expect(new Set(seen.sites).size).toBe(2); + }, + ); + + bindingCase( + "A2: two concurrent invocations keep their own sites", + function* (root, path, stream): Operation { + const seen = watched(); + + const ran = yield* run( + root, + path, + stream, + [ + ``, + ``, + `first`, + `second`, + ``, + ``, + "", + ].join("\n"), + [declaring({ issue: fakeIssuePolicy(seen) })], + ); - it("A5: cancelling an invocation stops the operation it was performing", function* (): Operation { - const root = yield* useRoot(); - const seen = watched(); - const reached = withResolvers(); - - // The upsert suspends where a slow service would, and this row halts the - // whole execution while it is standing there. - const suspending = (site: string): IssueOperationsApi => { - seen.sites.push(site); - return { - read: function* (invocation): Operation { - return details(invocation.url); - }, - upsert: function* (invocation): Operation { - seen.performed.push(`upsert ${invocation.target}`); - reached.resolve(); - yield* suspend(); - throw new Error("a suspended upsert resumed"); - }, + expect(ran.refusal).toBe(undefined); + expect(seen.sites).toHaveLength(2); + expect(new Set(seen.sites).size).toBe(2); + }, + ); + + bindingCase( + "A5: cancelling an invocation stops the operation it was performing", + function* (root, path, stream): Operation { + const seen = watched(); + const reached = withResolvers(); + + // The upsert suspends where a slow service would, and this row halts the + // whole execution while it is standing there. + const suspending = (site: string): IssueOperationsApi => { + seen.sites.push(site); + return { + read: function* (invocation): Operation { + return details(invocation.url); + }, + upsert: function* (invocation): Operation { + seen.performed.push(`upsert ${invocation.target}`); + reached.resolve(); + yield* suspend(); + throw new Error("a suspended upsert resumed"); + }, + }; }; - }; - yield* scoped(function* (): Operation { - const task = yield* spawn(() => - run( - root, - [ - ``, - `described`, - ``, - "", - ].join("\n"), - [declaring({ issue: suspending })], - ), - ); - yield* race([ - reached.operation, - (function* (): Operation { - yield* sleep(30_000); - throw new Error("the upsert never reached its policy"); - })(), - ]); - // Joined here: the halt returns once the suspended upsert has been torn - // down, so what follows cannot be read before cancellation finished. - yield* task.halt(); - }); - - // The upsert was entered once, never resumed and never performed again. - expect(seen.performed).toEqual([`upsert ${TRACKER}`]); - expect(seen.sites).toHaveLength(1); - }); + yield* scoped(function* (): Operation { + const task = yield* spawn(() => + run( + root, + path, + stream, + [ + ``, + `described`, + ``, + "", + ].join("\n"), + [declaring({ issue: suspending })], + ), + ); + yield* race([ + reached.operation, + (function* (): Operation { + yield* sleep(30_000); + throw new Error("the upsert never reached its policy"); + })(), + ]); + // Joined here: the halt returns once the suspended upsert has been torn + // down, so what follows cannot be read before cancellation finished. + yield* task.halt(); + }); + + // The upsert was entered once, never resumed and never performed again. + expect(seen.performed).toEqual([`upsert ${TRACKER}`]); + expect(seen.sites).toHaveLength(1); + }, + ); }); diff --git a/packages/git/tests/issue-owned.test.ts b/packages/git/tests/issue-owned.test.ts index a4543833d..e2d2fd5b3 100644 --- a/packages/git/tests/issue-owned.test.ts +++ b/packages/git/tests/issue-owned.test.ts @@ -1,3 +1,4 @@ +import { captureTestJournal } from "../../test-support/failure-journal.ts"; /** * The durable envelope an owned Issue operation runs inside, and the * compatibility it owes the profile that used to be the only one. @@ -249,6 +250,7 @@ function run( stream: DurableStream, live: Live, options: { + readonly path?: string; readonly transport?: Transport; readonly installations?: readonly ExecutionInstallation[]; /** Install the workflow run's own Issue lifecycle, as a workflow host does. */ @@ -256,7 +258,7 @@ function run( } = {}, ): Operation { return scoped(function* (): Operation { - const path = join(fixture.root, `entry-${crypto.randomUUID()}.md`); + const path = options.path ?? join(fixture.root, `entry-${crypto.randomUUID()}.md`); yield* writeTextFile(path, source); const seen = observed(); yield* useCompositionComponents(); @@ -370,39 +372,56 @@ function workflowProfile(runId: string): readonly ExecutionInstallation[] { ]; } -describe("the durable envelope an owned Issue operation runs inside", () => { - it("E1: retains the answer one live read composed, and names it after the request", function* (): Operation { +function liveIssueCase( + name: string, + check: (fixture: Fixture, path: string, stream: InMemoryStream) => Operation, +): void { + it(name, function* () { const fixture = yield* useFixture(); - const stream = new InMemoryStream(); - const ran = yield* run( - fixture, - '', - stream, - { - read: function* (): Operation { - // A valid normalized result, answered without any transport: this is - // what a live middleware answer is, and the envelope records it. - return { ...DETAILS, tags: [...DETAILS.tags] }; - }, - }, + const path = join(fixture.root, `entry-${crypto.randomUUID()}.md`); + yield* captureTestJournal( + { owner: "packages/git/tests/issue-owned.test.ts", name }, + path, + (stream) => check(fixture, path, stream), ); - - expect(ran.refusal).toBe(undefined); - expect(ran.seen.live).toEqual(["read"]); - expect(ran.seen.transport).toEqual([]); - expect(ran.seen.answers).toEqual([{ ...DETAILS, tags: [...DETAILS.tags] }]); - - const records = issueRecords(ran.events); - expect(records.length).toBe(1); - expect(requestOf(records[0])).toEqual({ - operation: "read", - identity: { runId: "owner-1", expansionId: "site-1" }, - url: ISSUE_URL, - provider: null, - }); - expect(valueOf(records[0])).toEqual({ ...DETAILS, tags: [...DETAILS.tags] }); - expect(nameOf(records[0])).toBe(yield* digestOf(requestOf(records[0]))); }); +} + +describe("the durable envelope an owned Issue operation runs inside", () => { + liveIssueCase( + "E1: retains the answer one live read composed, and names it after the request", + function* (fixture, path, stream): Operation { + const ran = yield* run( + fixture, + '', + stream, + { + read: function* (): Operation { + // A valid normalized result, answered without any transport: this is + // what a live middleware answer is, and the envelope records it. + return { ...DETAILS, tags: [...DETAILS.tags] }; + }, + }, + { path }, + ); + + expect(ran.refusal).toBe(undefined); + expect(ran.seen.live).toEqual(["read"]); + expect(ran.seen.transport).toEqual([]); + expect(ran.seen.answers).toEqual([{ ...DETAILS, tags: [...DETAILS.tags] }]); + + const records = issueRecords(ran.events); + expect(records.length).toBe(1); + expect(requestOf(records[0])).toEqual({ + operation: "read", + identity: { runId: "owner-1", expansionId: "site-1" }, + url: ISSUE_URL, + provider: null, + }); + expect(valueOf(records[0])).toEqual({ ...DETAILS, tags: [...DETAILS.tags] }); + expect(nameOf(records[0])).toBe(yield* digestOf(requestOf(records[0]))); + }, + ); it("E1: replays a completed read without invoking the live operation at all", function* (): Operation { const fixture = yield* useFixture(); @@ -493,93 +512,100 @@ describe("the durable envelope an owned Issue operation runs inside", () => { expect(issueRecords(again.events).length).toBe(1); }); - it("E1: a child's record lands before its parent's, and each call retains one", function* (): Operation { - const fixture = yield* useFixture(); - const ran = yield* run( - fixture, - [ - "", - '', - "", - '', - ].join("\n"), - new InMemoryStream(), - { - read: function* (): Operation { - return { ...DETAILS, tags: [...DETAILS.tags] }; - }, - upsert: function* (): Operation { - return { url: `${TRACKER}/issues/12` }; + liveIssueCase( + "E1: a child's record lands before its parent's, and each call retains one", + function* (fixture, path, stream): Operation { + const ran = yield* run( + fixture, + [ + "", + '', + "", + '', + ].join("\n"), + stream, + { + read: function* (): Operation { + return { ...DETAILS, tags: [...DETAILS.tags] }; + }, + upsert: function* (): Operation { + return { url: `${TRACKER}/issues/12` }; + }, }, - }, - ); - - expect(ran.refusal).toBe(undefined); - const records = issueRecords(ran.events); - // One envelope per Issue operation, in the order the document reached them: - // the content's read finished at its own position before the upsert that - // follows it was offered. - expect(records.length).toBe(2); - expect(requestOf(records[0])).toMatchObject({ operation: "read" }); - expect(requestOf(records[1])).toMatchObject({ operation: "upsert" }); - }); + { path }, + ); + + expect(ran.refusal).toBe(undefined); + const records = issueRecords(ran.events); + // One envelope per Issue operation, in the order the document reached them: + // the content's read finished at its own position before the upsert that + // follows it was offered. + expect(records.length).toBe(2); + expect(requestOf(records[0])).toMatchObject({ operation: "read" }); + expect(requestOf(records[1])).toMatchObject({ operation: "upsert" }); + }, + ); - it("E7: writes a workflow run's record exactly as it has always written it", function* (): Operation { - const fixture = yield* useFixture(); - const stream = new InMemoryStream(); - const ran = yield* run( - fixture, - WORKFLOW_ENTRY, - stream, - {}, - { - retained: true, - installations: workflowProfile(RUN.runId), - transport: { - // deno-lint-ignore require-yield - *upsert(): Operation { - return { url: `${TRACKER}/issues/21` }; + liveIssueCase( + "E7: writes a workflow run's record exactly as it has always written it", + function* (fixture, path, stream): Operation { + const ran = yield* run( + fixture, + WORKFLOW_ENTRY, + stream, + {}, + { + path, + retained: true, + installations: workflowProfile(RUN.runId), + transport: { + // deno-lint-ignore require-yield + *upsert(): Operation { + return { url: `${TRACKER}/issues/21` }; + }, }, }, - }, - ); - - expect(ran.refusal).toBe(undefined); - expect(ran.seen.transport).toEqual([`upsert ${TRACKER}`]); - - const record = issueRecords(ran.events)[0]; - const asked = requestOf(record); - // The expansion id is the engine's, so it is read back rather than - // predicted. Everything around it is the encoding this row is about. - const site = String(Reflect.get(Object(Reflect.get(Object(asked), "identity")), "expansionId")); - expect(asked).toEqual({ - operation: "upsert", - identity: { runId: RUN.runId, expansionId: site }, - target: TRACKER, - provider: null, - issue: { - title: "Filed", - description: "a described issue", - tags: [], - assignee: null, - }, - }); - expect(valueOf(record)).toEqual({ url: `${TRACKER}/issues/21` }); - expect(nameOf(record)).toBe(yield* digestOf(asked)); - // And the key the provider was handed is the canonical encoding of this - // run's own identity and target, computed here rather than by the code - // that produced it. - expect(ran.seen.keys).toEqual([ - JSON.stringify( - sorted({ - operation: "upsert", - canonicalTargetUrl: TRACKER, - runId: RUN.runId, - expansionId: site, - }), - ), - ]); - }); + ); + + expect(ran.refusal).toBe(undefined); + expect(ran.seen.transport).toEqual([`upsert ${TRACKER}`]); + + const record = issueRecords(ran.events)[0]; + const asked = requestOf(record); + // The expansion id is the engine's, so it is read back rather than + // predicted. Everything around it is the encoding this row is about. + const site = String( + Reflect.get(Object(Reflect.get(Object(asked), "identity")), "expansionId"), + ); + expect(asked).toEqual({ + operation: "upsert", + identity: { runId: RUN.runId, expansionId: site }, + target: TRACKER, + provider: null, + issue: { + title: "Filed", + description: "a described issue", + tags: [], + assignee: null, + }, + }); + expect(valueOf(record)).toEqual({ url: `${TRACKER}/issues/21` }); + expect(nameOf(record)).toBe(yield* digestOf(asked)); + // And the key the provider was handed is the canonical encoding of this + // run's own identity and target, computed here rather than by the code + // that produced it. + expect(ran.seen.keys).toEqual([ + JSON.stringify( + sorted({ + operation: "upsert", + canonicalTargetUrl: TRACKER, + runId: RUN.runId, + expansionId: site, + }), + ), + ]); + }, + ); it("E7: replays the run's own record without reaching a provider", function* (): Operation { const fixture = yield* useFixture(); diff --git a/packages/git/tests/repository-components.test.ts b/packages/git/tests/repository-components.test.ts index 1ad082f8b..d24428e91 100644 --- a/packages/git/tests/repository-components.test.ts +++ b/packages/git/tests/repository-components.test.ts @@ -31,7 +31,7 @@ import { useCompositionComponents } from "../src/composition/installation.ts"; import { RepositoryCompositionProviderError } from "../src/composition/errors.ts"; import { DirInvocationError } from "../../core/src/components/Dir.ts"; import { denoRepositoryHost } from "../src/deno/composition/host.ts"; -import { InMemoryStream } from "@executablemd/durable-streams"; +import { journalCases } from "../../test-support/journal-cases.ts"; import { createRun, useStorageRoot, withStorage } from "../../workflow/tests/support/storage.ts"; import { withWorkflowWorkspace } from "../../workflow/src/deno/workspace/host.ts"; import { gitWorkspaceAttachment } from "../src/deno/attachment.ts"; @@ -60,6 +60,8 @@ function isWorktreeRefusal(value: unknown): value is WorktreeCompositionError { return value instanceof WorktreeCompositionError; } +const journalCase = journalCases("packages/git/tests/repository-components.test.ts"); + describe("workflow Repository composition", () => { it("binds a self-closing Repository's Workspace-relative checkout path", function* () { const root = yield* useStorageRoot(); @@ -461,14 +463,14 @@ describe("workflow composition failure policy", () => { * existed. The plain form is what discriminates: no region is present, so * nothing may print, and what escapes must still be the original failure. */ - it("does not turn a missing provider into a refusal", function* () { + journalCase("does not turn a missing provider into a refusal", "", function* (stream) { const failure = yield* raised( scoped(function* () { yield* useCompositionComponents(); return yield* collect( yield* execute({ ...inlineSource(``), - stream: new InMemoryStream(), + stream, }), ); }), @@ -770,84 +772,88 @@ function fatalCause(error: unknown, seen = new Set()): unknown { * and this could pass while the operation quietly answered instead of refusing. */ describe("Dir without a Files provider", () => { - it("stops at ensureDirectory, and no directory, content or sibling follows", function* () { - const calls: string[] = []; - // Sentinel components rather than rendered text. What escapes a failed - // execution is an error, and searching an error's string for a marker - // cannot tell "the content never expanded" from "the content expanded and - // its text is simply not in this message". A component that ran leaves a - // record here whether or not anything was rendered or collected. - const expanded: string[] = []; - const marker = (name: string): ComponentRegistration => ({ - name, - origin: "test://marker", - props: { type: "object", properties: {}, additionalProperties: false }, - // deno-lint-ignore require-yield - *fn(): Operation { - expanded.push(name); - return name; - }, - }); + journalCase( + "stops at ensureDirectory, and no directory, content or sibling follows", + "", + function* (stream) { + const calls: string[] = []; + // Sentinel components rather than rendered text. What escapes a failed + // execution is an error, and searching an error's string for a marker + // cannot tell "the content never expanded" from "the content expanded and + // its text is simply not in this message". A component that ran leaves a + // record here whether or not anything was rendered or collected. + const expanded: string[] = []; + const marker = (name: string): ComponentRegistration => ({ + name, + origin: "test://marker", + props: { type: "object", properties: {}, additionalProperties: false }, + // deno-lint-ignore require-yield + *fn(): Operation { + expanded.push(name); + return name; + }, + }); - const failure = yield* raised( - scoped(function* () { - yield* useCompositionComponents(); - yield* registerComponents([marker("Inside"), marker("After")]); - // Middleware that records and delegates. Delegation is what keeps this - // fail-closed: the absent-provider terminal is still what answers, so - // recording the call cannot be what makes the document stop. - yield* API.Files.around({ - *checkFilePath([input], next) { - calls.push("check-file-path"); - return yield* next(input); - }, - *readTextFile([input], next) { - calls.push("read"); - return yield* next(input); - }, - *writeTextFile([input], next) { - calls.push("write"); - return yield* next(input); - }, - *deleteFile([input], next) { - calls.push("delete"); - return yield* next(input); - }, - *ensureDirectory([input], next) { - calls.push("ensure-directory"); - return yield* next(input); - }, - *globFiles([input], next) { - calls.push("glob"); - return yield* next(input); - }, - *temporaryDirectory([], next) { - calls.push("temporary-directory"); - return yield* next(); - }, - }); - return yield* collect( - yield* execute({ - ...inlineSource('\n\n\n\n\n\n\n'), - stream: new InMemoryStream(), - }), - ); - }), - ); + const failure = yield* raised( + scoped(function* () { + yield* useCompositionComponents(); + yield* registerComponents([marker("Inside"), marker("After")]); + // Middleware that records and delegates. Delegation is what keeps this + // fail-closed: the absent-provider terminal is still what answers, so + // recording the call cannot be what makes the document stop. + yield* API.Files.around({ + *checkFilePath([input], next) { + calls.push("check-file-path"); + return yield* next(input); + }, + *readTextFile([input], next) { + calls.push("read"); + return yield* next(input); + }, + *writeTextFile([input], next) { + calls.push("write"); + return yield* next(input); + }, + *deleteFile([input], next) { + calls.push("delete"); + return yield* next(input); + }, + *ensureDirectory([input], next) { + calls.push("ensure-directory"); + return yield* next(input); + }, + *globFiles([input], next) { + calls.push("glob"); + return yield* next(input); + }, + *temporaryDirectory([], next) { + calls.push("temporary-directory"); + return yield* next(); + }, + }); + return yield* collect( + yield* execute({ + ...inlineSource('\n\n\n\n\n\n\n'), + stream, + }), + ); + }), + ); - // The first Files call the component makes, and the only one it reaches. - expect(calls[0]).toBe("ensure-directory"); - expect(calls).toEqual(["ensure-directory"]); - // Absence is not a refusal the document can print: what escapes is the - // provider-unavailable failure itself. - expect(parseFilesFatal(fatalCause(failure))?.kind).toBe("provider-unavailable"); - // Neither the content inside the region nor the sibling after it ran. This - // is the assertion the failure's message could not make. - expect(expanded).toEqual([]); - // And nothing was made. The path is relative, so a provider that had - // answered would have created it beneath the process directory. - expect(yield* exists(join(process.cwd(), "made"))).toBe(false); - }); + // The first Files call the component makes, and the only one it reaches. + expect(calls[0]).toBe("ensure-directory"); + expect(calls).toEqual(["ensure-directory"]); + // Absence is not a refusal the document can print: what escapes is the + // provider-unavailable failure itself. + expect(parseFilesFatal(fatalCause(failure))?.kind).toBe("provider-unavailable"); + // Neither the content inside the region nor the sibling after it ran. This + // is the assertion the failure's message could not make. + expect(expanded).toEqual([]); + // And nothing was made. The path is relative, so a provider that had + // answered would have created it beneath the process directory. + expect(yield* exists(join(process.cwd(), "made"))).toBe(false); + }, + ); }); describe("workflow Git declarations belong to the Plugin", () => { From 68b2cf9ea7f6ebdbb2e53f0fc4d0852556a5dd6b Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:29:59 -0500 Subject: [PATCH 38/78] test: attribute fresh Workflow and Testing journals --- packages/testing/tests/test-component.test.ts | 163 +-- .../testing/tests/testing-boundary.test.ts | 106 +- packages/workflow/tests/retained-run.test.ts | 29 +- .../tests/workflow-checkpoint.test.ts | 24 +- packages/workflow/tests/workflow-run.test.ts | 984 ++++++++++-------- 5 files changed, 700 insertions(+), 606 deletions(-) diff --git a/packages/testing/tests/test-component.test.ts b/packages/testing/tests/test-component.test.ts index 5ee77a0a6..5d51c88da 100644 --- a/packages/testing/tests/test-component.test.ts +++ b/packages/testing/tests/test-component.test.ts @@ -19,8 +19,10 @@ import type { ErrorSegment } from "@executablemd/core"; import { createTestHandlers } from "../src/handlers.ts"; import { absorbTestFailure, Staging } from "../src/test-component.ts"; import { documentCases, runDoc, withFreshDocument } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; const OWNER = "packages/testing/tests/test-component.test.ts"; +const journalCase = journalCases(OWNER); const documentCase = documentCases(OWNER); describe(" as a function component", () => { @@ -86,61 +88,66 @@ describe(" as a function component", () => { }, ); - it("keeps actual Files infrastructure failure globally terminal inside canonical Test", function* () { - let fatal: unknown; - let later = 0; - let released = false; - const stream = new InMemoryStream(); - yield* registerComponents([ - { - name: "LaterTestWork", - origin: "test-interaction", - props: { type: "object" }, - *fn() { - later++; - return "later work"; + journalCase( + "keeps actual Files infrastructure failure globally terminal inside canonical Test", + "README.md", + function* (stream) { + let fatal: unknown; + let later = 0; + let released = false; + yield* registerComponents([ + { + name: "LaterTestWork", + origin: "test-interaction", + props: { type: "object" }, + *fn() { + later++; + return "later work"; + }, }, - }, - { - name: "TestFilesInfra", - origin: "test-interaction", - props: { type: "object" }, - *fn() { - yield* ensure(() => { - released = true; - }); - yield* API.Files.around({ - *readTextFile() { - throw new Error("broken provider"); - }, - }); - try { - yield* invokeFiles(API.Files.operations.readTextFile({ cwd: ".", path: "notes.txt" })); - } catch (error) { - fatal = filesFatalFailure(error); - throw error; - } - return "unreachable"; + { + name: "TestFilesInfra", + origin: "test-interaction", + props: { type: "object" }, + *fn() { + yield* ensure(() => { + released = true; + }); + yield* API.Files.around({ + *readTextFile() { + throw new Error("broken provider"); + }, + }); + try { + yield* invokeFiles( + API.Files.operations.readTextFile({ cwd: ".", path: "notes.txt" }), + ); + } catch (error) { + fatal = filesFatalFailure(error); + throw error; + } + return "unreachable"; + }, }, - }, - ]); - const run = yield* runDoc( - { - "README.md": - '', - }, - { stream }, - ); - expect(released).toBe(true); - expect(fatal).toBeDefined(); - expect(run.completion.ok).toBe(false); - if (!run.completion.ok) { - expect(filesFatalFailure(run.completion.error)).toBe(fatal); - } - expect(later).toBe(0); - expect(run.results).toHaveLength(0); - expect(stream.snapshot().filter((event) => event.type === "close")).toHaveLength(0); - }); + ]); + const run = yield* runDoc( + { + "README.md": + '', + }, + { stream }, + ); + expect(released).toBe(true); + expect(fatal).toBeDefined(); + expect(run.completion.ok).toBe(false); + if (!run.completion.ok) { + expect(filesFatalFailure(run.completion.error)).toBe(fatal); + } + expect(later).toBe(0); + expect(run.results).toHaveLength(0); + expect(stream.snapshot().filter((event) => event.type === "close")).toHaveLength(0); + }, + ); // The raise interceptor answers nearest-first so can catch a // diagnostic before the test claims it. That must not cost the property the @@ -306,30 +313,33 @@ describe(" as a function component", () => { // Staging defers the journal write, so the thing to pin is that deferring it // does not reorder it: results are recorded and journalled in discovery // order, including the one an upgrade rewrote after its test had returned. - it("records and journals in discovery order when a middle test tears down badly", function* () { - const doc = [ - "", - '', - '', - FAILING_CLEANUP, - "", - '', - "", - "", - ].join("\n"); + journalCase( + "records and journals in discovery order when a middle test tears down badly", + "README.md", + function* (stream) { + const doc = [ + "", + '', + '', + FAILING_CLEANUP, + "", + '', + "", + "", + ].join("\n"); - const stream = new InMemoryStream(); - const run = yield* runDoc({ "README.md": doc }, { stream }); + const run = yield* runDoc({ "README.md": doc }, { stream }); - expect(run.results.map((r) => [r.name, r.error?.kind])).toEqual([ - ["one", undefined], - ["two", "teardown"], - ["three", undefined], - ]); - const journalled = yield* entriesOf(stream, "test_result"); - expect(journalled).toHaveLength(3); - expect(journalled).toEqual([...journalled].sort((a, b) => a.localeCompare(b))); - }); + expect(run.results.map((r) => [r.name, r.error?.kind])).toEqual([ + ["one", undefined], + ["two", "teardown"], + ["three", undefined], + ]); + const journalled = yield* entriesOf(stream, "test_result"); + expect(journalled).toHaveLength(3); + expect(journalled).toEqual([...journalled].sort((a, b) => a.localeCompare(b))); + }, + ); // A root run has no element, so nothing in the document flushes the // last test. The region useTesting installs settles inside durableRun, before @@ -367,10 +377,9 @@ describe(" as a function component", () => { // The root region is flush-only: it reports no outcome of its own, so a root // run's journal looks exactly like one without it. - it("writes no boundary entry for a root run", function* () { + journalCase("writes no boundary entry for a root run", "README.md", function* (stream) { const doc = ['', ""].join("\n"); - const stream = new InMemoryStream(); yield* runDoc({ "README.md": doc }, { stream, testing: true }); expect(yield* entriesOf(stream, "testing_boundary")).toEqual([]); diff --git a/packages/testing/tests/testing-boundary.test.ts b/packages/testing/tests/testing-boundary.test.ts index e88029219..30c3b9345 100644 --- a/packages/testing/tests/testing-boundary.test.ts +++ b/packages/testing/tests/testing-boundary.test.ts @@ -18,6 +18,10 @@ import { documentCases, runDoc } from "./helpers.ts"; const documentCase = documentCases("packages/testing/tests/testing-boundary.test.ts"); import type { DocRun } from "./helpers.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const OWNER = "packages/testing/tests/testing-boundary.test.ts"; +const journalCase = journalCases(OWNER); /** Every journalled boundary entry, by the name it recorded. */ function* boundaryEntries(stream: InMemoryStream): Operation { @@ -61,32 +65,35 @@ function stopping(files: Record, stream: InMemoryStream): Operat describe("Tier TB — a boundary that never finished", () => { beforeAll(() => useTempFileCompiler()); - it("TB1: a stopped body reports no outcome and journals nothing", function* () { - const stream = new InMemoryStream(); - const doc = [ - "", - '', - "", - "", - "", - "AFTER", - "", - "", - "", - ].join("\n"); - - const run = yield* stopping({ "README.md": doc }, stream); - - // The original failure reaches completion, by identity… - expect(run.completion.ok).toBe(false); - expect(run.completion.ok === false && run.completion.error).toBe(BOOM); - // …nothing after it rendered… - expect(run.output).not.toContain("AFTER"); - // …no outcome was observed for a boundary that never finished… - expect(run.boundaries).toEqual([]); - // …and nothing was journalled for it. - expect(yield* boundaryEntries(stream)).toEqual([]); - }); + journalCase( + "TB1: a stopped body reports no outcome and journals nothing", + "README.md", + function* (stream) { + const doc = [ + "", + '', + "", + "", + "", + "AFTER", + "", + "", + "", + ].join("\n"); + + const run = yield* stopping({ "README.md": doc }, stream); + + // The original failure reaches completion, by identity… + expect(run.completion.ok).toBe(false); + expect(run.completion.ok === false && run.completion.error).toBe(BOOM); + // …nothing after it rendered… + expect(run.output).not.toContain("AFTER"); + // …no outcome was observed for a boundary that never finished… + expect(run.boundaries).toEqual([]); + // …and nothing was journalled for it. + expect(yield* boundaryEntries(stream)).toEqual([]); + }, + ); it("TB2: replaying that journal hydrates no boundary outcome", function* () { const stream = new InMemoryStream(); @@ -100,28 +107,31 @@ describe("Tier TB — a boundary that never finished", () => { expect(yield* boundaryEntries(stream)).toEqual([]); }); - it("TB3: a body that only printed is complete, and does report", function* () { - const stream = new InMemoryStream(); - const doc = [ - "", - "", - "", - "", - "", - '', - "", - "", - "", - "", - ].join("\n"); - - // No interceptor, and a region that prints: the error settles as a printed - // error, so the projection finishes and the boundary is a real count. - const run = yield* runDoc({ "README.md": doc }, { stream }); - - expect(run.boundaries).toEqual([{ tests: 1, failed: 0 }]); - expect(yield* boundaryEntries(stream)).toHaveLength(1); - }); + journalCase( + "TB3: a body that only printed is complete, and does report", + "README.md", + function* (stream) { + const doc = [ + "", + "", + "", + "", + "", + '', + "", + "", + "", + "", + ].join("\n"); + + // No interceptor, and a region that prints: the error settles as a printed + // error, so the projection finishes and the boundary is a real count. + const run = yield* runDoc({ "README.md": doc }, { stream }); + + expect(run.boundaries).toEqual([{ tests: 1, failed: 0 }]); + expect(yield* boundaryEntries(stream)).toHaveLength(1); + }, + ); }); describe("Tier TB — a repository component replaces ", () => { diff --git a/packages/workflow/tests/retained-run.test.ts b/packages/workflow/tests/retained-run.test.ts index cbe71e4f9..791a8b784 100644 --- a/packages/workflow/tests/retained-run.test.ts +++ b/packages/workflow/tests/retained-run.test.ts @@ -39,6 +39,10 @@ import type { ExecutionRequest } from "@executablemd/core"; import { GitQuery } from "@executablemd/git/api"; import { getWorkflowRun, retainedWorkflowInstallation } from "../src/run.ts"; import type { WorkflowRun } from "../src/run.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const OWNER = "packages/workflow/tests/retained-run.test.ts"; +const journalCase = journalCases(OWNER); const COMMIT = "9fceb02d0ae598e95dc970b74767f19372d61af8"; const OTHER_COMMIT = "1111111111111111111111111111111111111111"; @@ -334,18 +338,21 @@ function completedWith( } describe("Tier RR — retained workflow runs", () => { - it("RR1: records exactly the retained run, without allocating or resolving", function* () { - const stream = new InMemoryStream(); - const attempt = yield* runRetained(RETAINED, stream); + journalCase( + "RR1: records exactly the retained run, without allocating or resolving", + "", + function* (stream) { + const attempt = yield* runRetained(RETAINED, stream); - expect(attempt.thrown).toBeUndefined(); - expect(attempt.seen).toEqual([RETAINED]); - expect(recordedRun(stream)).toEqual({ - runId: "release-1.4", - bundleHash: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", - }); - expect(workflowEvents(stream)).toHaveLength(1); - }); + expect(attempt.thrown).toBeUndefined(); + expect(attempt.seen).toEqual([RETAINED]); + expect(recordedRun(stream)).toEqual({ + runId: "release-1.4", + bundleHash: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", + }); + expect(workflowEvents(stream)).toHaveLength(1); + }, + ); it("RR2: restores the retained run from a truncated journal without recording again", function* () { const first = new InMemoryStream(); diff --git a/packages/workflow/tests/workflow-checkpoint.test.ts b/packages/workflow/tests/workflow-checkpoint.test.ts index b151a296c..637474caa 100644 --- a/packages/workflow/tests/workflow-checkpoint.test.ts +++ b/packages/workflow/tests/workflow-checkpoint.test.ts @@ -22,13 +22,16 @@ import { DatabaseSync } from "node:sqlite"; import { collect, execute, inlineSource, isJsonObject } from "@executablemd/core"; import type { Json } from "@executablemd/core"; import type { DurableEvent, Yield } from "@executablemd/durable-streams"; -import { InMemoryStream } from "@executablemd/durable-streams"; import type { WorkflowRunDatabase } from "../mod.ts"; import { runWorkflowDocument } from "../../git/tests/support/composition.ts"; import { runPath, useStorageRoot, withBegunRun } from "./support/storage.ts"; import { createSuspensionController } from "../src/deno/suspension.ts"; import type { SuspensionNotice } from "../src/deno/suspension.ts"; import { SUSPENSION_REQUEST } from "../src/suspension/suspend.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; + +const OWNER = "packages/workflow/tests/workflow-checkpoint.test.ts"; +const journalCase = journalCases(OWNER); /** The durable record core's `` writes and the workflow's must not. */ const ELICIT = "elicit"; @@ -226,14 +229,17 @@ describe("Tier CK — the durable checkpoint", () => { }); }); - it("CK7: ordinary execution is unchanged — core's still records", function* () { - const stream = new InMemoryStream(); - const output = yield* collect(yield* execute({ ...inlineSource(ANSWERED), stream })); + journalCase( + "CK7: ordinary execution is unchanged — core's still records", + "", + function* (stream) { + const output = yield* collect(yield* execute({ ...inlineSource(ANSWERED), stream })); - expect(String(output)).toContain("decision: true"); + expect(String(output)).toContain("decision: true"); - const events: DurableEvent[] = yield* stream.readAll(); - const recorded = events.filter(isYield).filter((event) => event.description.type === ELICIT); - expect(recorded).toHaveLength(1); - }); + const events: DurableEvent[] = yield* stream.readAll(); + const recorded = events.filter(isYield).filter((event) => event.description.type === ELICIT); + expect(recorded).toHaveLength(1); + }, + ); }); diff --git a/packages/workflow/tests/workflow-run.test.ts b/packages/workflow/tests/workflow-run.test.ts index 00eb0498a..fcf5ccfc3 100644 --- a/packages/workflow/tests/workflow-run.test.ts +++ b/packages/workflow/tests/workflow-run.test.ts @@ -36,6 +36,11 @@ import { createWorkflowRunInstallation, getWorkflowRun } from "../src/run.ts"; import { WORKFLOW_RUN } from "../src/journal.ts"; import type { WorkflowRun } from "../src/run.ts"; import { retainedRunMismatch } from "../mod.ts"; +import { journalCases } from "../../test-support/journal-cases.ts"; +import { captureTestJournal } from "../../test-support/failure-journal.ts"; + +const OWNER = "packages/workflow/tests/workflow-run.test.ts"; +const journalCase = journalCases(OWNER); const BUNDLE = "9fceb02d0ae598e95dc970b74767f19372d61af89fceb02d0ae598e95dc970b74"; const OTHER_BUNDLE = "1111111111111111111111111111111111111111111111111111111111111111"; @@ -121,189 +126,214 @@ function recordedRun(stream: InMemoryStream): Json | undefined { } describe("Tier WR — workflow runs", () => { - it("WR1: is unreadable before the execution, readable inside it, unreadable after", function* () { - const seen: WorkflowRun[] = []; - const before: string[] = []; - const after: string[] = []; - - yield* scoped(function* () { - yield* useProbe(seen); - const workflow = runInstallation(); - - // Installing the middleware creates no workflow run. - try { - yield* getWorkflowRun(); - } catch (error) { - before.push(error instanceof Error ? error.message : String(error)); - } - - yield* collect( - yield* executeInstalled({ ...inlineSource("\n"), stream: new InMemoryStream() }, [ - workflow, - ]), - ); + journalCase( + "WR1: is unreadable before the execution, readable inside it, unreadable after", + "", + function* (stream) { + const seen: WorkflowRun[] = []; + const before: string[] = []; + const after: string[] = []; - // ...and the run does not outlive the execution that owns it, even though - // the scope that installed the middleware is still alive. - try { - yield* getWorkflowRun(); - } catch (error) { - after.push(error instanceof Error ? error.message : String(error)); - } - }); + yield* scoped(function* () { + yield* useProbe(seen); + const workflow = runInstallation(); - expect(seen).toHaveLength(1); - expect(seen[0]).toEqual({ runId: expect.any(String), bundleHash: BUNDLE }); - expect(before[0]).toContain("run installation"); - expect(after[0]).toContain("run installation"); - }); + // Installing the middleware creates no workflow run. + try { + yield* getWorkflowRun(); + } catch (error) { + before.push(error instanceof Error ? error.message : String(error)); + } - it("WR2: every read inside one execution answers with the same frozen value", function* () { - const seen: WorkflowRun[] = []; + yield* collect( + yield* executeInstalled({ ...inlineSource("\n"), stream }, [workflow]), + ); - yield* scoped(function* () { - yield* useProbe(seen); - const workflow = runInstallation(); - yield* collect( - yield* executeInstalled( - { - ...inlineSource("\n\n\n"), - stream: new InMemoryStream(), - }, - [workflow], - ), - ); - }); + // ...and the run does not outlive the execution that owns it, even though + // the scope that installed the middleware is still alive. + try { + yield* getWorkflowRun(); + } catch (error) { + after.push(error instanceof Error ? error.message : String(error)); + } + }); - expect(seen).toHaveLength(2); - expect(seen[0]).toBe(seen[1]); - expect(Object.isFrozen(seen[0])).toBe(true); - }); + expect(seen).toHaveLength(1); + expect(seen[0]).toEqual({ runId: expect.any(String), bundleHash: BUNDLE }); + expect(before[0]).toContain("run installation"); + expect(after[0]).toContain("run installation"); + }, + ); - it("WR3: concurrent executions each read their own run", function* () { - const first: WorkflowRun[] = []; - const second: WorkflowRun[] = []; + journalCase( + "WR2: every read inside one execution answers with the same frozen value", + "", + function* (stream) { + const seen: WorkflowRun[] = []; - function run(into: WorkflowRun[], bundleHash: string, runId: string): Operation { - return scoped(function* () { - yield* useProbe(into); - const workflow = runInstallation(bundleHash, { runId }); + yield* scoped(function* () { + yield* useProbe(seen); + const workflow = runInstallation(); yield* collect( yield* executeInstalled( - { ...inlineSource("\n"), stream: new InMemoryStream() }, + { + ...inlineSource("\n\n\n"), + stream, + }, [workflow], ), ); }); - } - yield* scoped(function* () { - const a = yield* spawn(() => run(first, BUNDLE, "first-run")); - const b = yield* spawn(() => run(second, OTHER_BUNDLE, "second-run")); - yield* a; - yield* b; - }); + expect(seen).toHaveLength(2); + expect(seen[0]).toBe(seen[1]); + expect(Object.isFrozen(seen[0])).toBe(true); + }, + ); - expect(first[0]?.bundleHash).toBe(BUNDLE); - expect(second[0]?.bundleHash).toBe(OTHER_BUNDLE); - expect(first[0]?.runId).not.toBe(second[0]?.runId); + const concurrentRuns = "WR3: concurrent executions each read their own run"; + journalCase(concurrentRuns, "", function* (streamA) { + yield* captureTestJournal( + { owner: OWNER, name: concurrentRuns }, + "", + function* (streamB) { + const first: WorkflowRun[] = []; + const second: WorkflowRun[] = []; + + function run( + stream: InMemoryStream, + into: WorkflowRun[], + bundleHash: string, + runId: string, + ): Operation { + return scoped(function* () { + yield* useProbe(into); + const workflow = runInstallation(bundleHash, { runId }); + yield* collect( + yield* executeInstalled({ ...inlineSource("\n"), stream }, [workflow]), + ); + }); + } + + yield* scoped(function* () { + const a = yield* spawn(() => run(streamA, first, BUNDLE, "first-run")); + const b = yield* spawn(() => run(streamB, second, OTHER_BUNDLE, "second-run")); + yield* a; + yield* b; + }); + + expect(first[0]?.bundleHash).toBe(BUNDLE); + expect(second[0]?.bundleHash).toBe(OTHER_BUNDLE); + expect(first[0]?.runId).not.toBe(second[0]?.runId); + }, + ); }); - it("WR20: one installation value reused by two executions gives each its own run", function* () { - // A host may hold one installation value and run more than one document - // with it. Each of those is a separate execution, and the run one of them - // records is not the other's — including while both are live. - const shared = runInstallation(); - const prepared = withResolvers(); - const release = withResolvers(); - const streamA = new InMemoryStream(); - const streamB = new InMemoryStream(); - const seenA: WorkflowRun[] = []; - const seenB: WorkflowRun[] = []; - - const first = yield* spawn(() => - scoped(function* () { - yield* registerComponents([ - { - name: "Hold", - origin: "tier-wr", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn() { - // Prepared, and holding here while the sibling runs end to end. - prepared.resolve(); - yield* release.operation; - seenA.push(yield* getWorkflowRun()); - seenA.push(yield* getWorkflowRun()); - return ""; - }, - }, - ]); - return yield* collect( - yield* executeInstalled({ ...inlineSource("\n"), stream: streamA }, [shared]), + const sharedInstallation = + "WR20: one installation value reused by two executions gives each its own run"; + journalCase(sharedInstallation, "", function* (streamA) { + yield* captureTestJournal( + { owner: OWNER, name: sharedInstallation }, + "", + function* (streamB) { + // A host may hold one installation value and run more than one document + // with it. Each of those is a separate execution, and the run one of them + // records is not the other's — including while both are live. + const shared = runInstallation(); + const prepared = withResolvers(); + const release = withResolvers(); + const seenA: WorkflowRun[] = []; + const seenB: WorkflowRun[] = []; + + const first = yield* spawn(() => + scoped(function* () { + yield* registerComponents([ + { + name: "Hold", + origin: "tier-wr", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn() { + // Prepared, and holding here while the sibling runs end to end. + prepared.resolve(); + yield* release.operation; + seenA.push(yield* getWorkflowRun()); + seenA.push(yield* getWorkflowRun()); + return ""; + }, + }, + ]); + return yield* collect( + yield* executeInstalled({ ...inlineSource("\n"), stream: streamA }, [shared]), + ); + }), ); - }), - ); - - yield* prepared.operation; - - yield* scoped(function* () { - yield* useProbe(seenB); - yield* collect( - yield* executeInstalled({ ...inlineSource("\n"), stream: streamB }, [shared]), - ); - }); - release.resolve(); - yield* first; - - const recordedA = recordedRun(streamA); - const recordedB = recordedRun(streamB); - expect(recordedA).toBeDefined(); - expect(recordedB).toBeDefined(); - const idA = - recordedA !== null && typeof recordedA === "object" && "runId" in recordedA - ? recordedA.runId - : undefined; - const idB = - recordedB !== null && typeof recordedB === "object" && "runId" in recordedB - ? recordedB.runId - : undefined; - // Two executions, two runs. - expect(idA).toBeDefined(); - expect(idB).toBeDefined(); - expect(idA).not.toEqual(idB); - - // Each document read the run its own journal records — the sibling's - // preparation and completion changed neither. - expect(seenA[0]?.runId).toEqual(idA); - expect(seenB[0]?.runId).toEqual(idB); - // And every read inside one execution is the same frozen object. - expect(seenA[0]).toBe(seenA[1]); - - // Nothing leaked into a later ordinary execution. - let leaked: unknown; - yield* scoped(function* () { - yield* useForbiddenGit(); - yield* registerComponents([ - { - name: "Probe", - origin: "tier-wr", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn() { - try { - leaked = yield* getWorkflowRun(); - } catch { - leaked = "refused"; - } - return ""; + yield* prepared.operation; + + yield* scoped(function* () { + yield* useProbe(seenB); + yield* collect( + yield* executeInstalled({ ...inlineSource("\n"), stream: streamB }, [shared]), + ); + }); + + release.resolve(); + yield* first; + + const recordedA = recordedRun(streamA); + const recordedB = recordedRun(streamB); + expect(recordedA).toBeDefined(); + expect(recordedB).toBeDefined(); + const idA = + recordedA !== null && typeof recordedA === "object" && "runId" in recordedA + ? recordedA.runId + : undefined; + const idB = + recordedB !== null && typeof recordedB === "object" && "runId" in recordedB + ? recordedB.runId + : undefined; + // Two executions, two runs. + expect(idA).toBeDefined(); + expect(idB).toBeDefined(); + expect(idA).not.toEqual(idB); + + // Each document read the run its own journal records — the sibling's + // preparation and completion changed neither. + expect(seenA[0]?.runId).toEqual(idA); + expect(seenB[0]?.runId).toEqual(idB); + // And every read inside one execution is the same frozen object. + expect(seenA[0]).toBe(seenA[1]); + + // Nothing leaked into a later ordinary execution. + yield* captureTestJournal( + { owner: OWNER, name: sharedInstallation }, + "", + function* (ordinary) { + let leaked: unknown; + yield* scoped(function* () { + yield* useForbiddenGit(); + yield* registerComponents([ + { + name: "Probe", + origin: "tier-wr", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn() { + try { + leaked = yield* getWorkflowRun(); + } catch { + leaked = "refused"; + } + return ""; + }, + }, + ]); + yield* collect(yield* execute({ ...inlineSource("\n"), stream: ordinary })); + }); + expect(leaked).toEqual("refused"); }, - }, - ]); - yield* collect( - yield* execute({ ...inlineSource("\n"), stream: new InMemoryStream() }), - ); - }); - expect(leaked).toEqual("refused"); + ); + }, + ); }); it("WR4: a completed journal restores the run without consulting Git", function* () { @@ -443,80 +473,86 @@ describe("Tier WR — workflow runs", () => { expect(replay.snapshot().length).toEqual(recorded.length); }); - it("WR8: a run survives a document that fails after it was recorded", function* () { - const stream = new InMemoryStream(); - - const result = yield* scoped(function* () { - const workflow = runInstallation(); - return yield* yield* executeInstalled( - { - // A value root that produces no fails after expansion begins. - ...inlineSource("---\nreturns:\n type: object\n---\n\nbody\n"), - stream, - }, - [workflow], - ); - }); + journalCase( + "WR8: a run survives a document that fails after it was recorded", + "", + function* (stream) { + const result = yield* scoped(function* () { + const workflow = runInstallation(); + return yield* yield* executeInstalled( + { + // A value root that produces no fails after expansion begins. + ...inlineSource("---\nreturns:\n type: object\n---\n\nbody\n"), + stream, + }, + [workflow], + ); + }); - expect(result.ok).toBe(false); - expect(recordedRun(stream)).toEqual({ - runId: expect.any(String), - bundleHash: BUNDLE, - }); - }); + expect(result.ok).toBe(false); + expect(recordedRun(stream)).toEqual({ + runId: expect.any(String), + bundleHash: BUNDLE, + }); + }, + ); // Ordinary execution stays Git-independent: with no workflow middleware // installed, nothing reaches the process boundary looking for `git`. - it("WR9: an execution without a workflow installation never invokes Git", function* () { - const commands: string[][] = []; - - const output = yield* scoped(function* () { - yield* API.Process.around( - { - // deno-lint-ignore require-yield - *exec([options]) { - commands.push(options.command); - throw new Error(`the run executed ${options.command[0]}`); + journalCase( + "WR9: an execution without a workflow installation never invokes Git", + "", + function* (stream) { + const commands: string[][] = []; + + const output = yield* scoped(function* () { + yield* API.Process.around( + { + // deno-lint-ignore require-yield + *exec([options]) { + commands.push(options.command); + throw new Error(`the run executed ${options.command[0]}`); + }, }, - }, - { at: "min" }, - ); - return yield* collect( - yield* execute({ ...inlineSource("# Hello\n"), stream: new InMemoryStream() }), - ); - }); + { at: "min" }, + ); + return yield* collect(yield* execute({ ...inlineSource("# Hello\n"), stream })); + }); - expect(String(output)).toContain("Hello"); - expect(commands).toHaveLength(0); - }); + expect(String(output)).toContain("Hello"); + expect(commands).toHaveLength(0); + }, + ); - it("WR10: getWorkflowRun() throws inside an execution that installed no workflow", function* () { - const failures: string[] = []; + journalCase( + "WR10: getWorkflowRun() throws inside an execution that installed no workflow", + "", + function* (stream) { + const failures: string[] = []; - yield* scoped(function* () { - yield* registerComponents([ - { - name: "Probe", - origin: "tier-wr", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn() { - try { - yield* getWorkflowRun(); - } catch (error) { - failures.push(error instanceof Error ? error.message : String(error)); - } - return ""; + yield* scoped(function* () { + yield* registerComponents([ + { + name: "Probe", + origin: "tier-wr", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn() { + try { + yield* getWorkflowRun(); + } catch (error) { + failures.push(error instanceof Error ? error.message : String(error)); + } + return ""; + }, }, - }, - ]); - yield* collect( - yield* execute({ ...inlineSource("\n"), stream: new InMemoryStream() }), - ); - }); + ]); + yield* collect(yield* execute({ ...inlineSource("\n"), stream })); + }); - expect(failures).toHaveLength(1); - expect(failures[0]).toContain("run installation"); - }); + expect(failures).toHaveLength(1); + expect(failures[0]).toContain("run installation"); + }, + ); it("WR11: a journal holding something else under the workflow name is refused", function* () { const stream = new InMemoryStream(); @@ -612,9 +648,63 @@ describe("Tier WR — workflow runs", () => { // The expansion identifier is derived from the document alone. A workflow run // pairs with it for workflow-wide identity; it never enters the derivation. - it("WR15: expansion identifiers do not move with the workflow run", function* () { - function* ids(bundleHash?: string): Operation { - const seen: string[] = []; + const expansionIdentity = "WR15: expansion identifiers do not move with the workflow run"; + journalCase(expansionIdentity, "", function* (ordinary) { + yield* captureTestJournal( + { owner: OWNER, name: expansionIdentity }, + "", + function* (first) { + function* ids(stream: InMemoryStream, bundleHash?: string): Operation { + const seen: string[] = []; + yield* scoped(function* () { + yield* registerComponents([ + { + name: "Probe", + origin: "tier-wr", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn() { + seen.push((yield* getExpansion()).id); + return ""; + }, + }, + ]); + const workflow = bundleHash === undefined ? undefined : runInstallation(bundleHash); + yield* collect( + yield* executeInstalled( + { ...inlineSource("\n"), stream }, + workflow === undefined ? [] : [workflow], + ), + ); + }); + return seen; + } + + const withoutWorkflow = yield* ids(ordinary); + const firstRun = yield* ids(first); + yield* captureTestJournal( + { owner: OWNER, name: expansionIdentity }, + "", + function* (second) { + const secondRun = yield* ids(second); + + expect(withoutWorkflow).toHaveLength(1); + expect(firstRun).toEqual(withoutWorkflow); + expect(secondRun).toEqual(withoutWorkflow); + }, + ); + }, + ); + }); + + journalCase( + "WR16: cancelling a document execution does not erase a recorded run", + "", + function* (stream) { + // The component says when it has observed the recorded run, so the + // cancellation lands after that point by construction rather than by + // winning a race against a timer. + const observed = withResolvers(); + yield* scoped(function* () { yield* registerComponents([ { @@ -622,111 +712,75 @@ describe("Tier WR — workflow runs", () => { origin: "tier-wr", props: { type: "object", properties: {}, additionalProperties: false }, *fn() { - seen.push((yield* getExpansion()).id); + yield* getWorkflowRun(); + observed.resolve(); + // Held open, so the execution is still running when it is cancelled. + yield* suspend(); return ""; }, }, ]); - const workflow = bundleHash === undefined ? undefined : runInstallation(bundleHash); - yield* collect( - yield* executeInstalled( - { ...inlineSource("\n"), stream: new InMemoryStream() }, - workflow === undefined ? [] : [workflow], - ), - ); + const workflow = runInstallation(); + + const execution = yield* spawn(function* () { + yield* collect( + yield* executeInstalled({ ...inlineSource("\n"), stream }, [workflow]), + ); + }); + yield* observed.operation; + yield* execution.halt(); }); - return seen; - } - - const withoutWorkflow = yield* ids(); - const firstRun = yield* ids(BUNDLE); - const secondRun = yield* ids(OTHER_BUNDLE); - expect(withoutWorkflow).toHaveLength(1); - expect(firstRun).toEqual(withoutWorkflow); - expect(secondRun).toEqual(withoutWorkflow); - }); + expect(recordedRun(stream)).toEqual({ + runId: expect.any(String), + bundleHash: BUNDLE, + }); + }, + ); - it("WR16: cancelling a document execution does not erase a recorded run", function* () { - const stream = new InMemoryStream(); - // The component says when it has observed the recorded run, so the - // cancellation lands after that point by construction rather than by - // winning a race against a timer. - const observed = withResolvers(); + // `run.ts` makes the same loaded-copy claim core does: a second copy of this + // package reads the run through its own descriptor of the same context name. + journalCase( + "WR17: a descriptor of the same name built elsewhere reads the run", + "", + function* (stream) { + // The binding is the execution's own slot, and what it holds is the exact + // frozen run. Retained-history admission and durable preparation both + // decide the run from outside the scope that reads it, so a context set + // from either would end with the operation that set it; the slot is what + // gives them somewhere to put it that the document can still see. + let own: WorkflowRun | undefined; + let observed: unknown; + const elsewhere = createContext("executablemd.workflow.run", undefined); - yield* scoped(function* () { - yield* registerComponents([ - { - name: "Probe", - origin: "tier-wr", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn() { - yield* getWorkflowRun(); - observed.resolve(); - // Held open, so the execution is still running when it is cancelled. - yield* suspend(); - return ""; + yield* scoped(function* () { + yield* registerComponents([ + { + name: "Probe", + origin: "tier-wr", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn() { + own = yield* getWorkflowRun(); + observed = yield* elsewhere.get(); + return ""; + }, }, - }, - ]); - const workflow = runInstallation(); - - const execution = yield* spawn(function* () { + ]); + const workflow = runInstallation(); yield* collect( yield* executeInstalled({ ...inlineSource("\n"), stream }, [workflow]), ); }); - yield* observed.operation; - yield* execution.halt(); - }); - - expect(recordedRun(stream)).toEqual({ - runId: expect.any(String), - bundleHash: BUNDLE, - }); - }); - - // `run.ts` makes the same loaded-copy claim core does: a second copy of this - // package reads the run through its own descriptor of the same context name. - it("WR17: a descriptor of the same name built elsewhere reads the run", function* () { - // The binding is the execution's own slot, and what it holds is the exact - // frozen run. Retained-history admission and durable preparation both - // decide the run from outside the scope that reads it, so a context set - // from either would end with the operation that set it; the slot is what - // gives them somewhere to put it that the document can still see. - let own: WorkflowRun | undefined; - let observed: unknown; - const elsewhere = createContext("executablemd.workflow.run", undefined); - yield* scoped(function* () { - yield* registerComponents([ - { - name: "Probe", - origin: "tier-wr", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn() { - own = yield* getWorkflowRun(); - observed = yield* elsewhere.get(); - return ""; - }, - }, - ]); - const workflow = runInstallation(); - yield* collect( - yield* executeInstalled({ ...inlineSource("\n"), stream: new InMemoryStream() }, [ - workflow, - ]), - ); - }); - - expect(own).toBeDefined(); - expect(observed).toBeDefined(); - const carried = - observed !== null && typeof observed === "object" && "run" in observed - ? observed.run - : undefined; - expect(carried).toBe(own); - }); + expect(own).toBeDefined(); + expect(observed).toBeDefined(); + const carried = + observed !== null && typeof observed === "object" && "run" in observed + ? observed.run + : undefined; + expect(carried).toBe(own); + }, + ); /** * A descriptor of the Api's name whose `document` may return anything. @@ -753,122 +807,129 @@ describe("Tier WR — workflow runs", () => { * what happens instead. */ - it("WM1: a non-delegating document handler cannot fabricate a successful run", function* () { - const journal = new InMemoryStream(); - const seen: WorkflowRun[] = []; + journalCase( + "WM1: a non-delegating document handler cannot fabricate a successful run", + "", + function* (stream) { + const seen: WorkflowRun[] = []; - const result = yield* scoped(function* () { - yield* useProbe(seen); - yield* loose().around({ - // deno-lint-ignore require-yield - *document() { - return { status: "ok", output: "FABRICATED", value: "FABRICATED" }; - }, + const result = yield* scoped(function* () { + yield* useProbe(seen); + yield* loose().around({ + // deno-lint-ignore require-yield + *document() { + return { status: "ok", output: "FABRICATED", value: "FABRICATED" }; + }, + }); + return yield* yield* executeInstalled({ ...inlineSource("\n"), stream }, [ + runInstallation(), + ]); }); - return yield* yield* executeInstalled({ ...inlineSource("\n"), stream: journal }, [ - runInstallation(), - ]); - }); - - // The handler decided nothing. Core refused it. - expect(result.ok).toBe(false); - expect(seen).toEqual([]); - // The run was prepared before that handler ever ran, so the journal holds - // the canonical record — and then the failed terminal, never a success - // carrying "FABRICATED". - expect(recordedRun(journal)).toBeDefined(); - expect(JSON.stringify(journal.snapshot())).not.toContain("FABRICATED"); - const closes = journal.snapshot().filter((event) => event.type === "close"); - expect(closes.length).toEqual(1); - }); - it("WM2: a substitute result after delegating replaces nothing", function* () { - const journal = new InMemoryStream(); - const seen: WorkflowRun[] = []; + // The handler decided nothing. Core refused it. + expect(result.ok).toBe(false); + expect(seen).toEqual([]); + // The run was prepared before that handler ever ran, so the journal holds + // the canonical record — and then the failed terminal, never a success + // carrying "FABRICATED". + expect(recordedRun(stream)).toBeDefined(); + expect(JSON.stringify(stream.snapshot())).not.toContain("FABRICATED"); + const closes = stream.snapshot().filter((event) => event.type === "close"); + expect(closes.length).toEqual(1); + }, + ); - const output = yield* scoped(function* () { - yield* useProbe(seen); - yield* loose().around({ - *document([request], next) { - yield* next(request); - return { status: "ok", output: "SUBSTITUTE", value: "SUBSTITUTE" }; - }, + journalCase( + "WM2: a substitute result after delegating replaces nothing", + "", + function* (stream) { + const seen: WorkflowRun[] = []; + + const output = yield* scoped(function* () { + yield* useProbe(seen); + yield* loose().around({ + *document([request], next) { + yield* next(request); + return { status: "ok", output: "SUBSTITUTE", value: "SUBSTITUTE" }; + }, + }); + return yield* collect( + yield* executeInstalled({ ...inlineSource("\n"), stream }, [runInstallation()]), + ); }); - return yield* collect( - yield* executeInstalled({ ...inlineSource("\n"), stream: journal }, [ - runInstallation(), - ]), - ); - }); - expect(String(output)).not.toContain("SUBSTITUTE"); - expect(seen.length).toEqual(1); - expect(recordedRun(journal)).toBeDefined(); - }); + expect(String(output)).not.toContain("SUBSTITUTE"); + expect(seen.length).toEqual(1); + expect(recordedRun(stream)).toBeDefined(); + }, + ); - it("WM3: the run is prepared before any document policy observes it", function* () { - const order: string[] = []; - const journal = new InMemoryStream(); + journalCase( + "WM3: the run is prepared before any document policy observes it", + "", + function* (stream) { + const order: string[] = []; - yield* scoped(function* () { - yield* registerComponents([ - { - name: "Probe", - origin: "tier-wr", - props: { type: "object", properties: {}, additionalProperties: false }, - *fn() { - order.push(`expanded:${(yield* getWorkflowRun()).bundleHash === BUNDLE}`); - return ""; + yield* scoped(function* () { + yield* registerComponents([ + { + name: "Probe", + origin: "tier-wr", + props: { type: "object", properties: {}, additionalProperties: false }, + *fn() { + order.push(`expanded:${(yield* getWorkflowRun()).bundleHash === BUNDLE}`); + return ""; + }, }, - }, - ]); - yield* Execution.around({ - *document([request], next) { - // The record is already in the journal by the time policy runs. - order.push(`policy:${workflowEvents(journal).length}`); - yield* next(request); - }, + ]); + yield* Execution.around({ + *document([request], next) { + // The record is already in the journal by the time policy runs. + order.push(`policy:${workflowEvents(stream).length}`); + yield* next(request); + }, + }); + yield* collect( + yield* executeInstalled({ ...inlineSource("\n"), stream }, [runInstallation()]), + ); }); - yield* collect( - yield* executeInstalled({ ...inlineSource("\n"), stream: journal }, [ - runInstallation(), - ]), - ); - }); - expect(order).toEqual(["policy:1", "expanded:true"]); - }); + expect(order).toEqual(["policy:1", "expanded:true"]); + }, + ); - it("WM4: an installation another loaded copy built composes when the host passes it", function* () { - const seen: WorkflowRun[] = []; - const journal = new InMemoryStream(); - - // Built through this package's own constructor, then relayed to canonical - // core as an opaque record of closures — which is exactly how a separately - // loaded copy reaches core: it hands over functions, and nobody agrees on - // a name or a type. - const built = runInstallation(); - const relayed: ExecutionInstallation = { - admissions: built.admissions, - prepare: built.prepare, - install: built.install, - }; + journalCase( + "WM4: an installation another loaded copy built composes when the host passes it", + "", + function* (stream) { + const seen: WorkflowRun[] = []; + + // Built through this package's own constructor, then relayed to canonical + // core as an opaque record of closures — which is exactly how a separately + // loaded copy reaches core: it hands over functions, and nobody agrees on + // a name or a type. + const built = runInstallation(); + const relayed: ExecutionInstallation = { + admissions: built.admissions, + prepare: built.prepare, + install: built.install, + }; - yield* scoped(function* () { - yield* useProbe(seen); - yield* collect( - yield* executeInstalled({ ...inlineSource("\n"), stream: journal }, [relayed]), - ); - }); + yield* scoped(function* () { + yield* useProbe(seen); + yield* collect( + yield* executeInstalled({ ...inlineSource("\n"), stream }, [relayed]), + ); + }); - expect(seen.length).toEqual(1); - expect(recordedRun(journal)).toBeDefined(); - }); + expect(seen.length).toEqual(1); + expect(recordedRun(stream)).toBeDefined(); + }, + ); - it("WM5: valid public observation still composes", function* () { + journalCase("WM5: valid public observation still composes", "", function* (stream) { const observed: string[] = []; const seen: WorkflowRun[] = []; - const journal = new InMemoryStream(); const output = yield* scoped(function* () { yield* useProbe(seen); @@ -880,16 +941,14 @@ describe("Tier WR — workflow runs", () => { }, }); return yield* collect( - yield* executeInstalled({ ...inlineSource("\n"), stream: journal }, [ - runInstallation(), - ]), + yield* executeInstalled({ ...inlineSource("\n"), stream }, [runInstallation()]), ); }); expect(observed).toEqual(["before", "after"]); expect(seen.length).toEqual(1); expect(String(output).trim()).toEqual(""); - expect(recordedRun(journal)).toBeDefined(); + expect(recordedRun(stream)).toBeDefined(); }); /** @@ -902,45 +961,48 @@ describe("Tier WR — workflow runs", () => { * published — so this preparation reaches no Git at all, and the journal is * still held to it before the document is imported. */ - it("WR21: a host preparation allocates the run, and this package records it", function* () { - const seen: WorkflowRun[] = []; - const stream = new InMemoryStream(); - const allocations: string[] = []; + journalCase( + "WR21: a host preparation allocates the run, and this package records it", + "", + function* (stream) { + const seen: WorkflowRun[] = []; + const allocations: string[] = []; - yield* scoped(function* () { - // Nothing about this preparation resolves a revision, and Git fails the - // test if the constructor reaches it on its own account. - yield* useForbiddenGit(); - yield* useProbe(seen); - yield* collect( - yield* executeInstalled({ ...inlineSource("\n"), stream }, [ - createWorkflowRunInstallation({ - description: { type: WORKFLOW_RUN, name: WORKFLOW_RUN, bundleHash: BUNDLE }, - required: false, - // deno-lint-ignore require-yield - *allocate(): Operation { - allocations.push("allocated"); - return { runId: "host-allocated", bundleHash: BUNDLE }; - }, - agree: (recorded) => recorded, - }), - ]), - ); - }); + yield* scoped(function* () { + // Nothing about this preparation resolves a revision, and Git fails the + // test if the constructor reaches it on its own account. + yield* useForbiddenGit(); + yield* useProbe(seen); + yield* collect( + yield* executeInstalled({ ...inlineSource("\n"), stream }, [ + createWorkflowRunInstallation({ + description: { type: WORKFLOW_RUN, name: WORKFLOW_RUN, bundleHash: BUNDLE }, + required: false, + // deno-lint-ignore require-yield + *allocate(): Operation { + allocations.push("allocated"); + return { runId: "host-allocated", bundleHash: BUNDLE }; + }, + agree: (recorded) => recorded, + }), + ]), + ); + }); - expect(allocations).toEqual(["allocated"]); - expect(seen).toHaveLength(1); - expect(seen[0]).toEqual({ - runId: "host-allocated", - bundleHash: BUNDLE, - }); - // Recorded under this package's canonical identity, from the host's own - // description — which is what makes it the record a later run is held to. - expect(recordedRun(stream)).toEqual({ - runId: "host-allocated", - bundleHash: BUNDLE, - }); - }); + expect(allocations).toEqual(["allocated"]); + expect(seen).toHaveLength(1); + expect(seen[0]).toEqual({ + runId: "host-allocated", + bundleHash: BUNDLE, + }); + // Recorded under this package's canonical identity, from the host's own + // description — which is what makes it the record a later run is held to. + expect(recordedRun(stream)).toEqual({ + runId: "host-allocated", + bundleHash: BUNDLE, + }); + }, + ); it("WR22: a host preparation's agreement decides a retained history", function* () { const stream = new InMemoryStream(); From 5e93fa63568de196e772a4671cb40de5739d522d Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:31:43 -0500 Subject: [PATCH 39/78] test: preserve both workflow inputs in identity comparison --- packages/workflow/tests/workflow-run.test.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/workflow/tests/workflow-run.test.ts b/packages/workflow/tests/workflow-run.test.ts index fcf5ccfc3..6648fb5b2 100644 --- a/packages/workflow/tests/workflow-run.test.ts +++ b/packages/workflow/tests/workflow-run.test.ts @@ -680,12 +680,12 @@ describe("Tier WR — workflow runs", () => { } const withoutWorkflow = yield* ids(ordinary); - const firstRun = yield* ids(first); + const firstRun = yield* ids(first, BUNDLE); yield* captureTestJournal( { owner: OWNER, name: expansionIdentity }, "", function* (second) { - const secondRun = yield* ids(second); + const secondRun = yield* ids(second, OTHER_BUNDLE); expect(withoutWorkflow).toHaveLength(1); expect(firstRun).toEqual(withoutWorkflow); From 5289ed504e32570f265139d971a84b60bc9595ae Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 15:33:11 -0500 Subject: [PATCH 40/78] test: attribute fresh Core execution and comparison owners --- .../core/tests/code-block-component.test.ts | 173 ++-- packages/core/tests/execute.test.ts | 775 ++++++++++-------- packages/core/tests/parse-components.test.ts | 181 ++-- packages/core/tests/root-composition.test.ts | 132 +-- 4 files changed, 699 insertions(+), 562 deletions(-) diff --git a/packages/core/tests/code-block-component.test.ts b/packages/core/tests/code-block-component.test.ts index a9003c0a5..de589637d 100644 --- a/packages/core/tests/code-block-component.test.ts +++ b/packages/core/tests/code-block-component.test.ts @@ -1,3 +1,4 @@ +import { captureTestJournal } from "../../test-support/failure-journal.ts"; /** * Tier CB — `` (spec §6.19). * @@ -36,7 +37,8 @@ import { registerComponents } from "../src/components/registration.ts"; import type { Json } from "../src/types.ts"; import { journalCases } from "../../test-support/journal-cases.ts"; -const journalCase = journalCases("packages/core/tests/code-block-component.test.ts"); +const OWNER = "packages/core/tests/code-block-component.test.ts"; +const journalCase = journalCases(OWNER); interface Run { /** Everything the document emitted, before any output middleware. */ @@ -147,20 +149,30 @@ function* captured( } describe("Tier CB — the envelope", () => { - it("CB1: an empty value is three backticks, two line feeds and nothing else", function* () { - const result = yield* directly(undefined, ""); + const emptyValue = "CB1: an empty value is three backticks, two line feeds and nothing else"; + journalCase(emptyValue, "doc.md", function* (stream) { + yield* captureTestJournal({ owner: OWNER, name: emptyValue }, "doc.md", function* (compared) { + const result = yield* directly(stream, ""); - expect(result.failure).toBe(""); - expect(result.output).toBe("```\n\n```"); - expect(yield* captured(undefined, "")).toBe("```\n\n```"); + expect(result.failure).toBe(""); + expect(result.output).toBe("```\n\n```"); + expect(yield* captured(compared, "")).toBe("```\n\n```"); + }); }); - it("CB1: ordinary Markdown keeps its own lines, and gains no final line feed", function* () { - const value = "# Title\n\n- one\n- two"; - const result = yield* directly(undefined, value); - - expect(result.output).toBe("```\n# Title\n\n- one\n- two\n```"); - expect(yield* captured(undefined, value)).toBe("```\n# Title\n\n- one\n- two\n```"); + const markdownValue = "CB1: ordinary Markdown keeps its own lines, and gains no final line feed"; + journalCase(markdownValue, "doc.md", function* (stream) { + yield* captureTestJournal( + { owner: OWNER, name: markdownValue }, + "doc.md", + function* (compared) { + const value = "# Title\n\n- one\n- two"; + const result = yield* directly(stream, value); + + expect(result.output).toBe("```\n# Title\n\n- one\n- two\n```"); + expect(yield* captured(compared, value)).toBe("```\n# Title\n\n- one\n- two\n```"); + }, + ); }); journalCase("CB1: the block lands where the element was written", "doc.md", function* (stream) { @@ -178,7 +190,8 @@ describe("Tier CB — the envelope", () => { }); describe("Tier CB — the fence the value cannot close", () => { - it("CB2: the fence is the longest backtick run plus one, never fewer than three", function* () { + const fenceCase = "CB2: the fence is the longest backtick run plus one, never fewer than three"; + it(fenceCase, function* () { const cases: ReadonlyArray = [ ["no backticks at all", 3], ["one ` here", 3], @@ -193,48 +206,57 @@ describe("Tier CB — the fence the value cannot close", () => { ]; for (const [value, length] of cases) { - const block = yield* captured(undefined, value); - const fence = "`".repeat(length); - - expect(block).toBe(`${fence}\n${value}\n${fence}`); - // Stated twice on purpose: the complete string pins the layout, and this - // pins the count the layout was built from. - expect(block.split("\n")[0]?.length).toBe(length); + yield* captureTestJournal({ owner: OWNER, name: fenceCase }, "doc.md", function* (stream) { + const block = yield* captured(stream, value); + const fence = "`".repeat(length); + + expect(block).toBe(`${fence}\n${value}\n${fence}`); + // Stated twice on purpose: the complete string pins the layout, and this + // pins the count the layout was built from. + expect(block.split("\n")[0]?.length).toBe(length); + }); } }); - it("CB2: a run broken by any other character is two runs, not one", function* () { - // Counting backticks without resetting would read five here and open a - // six-backtick fence. - expect(yield* captured(undefined, "```\n``")).toBe("````\n```\n``\n````"); - expect(yield* captured(undefined, "``x``x``")).toBe("```\n``x``x``\n```"); + const brokenRun = "CB2: a run broken by any other character is two runs, not one"; + journalCase(brokenRun, "doc.md", function* (stream) { + yield* captureTestJournal({ owner: OWNER, name: brokenRun }, "doc.md", function* (compared) { + // Counting backticks without resetting would read five here and open a + // six-backtick fence. + expect(yield* captured(stream, "```\n``")).toBe("````\n```\n``\n````"); + expect(yield* captured(compared, "``x``x``")).toBe("```\n``x``x``\n```"); + }); }); }); describe("Tier CB — the value is not read for anything else", () => { - it("CB3: removing the envelope recovers the source code units exactly", function* () { - const value = [ - " leading spaces", - "\ttab indented", - "", - "", - "carriage\r\nreturn line", - "`` two `````` six", - "trailing spaces ", - ].join("\n"); - const block = yield* captured(undefined, value); - - // The value's longest run is six backticks, so the fence is seven. - const fence = "`".repeat(7); - expect(block.startsWith(`${fence}\n`)).toBe(true); - expect(block.endsWith(`\n${fence}`)).toBe(true); - - const recovered = block.slice(fence.length + 1, block.length - fence.length - 1); - expect(recovered.length).toBe(value.length); - for (let index = 0; index < value.length; index += 1) { - expect(recovered.charCodeAt(index)).toBe(value.charCodeAt(index)); - } - }); + journalCase( + "CB3: removing the envelope recovers the source code units exactly", + "doc.md", + function* (stream) { + const value = [ + " leading spaces", + "\ttab indented", + "", + "", + "carriage\r\nreturn line", + "`` two `````` six", + "trailing spaces ", + ].join("\n"); + const block = yield* captured(stream, value); + + // The value's longest run is six backticks, so the fence is seven. + const fence = "`".repeat(7); + expect(block.startsWith(`${fence}\n`)).toBe(true); + expect(block.endsWith(`\n${fence}`)).toBe(true); + + const recovered = block.slice(fence.length + 1, block.length - fence.length - 1); + expect(recovered.length).toBe(value.length); + for (let index = 0; index < value.length; index += 1) { + expect(recovered.charCodeAt(index)).toBe(value.charCodeAt(index)); + } + }, + ); }); describe("Tier CB — the language token", () => { @@ -246,18 +268,26 @@ describe("Tier CB — the language token", () => { }, ); - it("CB4: every accepted token renders on the opening fence, unchanged", function* () { + const acceptedLanguage = "CB4: every accepted token renders on the opening fence, unchanged"; + it(acceptedLanguage, function* () { const accepted = ["markdown", "md", "json", "shell-session", "c++", "c#", "F", "x1._+#-"]; for (const language of accepted) { - const result = yield* directly(undefined, "body", ` language="${language}"`); - - expect(result.failure).toBe(""); - expect(result.output).toBe("```" + language + "\nbody\n```"); + yield* captureTestJournal( + { owner: OWNER, name: acceptedLanguage }, + "doc.md", + function* (stream) { + const result = yield* directly(stream, "body", ` language="${language}"`); + + expect(result.failure).toBe(""); + expect(result.output).toBe("```" + language + "\nbody\n```"); + }, + ); } }); - it("CB4: a refused token fails validation and renders no fence", function* () { + const refusedLanguage = "CB4: a refused token fails validation and renders no fence"; + it(refusedLanguage, function* () { const refused = [ "", " ", @@ -283,16 +313,22 @@ describe("Tier CB — the language token", () => { ]; for (const language of refused) { - const result = yield* run( - undefined, - '', - { v: "body", lang: language }, + yield* captureTestJournal( + { owner: OWNER, name: refusedLanguage }, + "doc.md", + function* (stream) { + const result = yield* run( + stream, + '', + { v: "body", lang: language }, + ); + + expect(reported(result)).toContain("Prop validation failed for "); + expect(reported(result)).toContain("language"); + expect(result.output).not.toContain("```"); + expect(result.output).not.toContain("body"); + }, ); - - expect(reported(result)).toContain("Prop validation failed for "); - expect(reported(result)).toContain("language"); - expect(result.output).not.toContain("```"); - expect(result.output).not.toContain("body"); } }); }); @@ -310,12 +346,15 @@ describe("Tier CB — the invocation is refused before the body", () => { }, ); - it("CB5: a non-string value is refused rather than coerced", function* () { + const nonString = "CB5: a non-string value is refused rather than coerced"; + it(nonString, function* () { for (const value of ["42", "true", "null", "{ text: 'x' }", "['x']"]) { - const result = yield* run(undefined, ``); + yield* captureTestJournal({ owner: OWNER, name: nonString }, "doc.md", function* (stream) { + const result = yield* run(stream, ``); - expect(reported(result)).toContain("Prop validation failed for "); - expect(result.output).not.toContain("```"); + expect(reported(result)).toContain("Prop validation failed for "); + expect(result.output).not.toContain("```"); + }); } }); diff --git a/packages/core/tests/execute.test.ts b/packages/core/tests/execute.test.ts index a07ec4061..60362a9fa 100644 --- a/packages/core/tests/execute.test.ts +++ b/packages/core/tests/execute.test.ts @@ -1,3 +1,4 @@ +import { captureTestJournal } from "../../test-support/failure-journal.ts"; /** * Integration tests for execute (Tiers B, D, E from spec §11). * @@ -28,7 +29,8 @@ import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import { asText } from "./helpers.ts"; import { journalCases } from "../../test-support/journal-cases.ts"; -const journalCase = journalCases("packages/core/tests/execute.test.ts"); +const OWNER = "packages/core/tests/execute.test.ts"; +const journalCase = journalCases(OWNER); /** * A stand-in child that behaves like one: it writes its output to the display @@ -117,37 +119,40 @@ function* useFailingStdoutExec(): Operation { describe("Tier B — durable import", () => { // B1: durableImportComponent golden run — journal shape - it("B1: import golden run — journal has import_component with path and content", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ "README.md": "Hello world\n" }); - yield* useStubExec(); + journalCase( + "B1: import golden run — journal has import_component with path and content", + "README.md", + function* (stream) { + yield* useStubFs({ "README.md": "Hello world\n" }); + yield* useStubExec(); - yield* collect( - yield* execute({ - path: "README.md", - stream, - }), - ); + yield* collect( + yield* execute({ + path: "README.md", + stream, + }), + ); - const events = stream.snapshot(); - const imports = events.flatMap((e) => - e.type === "yield" && e.description.type === "import_component" ? [e] : [], - ); + const events = stream.snapshot(); + const imports = events.flatMap((e) => + e.type === "yield" && e.description.type === "import_component" ? [e] : [], + ); - expect(imports.length).toBe(1); + expect(imports.length).toBe(1); - const rootImport = imports[0]!; - expect(rootImport).toMatchObject({ - type: "yield", - description: { name: "__root__" }, - result: { status: "ok", value: { path: "README.md" } }, - }); + const rootImport = imports[0]!; + expect(rootImport).toMatchObject({ + type: "yield", + description: { name: "__root__" }, + result: { status: "ok", value: { path: "README.md" } }, + }); - const result = rootImport.result; - expect(result.status).toBe("ok"); - const value = (result as { status: "ok"; value: Record }).value; - expect(value.content).toContain("Hello world"); - }); + const result = rootImport.result; + expect(result.status).toBe("ok"); + const value = (result as { status: "ok"; value: Record }).value; + expect(value.content).toContain("Hello world"); + }, + ); // B2: durableImportComponent replay — stored result returned, no I/O it("B2: import replay — stored result returned, no file read", function* () { @@ -227,8 +232,7 @@ describe("Tier B — durable import", () => { ); // B12: root document as component — __root__ import, same journal shape - it("B12: root document imported as __root__", function* () { - const stream = new InMemoryStream(); + journalCase("B12: root document imported as __root__", "doc.md", function* (stream) { yield* useStubFs({ "doc.md": "Root content\n" }); yield* useStubExec(); @@ -253,39 +257,42 @@ describe("Tier B — durable import", () => { }); // B13: dotted name resolution — Ns.Sub → components/Ns/Sub.md - it("B13: dotted component name resolves to nested path", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": "\n", - "components/Ui/Button.md": "Click me\n", - }); - yield* useStubExec(); + journalCase( + "B13: dotted component name resolves to nested path", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": "\n", + "components/Ui/Button.md": "Click me\n", + }); + yield* useStubExec(); - const result = asText( - yield* collect( - yield* execute({ - path: "README.md", - stream, - }), - ), - ); + const result = asText( + yield* collect( + yield* execute({ + path: "README.md", + stream, + }), + ), + ); - expect(result).toContain("Click me"); + expect(result).toContain("Click me"); - const events = stream.snapshot(); - const [compImport] = events.flatMap((e) => - e.type === "yield" && - e.description.type === "import_component" && - e.description.name === "Ui.Button" - ? [e] - : [], - ); - expect(compImport).toBeTruthy(); - expect(compImport!.result).toMatchObject({ - status: "ok", - value: { path: "components/Ui/Button.md" }, - }); - }); + const events = stream.snapshot(); + const [compImport] = events.flatMap((e) => + e.type === "yield" && + e.description.type === "import_component" && + e.description.name === "Ui.Button" + ? [e] + : [], + ); + expect(compImport).toBeTruthy(); + expect(compImport!.result).toMatchObject({ + status: "ok", + value: { path: "components/Ui/Button.md" }, + }); + }, + ); // B15: default resolver middleware — resolves via stat in search path order journalCase("B15: resolver searches component dirs in order", "README.md", function* (stream) { @@ -312,31 +319,34 @@ describe("Tier B — durable import", () => { describe("Tier D — code execution and modifiers", () => { // D1: bash exec golden run - it("D1: bash exec golden run — stdout displayed, exec in journal", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": ["```bash exec", "echo hello", "```"].join("\n"), - }); - yield* useStubExec(); + journalCase( + "D1: bash exec golden run — stdout displayed, exec in journal", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": ["```bash exec", "echo hello", "```"].join("\n"), + }); + yield* useStubExec(); - const run = yield* displayed(function* () { - return asText(yield* collect(yield* execute({ path: "README.md", stream }))); - }); - const result = run.value; + const run = yield* displayed(function* () { + return asText(yield* collect(yield* execute({ path: "README.md", stream }))); + }); + const result = run.value; - // A foreground block's output reached the reader as it ran, and the - // document does not say it again (#441). - expect(run.stdout).toContain("hello"); - expect(result).not.toContain("hello"); + // A foreground block's output reached the reader as it ran, and the + // document does not say it again (#441). + expect(run.stdout).toContain("hello"); + expect(result).not.toContain("hello"); - const events = stream.snapshot(); - const [execEvent] = events.flatMap((e) => - e.type === "yield" && e.description.type === "exec" ? [e] : [], - ); - expect(execEvent).toBeTruthy(); - expect(Array.isArray(execEvent!.description.command)).toBeTruthy(); - expect(execEvent!.result.status).toBe("ok"); - }); + const events = stream.snapshot(); + const [execEvent] = events.flatMap((e) => + e.type === "yield" && e.description.type === "exec" ? [e] : [], + ); + expect(execEvent).toBeTruthy(); + expect(Array.isArray(execEvent!.description.command)).toBeTruthy(); + expect(execEvent!.result.status).toBe("ok"); + }, + ); // D2: exec replay — command not re-executed it("D2: exec replay — stored stdout used, no re-execution", function* () { @@ -409,9 +419,8 @@ describe("Tier D — code execution and modifiers", () => { ); // D4: multi-line command — full script passed to -c - it("D4: multi-line command — full script in journal", function* () { + journalCase("D4: multi-line command — full script in journal", "README.md", function* (stream) { const multiLineScript = "echo line1\necho line2"; - const stream = new InMemoryStream(); yield* useStubFs({ "README.md": ["```bash exec", multiLineScript, "```"].join("\n"), }); @@ -437,12 +446,11 @@ describe("Tier D — code execution and modifiers", () => { }); // D5: python exec — python -c invocation - it("D5: python exec — python -c in command array", function* () { + journalCase("D5: python exec — python -c in command array", "README.md", function* (stream) { const files: Record = { "README.md": ["```python exec", "print('hello')", "```"].join("\n"), }; - const stream = new InMemoryStream(); yield* useStubFs(files); // Custom exec middleware that handles python -c yield* API.Process.around({ @@ -474,30 +482,33 @@ describe("Tier D — code execution and modifiers", () => { }); // D6: bash silent exec — chain: silent wraps exec, exec journals, silent returns empty - it("D6: bash silent exec — exec journals, output suppressed", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": ["```bash silent exec", "echo secret", "```"].join("\n"), - }); - yield* useStubExec(); + journalCase( + "D6: bash silent exec — exec journals, output suppressed", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": ["```bash silent exec", "echo secret", "```"].join("\n"), + }); + yield* useStubExec(); - const result = asText( - yield* collect( - yield* execute({ - path: "README.md", - stream, - }), - ), - ); + const result = asText( + yield* collect( + yield* execute({ + path: "README.md", + stream, + }), + ), + ); - // Output should be empty (silent suppresses) - expect(result).not.toContain("secret"); + // Output should be empty (silent suppresses) + expect(result).not.toContain("secret"); - // Journal should still have exec event - const events = stream.snapshot(); - const execs = events.filter((e) => e.type === "yield" && e.description["type"] === "exec"); - expect(execs.length).toBe(1); - }); + // Journal should still have exec event + const events = stream.snapshot(); + const execs = events.filter((e) => e.type === "yield" && e.description["type"] === "exec"); + expect(execs.length).toBe(1); + }, + ); // D7: silent exec replay — still produces empty output from stored result it("D7: silent exec replay — still empty output", function* () { @@ -534,56 +545,62 @@ describe("Tier D — code execution and modifiers", () => { // D6b/D7b: `silent` suppresses output; it does not convert failure into // success (#307). The command's exit code and stderr are the chain's, so a // silenced failure is still a failure — with nothing of what it printed. - it("D6b: failing silent exec — output suppressed, failure still reported", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": ["```bash silent exec", "echo secret", "```"].join("\n"), - }); - yield* useFailingStdoutExec(); + journalCase( + "D6b: failing silent exec — output suppressed, failure still reported", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": ["```bash silent exec", "echo secret", "```"].join("\n"), + }); + yield* useFailingStdoutExec(); - const run = yield* displayed(function* () { - return yield* failure(function* () { - return yield* collect(yield* execute({ path: "README.md", stream })); + const run = yield* displayed(function* () { + return yield* failure(function* () { + return yield* collect(yield* execute({ path: "README.md", stream })); + }); }); - }); - // Silence hides both channels; it does not excuse the exit code. - expect(run.stdout).toBe(""); - expect(run.value).toContain("Command failed (exit 3): why"); - }); + // Silence hides both channels; it does not excuse the exit code. + expect(run.stdout).toBe(""); + expect(run.value).toContain("Command failed (exit 3): why"); + }, + ); - it("D6c: a failing silent exec in documentation aborts before the next block", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": [ - "```bash silent exec", - "echo secret", - "```", - "", - "```bash exec", - "echo later", - "```", - "", - "ok", - ].join("\n"), - }); - yield* useFailingStdoutExec(); + journalCase( + "D6c: a failing silent exec in documentation aborts before the next block", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": [ + "```bash silent exec", + "echo secret", + "```", + "", + "```bash exec", + "echo later", + "```", + "", + "ok", + ].join("\n"), + }); + yield* useFailingStdoutExec(); - const execution = yield* execute({ path: "README.md", stream }); - const chunks: string[] = []; - yield* forEach(function* (chunk: string) { - chunks.push(chunk); - }, execution.output); - const result = yield* execution; - - expect(result.ok).toBe(false); - expect(chunks.join("")).not.toContain("ok"); - // The later block never ran — only the silenced one reached the journal. - const execs = stream - .snapshot() - .filter((e) => e.type === "yield" && e.description["type"] === "exec"); - expect(execs.length).toBe(1); - }); + const execution = yield* execute({ path: "README.md", stream }); + const chunks: string[] = []; + yield* forEach(function* (chunk: string) { + chunks.push(chunk); + }, execution.output); + const result = yield* execution; + + expect(result.ok).toBe(false); + expect(chunks.join("")).not.toContain("ok"); + // The later block never ran — only the silenced one reached the journal. + const execs = stream + .snapshot() + .filter((e) => e.type === "yield" && e.description["type"] === "exec"); + expect(execs.length).toBe(1); + }, + ); it("D7b: replay preserves a silent failure rather than replaying success", function* () { const stream = new InMemoryStream(); @@ -720,68 +737,71 @@ describe("Tier D — code execution and modifiers", () => { describe("execute", () => { // E1: Full document golden run - it("E1: full document golden run — root + component + exec", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": [ - "---", - "title: My Project", - "---", - "", - "# {meta.title}", - "", - '', - "", - "```bash exec", - "ls ./src", - "```", - ].join("\n"), - "components/Greeting.md": [ - "---", - "emoji: hi", - "", - "props:", - " type: object", - " properties:", - " name:", - " type: string", - " required: [name]", - " additionalProperties: false", - "---", - "", - "{meta.emoji} Hello, {props.name}!", - ].join("\n"), - }); - yield* useStubExec(); + journalCase( + "E1: full document golden run — root + component + exec", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": [ + "---", + "title: My Project", + "---", + "", + "# {meta.title}", + "", + '', + "", + "```bash exec", + "ls ./src", + "```", + ].join("\n"), + "components/Greeting.md": [ + "---", + "emoji: hi", + "", + "props:", + " type: object", + " properties:", + " name:", + " type: string", + " required: [name]", + " additionalProperties: false", + "---", + "", + "{meta.emoji} Hello, {props.name}!", + ].join("\n"), + }); + yield* useStubExec(); - const run = yield* displayed(function* () { - return asText(yield* collect(yield* execute({ path: "README.md", stream }))); - }); - const result = run.value; + const run = yield* displayed(function* () { + return asText(yield* collect(yield* execute({ path: "README.md", stream }))); + }); + const result = run.value; - expect(result).toContain("# My Project"); - expect(result).toContain("hi Hello, world!"); - // The listing was displayed as it arrived, not rendered into the document. - expect(run.stdout).toContain("main.ts"); - expect(run.stdout).toContain("utils.ts"); + expect(result).toContain("# My Project"); + expect(result).toContain("hi Hello, world!"); + // The listing was displayed as it arrived, not rendered into the document. + expect(run.stdout).toContain("main.ts"); + expect(run.stdout).toContain("utils.ts"); - const events = stream.snapshot(); - expect(events.length).toBeGreaterThan(0); + const events = stream.snapshot(); + expect(events.length).toBeGreaterThan(0); - // Should have import_component events for root and Greeting - const imports = events.filter( - (e) => e.type === "yield" && e.description["type"] === "import_component", - ); - expect(imports.length).toBe(2); + // Should have import_component events for root and Greeting + const imports = events.filter( + (e) => e.type === "yield" && e.description["type"] === "import_component", + ); + expect(imports.length).toBe(2); - // Should have exec event - const execs = events.filter((e) => e.type === "yield" && e.description["type"] === "exec"); - expect(execs.length).toBe(1); + // Should have exec event + const execs = events.filter((e) => e.type === "yield" && e.description["type"] === "exec"); + expect(execs.length).toBe(1); - // Should have close event - const closes = events.filter((e) => e.type === "close"); - expect(closes.length).toBe(1); - }); + // Should have close event + const closes = events.filter((e) => e.type === "close"); + expect(closes.length).toBe(1); + }, + ); // E2: Full replay — zero file reads, zero exec calls it("E2: full replay — same output, no I/O", function* () { @@ -860,34 +880,37 @@ describe("execute", () => { }); // E8: Silent exec in full document - it("E8: silent exec — command runs, result journaled, output omitted", function* () { - const stream = new InMemoryStream(); - yield* useStubFs({ - "README.md": ["before", "", "```bash silent exec", "echo hidden", "```", "", "after"].join( - "\n", - ), - }); - yield* useStubExec(); + journalCase( + "E8: silent exec — command runs, result journaled, output omitted", + "README.md", + function* (stream) { + yield* useStubFs({ + "README.md": ["before", "", "```bash silent exec", "echo hidden", "```", "", "after"].join( + "\n", + ), + }); + yield* useStubExec(); - const result = asText( - yield* collect( - yield* execute({ - path: "README.md", - stream, - }), - ), - ); + const result = asText( + yield* collect( + yield* execute({ + path: "README.md", + stream, + }), + ), + ); - // Output should NOT contain the exec result - expect(result).not.toContain("hidden"); - expect(result).toContain("before"); - expect(result).toContain("after"); + // Output should NOT contain the exec result + expect(result).not.toContain("hidden"); + expect(result).toContain("before"); + expect(result).toContain("after"); - // But the journal should have the exec event - const events = stream.snapshot(); - const execs = events.filter((e) => e.type === "yield" && e.description["type"] === "exec"); - expect(execs.length).toBe(1); - }); + // But the journal should have the exec event + const events = stream.snapshot(); + const execs = events.filter((e) => e.type === "yield" && e.description["type"] === "exec"); + expect(execs.length).toBe(1); + }, + ); // Simple text document — no components, no exec journalCase("simple text document — passthrough", "README.md", function* (stream) { @@ -1145,8 +1168,7 @@ describe("execute", () => { }); // Multiple components — verify all are imported and expanded - it("multiple components — all imported and expanded", function* () { - const stream = new InMemoryStream(); + journalCase("multiple components — all imported and expanded", "README.md", function* (stream) { yield* useStubFs({ "README.md": "
\n