Skip to content

Commit d701c9b

Browse files
committed
✨ Address a root document's sections as targets
A root document now catalogs its own addressable static headings, resolves one selector to exactly one of them, and projects itself down to the preamble, each ancestor's own content, and that section's subtree before anything expands. Heading discovery parses a masked copy of the body, with the boundary scanner's top-level component spans blanked to spaces of the same length. Remark ends the HTML block it infers for a component at a blank line, so a component child's `#` line surfaces as a root heading without the mask; offsets, lines, and everything outside those spans are untouched, so the mask changes what is seen and never where anything is. Projection retains original source ranges and scans each one under its own origin instead of concatenating and rescanning, so skipped source cannot renumber what follows it and a retained element keeps its expansion ID. The exact resolved target, never the caller's glob, is what the durable root import records. A replay guard resolves the current selector against the recorded content and requires the recorded exact target, in the check phase so a completed journal cannot answer for a section it never ran. `xmd targets`, targeted `xmd run`, and the targeted workflow definition are the later layers of #412 and remain unbuilt.
1 parent 30dc295 commit d701c9b

11 files changed

Lines changed: 2473 additions & 52 deletions

‎architecture.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ Existing documents and code get aligned to this section retroactively.
3131
| definition base | the Git revision supplied to choose a workflow definition's pinned commit |
3232
| Repository base | the optional Git revision from which one named Workspace Repository initializes its primary checkout |
3333
| pinned commit | the commit obtained by resolving a base once; it remains the workflow run's starting repository state even as the run creates descendant commits |
34+
| document target | an addressable static heading in a root document's own Markdown flow, named by the canonical path of heading labels that reaches it; selecting one executes the preamble, each ancestor's own content, and that heading's complete subtree |
3435
| expansion | one logical evaluation of an authored executable element within a document execution |
3536
| expansion ID | a deterministic identifier for one logical expansion; restoring or retrying that expansion preserves the ID, while a distinct evaluation requested by the document receives another |
3637
| Git capability | the contextual interface through which workflow infrastructure queries the Git repository associated with the current working directory |
@@ -533,6 +534,33 @@ interpreter; graceful Worker shutdown alone is insufficient. Worker Shell
533534
exposes no native executable or host PATH and is not described as POSIX or
534535
native Bash.
535536

537+
## Document targets
538+
539+
A root document addresses its own sections. The outline is discovered from the
540+
document's static Markdown alone: only headings in the root flow are targets,
541+
and a heading is addressable only when its text is statically rendered — a
542+
heading generated inside a component, or one carrying an interpolation, has no
543+
stable address, and neither does anything beneath it. Discovery therefore
544+
parses a copy in which the scanner's top-level component spans are blanked,
545+
because a Markdown parser reading raw XMD cannot tell a component's children
546+
from the root flow.
547+
548+
Selection resolves exactly once, before the document expands and before any
549+
authored effect runs. A selector may glob, but it must name exactly one catalog
550+
entry: naming none and naming several are both failures, and two sections that
551+
canonicalize to the same path stay two entries so the ambiguity is reported
552+
rather than resolved arbitrarily.
553+
554+
The selector and the target it resolves to are different things, and only one
555+
of them is identity. A selector is invocation input — it describes what a
556+
caller asked for, and two callers may spell the same request differently. The
557+
**exact resolved target** is what ran, so it is what a document execution
558+
records durably, what a targeted workflow definition carries, and what a resumed
559+
run is checked against. A caller's glob is never recorded and never re-resolved
560+
against a newer checkout; a resumed run re-resolves the current selector against
561+
the *recorded* content and refuses to continue unless it still names the
562+
recorded target.
563+
536564
## Expansion identity
537565

538566
Core describes the executable element currently being expanded:
@@ -569,6 +597,14 @@ JavaScript object identity.
569597
document execution receives expansion identity without installing workflow
570598
middleware.
571599

600+
Selecting a document target does not disturb any of this. Projection retains
601+
the original source ranges and scans each one under its own origin, so a
602+
retained element keeps the offset and line it was authored at, and with them
603+
its expansion ID. Two runs of the same document under different targets
604+
therefore agree on the ID of every element they both retain, and may share IDs
605+
without sharing effects — run identity and workflow-definition identity are
606+
what tell those runs apart.
607+
572608
## Two layers
573609

574610
Error handling has two layers:
@@ -890,6 +926,7 @@ Status is measured against main.
890926
| `<PrintErrors>` / `printErrors(fn)` | prints failures | built on main |
891927
| `<Output>` region `output` mode | an undecided error fails the document execution | built on main |
892928
| `Expansion` / `getExpansion()` | describes the current logical element expansion | built on main |
929+
| document targets | catalogs a root document's addressable static headings, resolves one selector to one exact target, and projects the document to it before expansion | built on the #412 stack; `xmd targets`, targeted `xmd run`, and the targeted workflow definition are unbuilt |
893930
| `useWorkflow()` / `getWorkflowRun()` | associates one document execution with a workflow run | built on main |
894931
| `Git.revParse()` | verifies and resolves one Git revision expression contextually | built on main |
895932
| workflow run storage | creates or compatibly finds one run by public run ID, retains its identity, state, document executions and filtered journal, and validates immutable Workspace roots through one provider-owned connection entry | built on the #365 stack; Workspace effect publication is unbuilt |

‎packages/core/mod.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -130,8 +130,20 @@ export type {
130130
ExecutionApi,
131131
DocumentExecution,
132132
} from "./src/execute.ts";
133-
export { INLINE_SOURCE_PATH, inlineSource, rootSourcePath } from "./src/root-source.ts";
134-
export type { InlineRootDocument, RootDocumentSource } from "./src/root-source.ts";
133+
export {
134+
fileSource,
135+
formatDocumentReference,
136+
INLINE_SOURCE_PATH,
137+
inlineSource,
138+
rootSourcePath,
139+
} from "./src/root-source.ts";
140+
export type {
141+
FileRootDocument,
142+
InlineRootDocument,
143+
RootDocumentSource,
144+
} from "./src/root-source.ts";
145+
export { DocumentTargetError } from "./src/document-targets.ts";
146+
export type { DocumentTargetErrorKind } from "./src/document-targets.ts";
135147
export { inspectComponent, inspectDocument } from "./src/inspect.ts";
136148
export type {
137149
ComponentInfo,

‎packages/core/src/definition.ts‎

Lines changed: 166 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
import type { Operation } from "effection";
2-
import type { ComponentDefinition } from "./types.ts";
2+
import type { ComponentDefinition, Segment } from "./types.ts";
33
import { parseFrontmatter } from "./frontmatter.ts";
44
import { compilePropsSchema, compileReturnsSchema } from "./validate.ts";
5-
import { scanSegments } from "./scanner.ts";
5+
import { scanComponentSpans, scanSegments } from "./scanner.ts";
6+
import { outlineDocument, retainedRanges, selectTarget } from "./document-targets.ts";
7+
import type { DocumentOutline } from "./document-targets.ts";
68

79
import matter from "gray-matter";
810

@@ -15,56 +17,187 @@ export function isFunctionComponentPath(path: string): boolean {
1517
return path.endsWith(".ts");
1618
}
1719

20+
/** A document's frontmatter data, its markdown body, and where the body sits. */
21+
interface ParsedSource {
22+
data: Record<string, unknown>;
23+
content: string;
24+
baseOffset: number;
25+
baseLine: number;
26+
}
27+
1828
/**
19-
* Parse markdown source into a component definition. Execution and
20-
* inspection share this so their frontmatter and schema behavior cannot
21-
* drift: both compile the props and return schemas, so a malformed schema
22-
* fails the same way whether the document runs or is only described.
29+
* Split frontmatter from the markdown body without reading either.
30+
*
31+
* The markdown body is a verbatim suffix of the raw file, so the body start
32+
* is computed by length — never by content search, which could false-match
33+
* body text repeated inside frontmatter. The invariant check turns any
34+
* gray-matter normalization surprise into a loud error instead of silently
35+
* wrong source positions.
2336
*/
24-
export function* parseMarkdownDefinition(
25-
name: string,
26-
path: string,
27-
content: string,
28-
): Operation<ComponentDefinition> {
37+
function parseSource(path: string, content: string): ParsedSource {
2938
const parsed = matter(content);
30-
const { meta, props, returns } = parseFrontmatter(parsed.data);
31-
yield* compilePropsSchema(props);
32-
if (returns !== undefined) {
33-
yield* compileReturnsSchema(returns);
34-
}
35-
// The markdown body is a verbatim suffix of the raw file, so the body start
36-
// is computed by length — never by content search, which could false-match
37-
// body text repeated inside frontmatter. The invariant check turns any
38-
// gray-matter normalization surprise into a loud error instead of silently
39-
// wrong source positions.
40-
const bodyStart = content.length - parsed.content.length;
41-
if (content.slice(bodyStart) !== parsed.content) {
39+
const baseOffset = content.length - parsed.content.length;
40+
if (content.slice(baseOffset) !== parsed.content) {
4241
throw new Error(`frontmatter parse did not preserve the markdown body verbatim: ${path}`);
4342
}
4443
let baseLine = 1;
45-
for (let i = 0; i < bodyStart; i++) {
44+
for (let i = 0; i < baseOffset; i++) {
4645
if (content[i] === "\n") {
4746
baseLine++;
4847
}
4948
}
50-
const bodySegments = scanSegments(parsed.content, {
51-
path,
52-
baseOffset: bodyStart,
53-
baseLine,
54-
});
49+
return { data: parsed.data, content: parsed.content, baseOffset, baseLine };
50+
}
5551

52+
/** The static heading structure a document's body offers as targets. */
53+
function documentOutline(path: string, content: string): DocumentOutline {
54+
const body = parseSource(path, content).content;
55+
return outlineDocument(body, scanComponentSpans(body));
56+
}
57+
58+
/**
59+
* The exact canonical target a selector names in this document's content.
60+
*
61+
* Synchronous and free of effects, so the resolution that decides *what* runs
62+
* happens before anything runs — including inside the durable operation that
63+
* records the root, and inside a replay guard reading recorded content.
64+
*/
65+
export function resolveDocumentTarget(path: string, content: string, selector: string): string {
66+
return selectTarget(documentOutline(path, content), selector).target;
67+
}
68+
69+
interface CompiledFrontmatter {
70+
meta: Record<string, unknown>;
71+
props: ComponentDefinition["props"];
72+
returns: ComponentDefinition["returns"];
73+
}
74+
75+
function* compileFrontmatter(data: Record<string, unknown>): Operation<CompiledFrontmatter> {
76+
const { meta, props, returns } = parseFrontmatter(data);
77+
yield* compilePropsSchema(props);
78+
if (returns !== undefined) {
79+
yield* compileReturnsSchema(returns);
80+
}
81+
return { meta, props, returns };
82+
}
83+
84+
function buildDefinition(
85+
name: string,
86+
path: string,
87+
frontmatter: CompiledFrontmatter,
88+
bodySegments: Segment[],
89+
): ComponentDefinition {
5690
// `returns` stays absent in text mode: absence is what distinguishes a text
5791
// component from one that explicitly declares a string return.
5892
const definition: ComponentDefinition = {
5993
kind: "markdown",
6094
name,
6195
path,
62-
meta,
63-
props,
96+
meta: frontmatter.meta,
97+
props: frontmatter.props,
6498
bodySegments,
6599
};
66-
if (returns !== undefined) {
67-
definition.returns = returns;
100+
if (frontmatter.returns !== undefined) {
101+
definition.returns = frontmatter.returns;
68102
}
69103
return definition;
70104
}
105+
106+
/**
107+
* Parse markdown source into a component definition. Execution and
108+
* inspection share this so their frontmatter and schema behavior cannot
109+
* drift: both compile the props and return schemas, so a malformed schema
110+
* fails the same way whether the document runs or is only described.
111+
*/
112+
export function* parseMarkdownDefinition(
113+
name: string,
114+
path: string,
115+
content: string,
116+
): Operation<ComponentDefinition> {
117+
const body = parseSource(path, content);
118+
const frontmatter = yield* compileFrontmatter(body.data);
119+
return buildDefinition(
120+
name,
121+
path,
122+
frontmatter,
123+
scanSegments(body.content, { path, baseOffset: body.baseOffset, baseLine: body.baseLine }),
124+
);
125+
}
126+
127+
/** A root document as parsed: what it declares, and what it addresses. */
128+
export interface ParsedRootDocument {
129+
definition: ComponentDefinition;
130+
/** Canonical encoded target fragments in document order, duplicates kept. */
131+
targets: readonly string[];
132+
/** The exact canonical target selected, when one was requested. */
133+
target?: string;
134+
}
135+
136+
/**
137+
* Parse a root document, projecting it to one target when a selector asks for
138+
* one.
139+
*
140+
* Selection happens here, before any segment exists, so a selector that names
141+
* nothing or names several sections fails with nothing expanded. Without a
142+
* selector the whole body is scanned exactly as an ordinary markdown component
143+
* is.
144+
*
145+
* A projection scans each retained range on its own, with the origin that range
146+
* has in the original file, rather than scanning a concatenated string. Skipped
147+
* source therefore cannot renumber what follows it: a retained element keeps
148+
* the offset and line it was authored at, and with them its expansion ID.
149+
*/
150+
export function* parseRootMarkdownDefinition(
151+
name: string,
152+
path: string,
153+
content: string,
154+
selector?: string,
155+
): Operation<ParsedRootDocument> {
156+
const body = parseSource(path, content);
157+
const frontmatter = yield* compileFrontmatter(body.data);
158+
const outline = outlineDocument(body.content, scanComponentSpans(body.content));
159+
160+
if (selector === undefined) {
161+
const bodySegments = scanSegments(body.content, {
162+
path,
163+
baseOffset: body.baseOffset,
164+
baseLine: body.baseLine,
165+
});
166+
return {
167+
definition: buildDefinition(name, path, frontmatter, bodySegments),
168+
targets: outline.targets,
169+
};
170+
}
171+
172+
const entry = selectTarget(outline, selector);
173+
const newlines = newlineCounts(body.content);
174+
const bodySegments: Segment[] = [];
175+
for (const range of retainedRanges(outline, entry)) {
176+
bodySegments.push(
177+
...scanSegments(body.content.slice(range.start, range.end), {
178+
path,
179+
baseOffset: body.baseOffset + range.start,
180+
baseLine: body.baseLine + newlines[range.start]!,
181+
}),
182+
);
183+
}
184+
return {
185+
definition: buildDefinition(name, path, frontmatter, bodySegments),
186+
targets: outline.targets,
187+
target: entry.target,
188+
};
189+
}
190+
191+
/** How many newlines precede each offset, so a retained range knows its line. */
192+
function newlineCounts(body: string): number[] {
193+
const counts = new Array<number>(body.length + 1);
194+
let seen = 0;
195+
for (let i = 0; i < body.length; i++) {
196+
counts[i] = seen;
197+
if (body[i] === "\n") {
198+
seen++;
199+
}
200+
}
201+
counts[body.length] = seen;
202+
return counts;
203+
}

0 commit comments

Comments
 (0)