Skip to content

Commit 9c5ab10

Browse files
authored
Merge pull request #89 from taras/worktree-component-output
feat: component-declared output via <Output> (#88)
2 parents 35831ac + 7d07bd1 commit 9c5ab10

30 files changed

Lines changed: 2205 additions & 1422 deletions

‎AGENTS.md‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,34 @@ Do not commit if any check fails. Fix the issue first, then re-run all three.
3131
language in specifications or source code.
3232
6. Parse to infer type; Do not type cast with `as`.
3333
7. Do not use braceless `if` statements.
34+
8. Keep the release spec current — changes to the release configuration
35+
require changes to specs/release-process-spec.md to match.
36+
9. Prefer stateless generators - use a function when calling a function that
37+
returns an operation; Do not do this function*(arg) { return yield* generator(arg) }
3438

3539
## PR Process
3640

3741
1. Use .github/pull_request_template.md
38-
2. After PR is open, monitor PR for
42+
2. After PR is open, monitor PR for
3943
1. CI failures
4044
2. Comments with feedback
41-
3. Integrate changes feedback appears
45+
3. Integrate changes feedback appears
46+
47+
## Agent Roles
48+
49+
If you're an Opus model, you're an Implementor agent.
50+
If you're a GPT model, you're an Planner agent.
51+
If you're a Fabel model, you're a Problem solver agent.
52+
53+
### Implementor agent
54+
55+
Writes code following Code Rules.
56+
57+
### Planner agent
58+
59+
##### When reviewing Implementor agent's plans**
60+
61+
**User will ask you**: Review <subject>; verdict; prompt on failure.
62+
**Respond by:**
63+
* Interviewing user to resolve ambiguity; do not ask the Implementor agent to make decisions.
64+
* Writing a feedback prompt that user will handoff to the Implementor agent

‎core/mod.ts‎

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,17 +39,32 @@ export type {
3939
ModifierMiddleware,
4040
CodeBlockWorkflow,
4141
} from "./src/modifiers.ts";
42-
export { useCodeBlock, CodeBlockCtx } from "./src/modifiers.ts";
42+
export { useCodeBlock } from "./src/modifiers.ts";
43+
44+
// ---------------------------------------------------------------------------
45+
// Component Api — contextual operations for component expansion
46+
// ---------------------------------------------------------------------------
47+
48+
export type { ComponentApi } from "./src/component-api.ts";
49+
export {
50+
Component,
51+
importComponent,
52+
applyModifiers,
53+
raise,
54+
env,
55+
evalScope,
56+
codeBlock,
57+
persistent,
58+
content,
59+
} from "./src/component-api.ts";
4360

4461
// ---------------------------------------------------------------------------
4562
// Eval system (generator eval blocks)
4663
// ---------------------------------------------------------------------------
4764

48-
export type { EvalEnv } from "./src/eval-env.ts";
49-
export { EvalEnvCtx, EvalScopeCtx } from "./src/eval-env.ts";
65+
export type { EvalEnv } from "./src/types.ts";
5066

51-
export type { EvalContext } from "./src/eval-context.ts";
52-
export { EvalCtxKey, createEvalContext, compileBlock } from "./src/eval-context.ts";
67+
export { compileBlock } from "./src/eval-context.ts";
5368

5469
// ---------------------------------------------------------------------------
5570
// executable.md Globals (for generated eval modules)

‎core/src/component-api.ts‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
/**
2+
* Component Api — contextual operations for component expansion.
3+
*
4+
* One public Api replaces the former dependency container (ExpansionContext)
5+
* and raw Effection context keys. Context-dependent behavior is installed as
6+
* scope-local middleware via `Component.around(...)`:
7+
*
8+
* - Runtime implementations (document import, modifier execution, component
9+
* state) install at `{ at: "min" }`. Middleware installed in a nested scope
10+
* runs before inherited middleware, so a component that installs its own
11+
* `env` shadows its ancestors without leaking into siblings — install
12+
* inside `scoped()` for automatic removal.
13+
* - Caller instrumentation and overrides wrap at the default `"max"`.
14+
*/
15+
16+
import { createApi } from "@effectionx/context-api";
17+
import type { Operation } from "effection";
18+
import type { EvalScope } from "@effectionx/scope-eval";
19+
import type {
20+
CodeBlockContext,
21+
CodeBlockResult,
22+
ComponentDefinition,
23+
ErrorSegment,
24+
EvalEnv,
25+
FunctionComponentDefinition,
26+
Modifier,
27+
} from "./types.ts";
28+
29+
export interface ComponentApi {
30+
/** `"__root__"` imports the root document. */
31+
importComponent(name: string): Operation<ComponentDefinition | FunctionComponentDefinition>;
32+
applyModifiers(modifiers: Modifier[], block: CodeBlockContext): Operation<CodeBlockResult>;
33+
/**
34+
* Report an ErrorSegment under the ambient error policy. The default
35+
* returns the segment for rendering; suppressed-documentation scopes
36+
* install middleware that throws instead (spec §6.9).
37+
*/
38+
raise(error: ErrorSegment): Operation<ErrorSegment>;
39+
env: EvalEnv | undefined;
40+
evalScope: EvalScope | undefined;
41+
codeBlock(): Operation<CodeBlockContext>;
42+
/** Whether the current block runs with persistent resource lifetime. */
43+
persistent: boolean;
44+
/** Render the invoking component's children (optionally a named slot). */
45+
content(slot?: string): Operation<string>;
46+
}
47+
48+
export const Component = createApi<ComponentApi>("Component", {
49+
// deno-lint-ignore require-yield
50+
*importComponent(name: string): Operation<ComponentDefinition | FunctionComponentDefinition> {
51+
throw new Error(
52+
`Component.importComponent("${name}") has no provider. Install one with ` +
53+
`Component.around({ importComponent }, { at: "min" }) before expansion.`,
54+
);
55+
},
56+
// deno-lint-ignore require-yield
57+
*applyModifiers(_modifiers: Modifier[], block: CodeBlockContext): Operation<CodeBlockResult> {
58+
throw new Error(
59+
`Component.applyModifiers() has no provider for block "${block.blockId}". Install one ` +
60+
`with Component.around({ applyModifiers }, { at: "min" }) before expansion.`,
61+
);
62+
},
63+
// deno-lint-ignore require-yield
64+
*raise(error: ErrorSegment): Operation<ErrorSegment> {
65+
return error;
66+
},
67+
env: undefined,
68+
evalScope: undefined,
69+
// deno-lint-ignore require-yield
70+
*codeBlock(): Operation<CodeBlockContext> {
71+
throw new Error(
72+
"Component.codeBlock() has no provider: no code block is executing in this scope.",
73+
);
74+
},
75+
persistent: false,
76+
// deno-lint-ignore require-yield
77+
*content(_slot?: string): Operation<string> {
78+
throw new Error(
79+
"Component.content() has no provider: not inside a function component invocation.",
80+
);
81+
},
82+
});
83+
84+
export const {
85+
importComponent,
86+
applyModifiers,
87+
raise,
88+
env,
89+
evalScope,
90+
codeBlock,
91+
persistent,
92+
content,
93+
} = Component.operations;

‎core/src/content-context.ts‎

Lines changed: 11 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,26 @@
11
/**
2-
* Content context for function components.
3-
*
4-
* Provides `useContent()` — the function component equivalent of
5-
* `<Content />` in markdown components. The expansion engine sets
6-
* the content handle on the Effection scope before calling the
7-
* function component. Components that need rendered children call
8-
* `yield* useContent()` to retrieve them.
9-
*
10-
* Named slots are supported: `yield* useContent("header")` returns
11-
* the content for the "header" slot, matching `<Content slot="header" />`
12-
* in markdown components.
2+
* useContent() — the function component equivalent of `<Content />` in
3+
* markdown components. Ergonomic alias for the Component `content()`
4+
* operation; the expansion engine installs the slot-rendering middleware
5+
* around each function component invocation.
136
*/
147

15-
import { createContext } from "effection";
168
import type { Operation } from "effection";
17-
import type { Segment } from "./types.ts";
18-
19-
/**
20-
* Handle providing access to a component's children content.
21-
* Set on the Effection scope by the expansion engine.
22-
*/
23-
export interface ContentHandle {
24-
/** Render the default slot (children without a slot prop). */
25-
renderDefault: () => Operation<string>;
26-
/** Render a named slot. Returns empty string if the slot has no content. */
27-
renderSlot: (name: string) => Operation<string>;
28-
/** Raw child segments (all slots combined, for inspection). */
29-
segments: Segment[];
30-
}
9+
import { content } from "./component-api.ts";
3110

3211
/**
33-
* Effection context key for the content handle.
34-
*/
35-
export const ContentCtx = createContext<ContentHandle>("content");
36-
37-
/**
38-
* Render children content from the parent scope.
39-
*
40-
* The function component equivalent of `<Content />` in markdown components.
12+
* Render children content from the invoking component.
4113
*
4214
* @param slotName - Optional slot name. If provided, renders only the
43-
* content assigned to that slot. If omitted, renders the default slot
44-
* (children without a `slot` prop).
45-
* @returns The rendered content as a string.
15+
* content assigned to that slot (matching `<Content slot="name" />`).
16+
* If omitted, renders the default slot.
4617
*
4718
* @example
4819
* ```ts
49-
* // Render default content (equivalent to <Content /> in .md)
50-
* const content = yield* useContent();
51-
*
52-
* // Render named slot (equivalent to <Content slot="header" /> in .md)
20+
* const body = yield* useContent();
5321
* const header = yield* useContent("header");
5422
* ```
5523
*/
56-
export function* useContent(slotName?: string): Operation<string> {
57-
const handle = yield* ContentCtx.expect();
58-
if (slotName !== undefined) {
59-
return yield* handle.renderSlot(slotName);
60-
}
61-
return yield* handle.renderDefault();
24+
export function useContent(slotName?: string): Operation<string> {
25+
return content(slotName);
6226
}

‎core/src/errors.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import type { ErrorSegment } from "./types.ts";
2+
3+
/**
4+
* Thrown by suppressed-documentation raise middleware (spec §6.9). Generic
5+
* catches in the engine rethrow it instead of converting it into an
6+
* ErrorSegment, so documentation fail-fast is never swallowed.
7+
*/
8+
export class DocumentationError extends Error {
9+
readonly segment: ErrorSegment;
10+
11+
constructor(segment: ErrorSegment) {
12+
super(segment.message);
13+
this.name = "DocumentationError";
14+
this.segment = segment;
15+
}
16+
}

‎core/src/eval-context.ts‎

Lines changed: 3 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,19 @@
11
/**
2-
* Eval block compilation context (spec §5).
2+
* Eval block compilation (spec §5).
33
*/
44

5-
import { createContext as createEffectionContext } from "effection";
65
import type { Operation } from "effection";
76
import { compile as runtimeCompile } from "@executablemd/runtime";
87

9-
// ---------------------------------------------------------------------------
10-
// EvalContext — lightweight context for the eval system
11-
// ---------------------------------------------------------------------------
12-
13-
/**
14-
* Eval context for document runs.
15-
*
16-
* In the Deno model, there is no VM context — eval blocks are compiled
17-
* into data: URI modules that import their dependencies. The EvalContext
18-
* exists as a marker that the eval system has been initialized.
19-
*/
20-
export interface EvalContext {
21-
/** Placeholder for future per-document eval configuration. */
22-
initialized: true;
23-
}
24-
25-
/**
26-
* Effection context key for the eval context.
27-
*/
28-
export const EvalCtxKey = createEffectionContext<EvalContext>("evalContext");
29-
30-
/**
31-
* Create an eval context for a document run.
32-
*
33-
* In the Deno model, this is lightweight — no VM sandbox creation.
34-
* The eval context is set on the Effection scope so eval blocks
35-
* can verify the eval system is initialized.
36-
*/
37-
export function createEvalContext(_globals: Record<string, unknown> = {}): EvalContext {
38-
return { initialized: true };
39-
}
40-
418
/**
429
* Compile transformed source code into a generator function.
4310
*
4411
* Delegates to `@executablemd/runtime` so platform-specific
4512
* compilation can be provided via API.Compiler middleware.
4613
*/
47-
export function* compileBlock(
14+
export function compileBlock(
4815
transformedBodyCode: string,
4916
userImports: string[],
5017
): Operation<(env: Record<string, unknown>) => Generator<unknown, unknown, unknown>> {
51-
return yield* runtimeCompile(transformedBodyCode, { imports: userImports });
18+
return runtimeCompile(transformedBodyCode, { imports: userImports });
5219
}

‎core/src/eval-env.ts‎

Lines changed: 0 additions & 58 deletions
This file was deleted.

0 commit comments

Comments
 (0)