asciidoc-abundant-tree 0.2.0 → 0.2.1

package/README.md

@@ -274,6 +274,29 @@ const ttl = projection.ttl;
 const jsonLd = projection.jsonLd;
 ```
 
+Book-entry callers can register include resolvers for includes that select by something other than a file path, such as a symbol in a TypeScript file. A resolver claims targets by prefix and returns whole consecutive lines of a source file inside `documentRoot`, plus the line they start at; the lines get coordinates in that file just like a file include:
+
+```ts
+const book = await parseAbundantTree({
+	sourcePath: "bookshelf/books/08-design/book.adoc",
+	mode: "book-entry",
+	documentRoot: ".",
+	includeResolvers: [
+		{
+			// include::docloom:examples/replay.ts[symbol=replay,part=source]
+			prefix: "docloom:",
+			resolve: ({ target, attributes }) => {
+				// Your own selector: find the declaration, widen it to whole lines.
+				const { text, startLine } = selectWholeLines(target, attributes);
+				return { text, origin: { path: target, startLine } };
+			},
+		},
+	],
+});
+```
+
+`attributes` are the include attributes as Asciidoctor parses them, the same an Asciidoctor include processor receives, so the bookshelf build and this parser can register the same selector. A resolver that throws fails construction with `include.resolver-failed`; returned text that does not match its source leaves those lines without coordinates and reports `origin-map.selection-mismatch`.
+
 `parseAbundantTree` reads only the supplied source file. Interdocument xrefs keep their raw target and official href when Asciidoctor exposes one, but this package does not open the referenced `.adoc` file.
 
 Browser tools that already hold AsciiDoc source text can use the browser-safe subpath:

package/dist/animation-yaml-export/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { o as exportAnimationYaml } from "../src-CNTTQlPJ.mjs";
+import { o as exportAnimationYaml } from "../src-DMOLXZbF.mjs";
 import process from "node:process";
 //#region src/animation-yaml-export/cli.ts
 const USAGE = `Usage:

package/dist/browser.mjs

@@ -944,8 +944,8 @@ function recoveryFailure(code, message, source) {
 }
 //#endregion
 //#region src/official-block-policy.ts
-function officialBlockPolicy(context) {
-	switch (context) {
+function officialBlockPolicy(block) {
+	switch (block.getContext?.()) {
 		case "admonition":
 		case "dlist":
 		case "list_item":
@@ -953,12 +953,13 @@ function officialBlockPolicy(context) {
 		case "table":
 		case "verse": return "scan";
 		case "example":
-		case "olist":
 		case "quote":
-		case "section":
 		case "sidebar":
-		case "ulist":
-		case "open": return "recurse";
+		case "open": return block.getContentModel?.() === "simple" ? "scan" : "recurse";
+		case "olist":
+		case "preamble":
+		case "section":
+		case "ulist": return "recurse";
 		case "listing":
 		case "literal":
 		case "pass":
@@ -1017,7 +1018,6 @@ function projectOfficialDocument(options) {
 		usedAnchorKeys: /* @__PURE__ */ new Set(),
 		intervalByBlock: options.intervalByBlock,
 		projectableBlocks: options.projectableBlocks,
-		containerFallbackBlocks: options.containerFallbackBlocks,
 		sectionByBlock: options.sectionByBlock,
 		bindingRequests,
 		targets,
@@ -1035,19 +1035,18 @@ function buildChildren(officialDocument, context) {
 	for (const block of childBlocksOf(officialDocument)) topLevel.push(...toNodes(buildNode(block, context)));
 	return topLevel;
 }
-function buildNode(block, context, fallbackLine) {
+function buildNode(block, context) {
 	const blockContext = block.getContext?.();
 	const officialLine = block.getSourceLocation?.()?.getLineNumber?.();
-	const line = officialLine ?? fallbackLine;
 	const interval = context.intervalByBlock.get(block);
-	if (!canProjectBlock(block, context, officialLine, fallbackLine)) return;
+	if (!canProjectBlock(block, context)) return;
 	if (blockContext === "section" && officialLine !== void 0) return buildSection(block, context);
-	if (blockContext === "paragraph" && line !== void 0) return buildParagraph(block, line, context, interval);
+	if (blockContext === "paragraph" && officialLine !== void 0) return buildParagraph(block, officialLine, context, interval);
 	if (blockContext === "listing" && officialLine !== void 0) return buildListing(block, officialLine, context, interval);
 	if (blockContext === "table" && officialLine !== void 0) return buildTable(block, officialLine, context, interval);
 	if (blockContext === "dlist" && officialLine !== void 0) return buildDescriptionList(block, officialLine, context, interval);
-	if (blockContext === "open" && line !== void 0) return buildOpenChildren(block, line, context);
-	if (officialBlockPolicy(blockContext) === "diagnostic") return;
+	if (blockContext === "open" && officialLine !== void 0) return childBlocksOf(block).flatMap((child) => toNodes(buildNode(child, context)));
+	if (officialBlockPolicy(block) === "diagnostic") return;
 	if (officialLine !== void 0) {
 		registerOfficialBlockTarget(context, block, {
 			targetType: "block",
@@ -1059,10 +1058,8 @@ function buildNode(block, context, fallbackLine) {
 		return childBlocksOf(block).flatMap((child) => toNodes(buildNode(child, context)));
 	}
 }
-function canProjectBlock(block, context, officialLine, fallbackLine) {
-	if (!context.projectableBlocks) return true;
-	if (context.projectableBlocks.has(block)) return true;
-	return officialLine === void 0 && fallbackLine !== void 0 && (context.containerFallbackBlocks?.has(block) ?? false);
+function canProjectBlock(block, context) {
+	return context.projectableBlocks?.has(block) ?? true;
 }
 function buildSection(block, context) {
 	const section = context.sectionByBlock.get(block);
@@ -1088,16 +1085,6 @@ function buildSection(block, context) {
 	section.children = childBlocksOf(block).flatMap((child) => toNodes(buildNode(child, context)));
 	return section;
 }
-function buildOpenChildren(block, line, context) {
-	const nodes = [];
-	let cursor = line;
-	for (const child of childBlocksOf(block)) {
-		const built = toNodes(buildNode(child, context, child.getSourceLocation?.()?.getLineNumber?.() ?? findBlockSourceLine(context, child, cursor)));
-		nodes.push(...built);
-		cursor = Math.max(cursor, ...built.map(nodeEndLine).filter(isNumber)) + 1;
-	}
-	return nodes;
-}
 function buildDescriptionList(block, startLine, context, interval) {
 	const metadata = interval?.metadata ?? [];
 	const span = interval?.span ?? {
@@ -1329,17 +1316,6 @@ function sourceSpanOf(node) {
 function isLineSpan(value) {
 	return value !== void 0;
 }
-function findBlockSourceLine(context, block, startLine) {
-	const firstSourceLine = block.getSource?.()?.split(/\r?\n/u).find((line) => line.trim() !== "")?.trim();
-	if (!firstSourceLine) return;
-	for (let line = startLine; line <= context.lineTable.lines.length; line += 1) if (lineText(context.lineTable, line).trim() === firstSourceLine) return line;
-}
-function nodeEndLine(node) {
-	return node.source?.span?.endLine ?? node.source?.line;
-}
-function isNumber(value) {
-	return typeof value === "number";
-}
 function buildParagraph(block, line, context, interval) {
 	const blockSpan = interval?.span ?? {
 		startLine: line,
@@ -1604,6 +1580,37 @@ function isRecord$1(value) {
 	return value !== null && typeof value === "object";
 }
 //#endregion
+//#region src/official-source-location.ts
+const takenFromParent = /* @__PURE__ */ new WeakSet();
+const borrowedFromChild = /* @__PURE__ */ new WeakSet();
+function completeSynthesizedSourceLocations(officialDocument) {
+	for (const block of childBlocksOf(officialDocument)) complete(block, void 0);
+}
+function takesParentSourceLocation(block) {
+	return takenFromParent.has(block);
+}
+function borrowsChildSourceLocation(block) {
+	return borrowedFromChild.has(block);
+}
+function complete(block, parent) {
+	if (!block.getSourceLocation?.() && block.getContext?.() === "paragraph" && parent?.getContext?.() === "open") {
+		locate(block, parent.getSourceLocation?.());
+		takenFromParent.add(block);
+	}
+	const children = childBlocksOf(block);
+	for (const child of children) complete(child, block);
+	if (!block.getSourceLocation?.() && block.getContext?.() === "open") {
+		const location = children.find((child) => child.getSourceLocation?.())?.getSourceLocation?.();
+		if (location) {
+			locate(block, location);
+			borrowedFromChild.add(block);
+		}
+	}
+}
+function locate(block, location) {
+	if (location) block.sourceLocation = location;
+}
+//#endregion
 //#region src/book-entry/source-scope-index.ts
 const sectionSourceScopeBySection = /* @__PURE__ */ new WeakMap();
 function registerSectionSourceScope(section, scope) {
@@ -1673,7 +1680,7 @@ function scanInlineOccurrencesInOfficialBlocks(options) {
 		}
 		if (interval.metadataSpan) scanMetadataRange(options.lineTable, interval.metadataSpan.startLine, interval.metadataSpan.endLine, xrefOccurrences, anchorOccurrences);
 		const span = interval.contentSpan ?? interval.span;
-		if (officialBlockPolicy(surface.context) !== "scan") continue;
+		if (officialBlockPolicy(surface.block) !== "scan") continue;
 		if (!scansMacroSubstitutedContent(surface)) continue;
 		if (surface.context === "table") scanTableInlineRange(options.lineTable, surface.block, span.startLine, span.endLine, xrefOccurrences, anchorOccurrences, headingInlineMetadataOccurrences, options.toolDiagnostics);
 		else scanInlineRange(options.lineTable, span.startLine, span.endLine, xrefOccurrences, anchorOccurrences, headingInlineMetadataOccurrences, options.toolDiagnostics, descendantUnscannableRanges(surface, options.intervalByBlock));
@@ -1721,7 +1728,7 @@ function recoverSourceAwareInlineOrigins(occurrences, sourceAwareDocument, toolD
 function hasDiagnosticPolicyAncestor$1(surface) {
 	let current = surface.parent;
 	while (current) {
-		if (officialBlockPolicy(current.context) === "diagnostic") return true;
+		if (officialBlockPolicy(current.block) === "diagnostic") return true;
 		current = current.parent;
 	}
 	return false;
@@ -1918,7 +1925,7 @@ function descendantUnscannableRanges(surface, intervalByBlock) {
 	return mergeLineSpans(ranges);
 }
 function collectUnscannableRanges(surface, intervalByBlock, ranges) {
-	const policy = officialBlockPolicy(surface.context);
+	const policy = officialBlockPolicy(surface.block);
 	const interval = intervalByBlock.get(surface.block);
 	if (policy === "skip" || policy === "diagnostic") {
 		if (interval) ranges.push(interval.span);
@@ -2203,6 +2210,85 @@ function parseStyleIdRoles(part) {
 	});
 }
 //#endregion
+//#region src/official-delimiter.ts
+const DELIMITED_BLOCKS = {
+	"--": ["open", new Set([
+		"comment",
+		"example",
+		"literal",
+		"listing",
+		"pass",
+		"quote",
+		"sidebar",
+		"source",
+		"verse",
+		"admonition",
+		"abstract",
+		"partintro"
+	])],
+	"----": ["listing", new Set(["literal", "source"])],
+	"....": ["literal", new Set(["listing", "source"])],
+	"====": ["example", new Set(["admonition"])],
+	"****": ["sidebar", /* @__PURE__ */ new Set()],
+	____: ["quote", new Set(["verse"])],
+	"++++": ["pass", new Set([
+		"stem",
+		"latexmath",
+		"asciimath"
+	])],
+	"|===": ["table", /* @__PURE__ */ new Set()],
+	",===": ["table", /* @__PURE__ */ new Set()],
+	":===": ["table", /* @__PURE__ */ new Set()],
+	"!===": ["table", /* @__PURE__ */ new Set()],
+	"~~~~": ["open", new Set(["abstract", "partintro"])],
+	"////": ["comment", /* @__PURE__ */ new Set()],
+	"```": ["fenced_code", /* @__PURE__ */ new Set()]
+};
+const DELIMITED_BLOCK_HEADS = new Set(Object.keys(DELIMITED_BLOCKS).map((delimiter) => delimiter.slice(0, 2)));
+const DELIMITED_BLOCK_TAILS = Object.fromEntries(Object.keys(DELIMITED_BLOCKS).filter((delimiter) => delimiter.length === 4).map((delimiter) => [delimiter, delimiter.slice(-1)]));
+function officialDelimiter(line) {
+	let candidate = line;
+	let lineLength = candidate.length;
+	if (lineLength < 2 || !DELIMITED_BLOCK_HEADS.has(candidate.slice(0, 2))) return;
+	let tip;
+	let tipLength;
+	if (lineLength === 2) {
+		tip = candidate;
+		tipLength = 2;
+	} else {
+		tipLength = lineLength < 5 ? lineLength : 4;
+		tip = candidate.slice(0, tipLength);
+		if (tip.startsWith("`")) {
+			if (tipLength === 4) {
+				if (tip === "````") return;
+				tip = tip.slice(0, 3);
+				if (tip !== "```") return;
+				candidate = tip;
+				lineLength = 3;
+				tipLength = 3;
+			} else if (tip !== "```") return;
+		} else if (tipLength === 3) return;
+	}
+	const entry = DELIMITED_BLOCKS[tip];
+	if (!entry) return;
+	const tail = DELIMITED_BLOCK_TAILS[tip];
+	if (!(lineLength === tipLength || tail !== void 0 && isUniform(candidate.slice(1), tail))) return;
+	const [context, masq] = entry;
+	return {
+		context,
+		masq,
+		terminator: candidate
+	};
+}
+function delimiterOpens(delimiter, context, style) {
+	if (context === void 0) return false;
+	if (delimiter.context === "fenced_code") return context === "listing";
+	return delimiter.context === context || delimiter.masq.has(context) || style !== null && style !== void 0 && delimiter.masq.has(style);
+}
+function isUniform(text, character) {
+	return [...text].every((each) => each === character);
+}
+//#endregion
 //#region src/source-interval-resolver.ts
 function resolveSourceInterval(surface, lineTable) {
 	if (surface.sourceLine === void 0) return;
@@ -2210,11 +2296,14 @@ function resolveSourceInterval(surface, lineTable) {
 	const metadata = metadataForSurface(surface, lineTable, blockStartLine);
 	const startLine = metadata.at(0)?.line ?? blockStartLine;
 	const diagnostics = [];
-	const delimited = resolveContextDelimitedSpan(lineTable, blockStartLine, surface.context);
-	const sourceContentSpan = sourceContentSpanForContext(surface, blockStartLine);
+	const delimitedContext = isDelimitedContext(surface.context);
+	const synthesized = borrowsChildSourceLocation(surface.block);
+	const delimited = delimitedContext ? resolveDelimitedBlockSpan(lineTable, blockStartLine, surface) : void 0;
+	const undelimited = delimitedContext && delimited === void 0 && !synthesized ? resolveUndelimitedBlockSpan(lineTable, blockStartLine, surface) : void 0;
+	const sourceContentSpan = sourceContentSpanForContext(surface, lineTable, blockStartLine);
 	const nextSiblingStart = nextSiblingStartLine(surface, lineTable);
 	const childEndLine = surface.context === "dlist" ? lastChildEndLine(surface, lineTable) : void 0;
-	const endLine = delimited?.span.endLine ?? sourceContentSpan?.endLine ?? childEndLine ?? (nextSiblingStart !== void 0 ? nextSiblingStart - 1 : void 0) ?? parentEndLine(surface, lineTable) ?? lineTable.lines.length;
+	const endLine = delimited?.span.endLine ?? undelimited?.endLine ?? sourceContentSpan?.endLine ?? childEndLine ?? (nextSiblingStart !== void 0 ? nextSiblingStart - 1 : void 0) ?? parentEndLine(surface, lineTable) ?? lineTable.lines.length;
 	const span = normalizeLineSpan({
 		startLine,
 		endLine: Math.max(startLine, endLine)
@@ -2223,13 +2312,13 @@ function resolveSourceInterval(surface, lineTable) {
 		startLine,
 		endLine: blockStartLine - 1
 	} : void 0;
-	if (delimited === void 0 && isDelimitedContext(surface.context) && blockStartLine <= lineTable.lines.length) diagnostics.push({
+	if (delimitedContext && delimited === void 0 && undelimited === void 0 && !synthesized && blockStartLine <= lineTable.lines.length) diagnostics.push({
 		level: "warning",
 		code: "source-interval.delimiter-not-found",
 		message: `Could not locate ${surface.context} block delimiter from official source line ${blockStartLine}.`,
 		source: spanForLineText(lineTable, blockStartLine, 1)
 	});
-	const contentSpan = delimited?.contentSpan ?? sourceContentSpan ?? contentSpanForContext(surface, span);
+	const contentSpan = delimited?.contentSpan ?? undelimited ?? sourceContentSpan ?? contentSpanForContext(surface, span);
 	const sourceSpan = sourceSpanFromLineSpan(lineTable, span);
 	const titleSpan = titleSpanForSurface(surface, lineTable);
 	return {
@@ -2251,6 +2340,7 @@ function nextSiblingStartLine(surface, lineTable) {
 }
 function metadataForSurface(surface, lineTable, blockStartLine) {
 	if (surface.context === "list_item") return [];
+	if (takesParentSourceLocation(surface.block)) return [];
 	return collectPrecedingMetadata(lineTable, blockStartLine);
 }
 function lastChildEndLine(surface, lineTable) {
@@ -2266,25 +2356,10 @@ function parentEndLine(surface, lineTable) {
 	if (!parent) return lineTable.lines.length;
 	return resolveSourceInterval(parent, lineTable)?.span.endLine;
 }
-function resolveContextDelimitedSpan(lineTable, startLine, context) {
-	switch (context) {
-		case "example": return resolveDelimitedBlockSpan(lineTable, startLine, ["===="]);
-		case "listing": return resolveDelimitedBlockSpan(lineTable, startLine, ["----", "```"]);
-		case "literal": return resolveDelimitedBlockSpan(lineTable, startLine, ["...."]);
-		case "pass": return resolveDelimitedBlockSpan(lineTable, startLine, ["++++"]);
-		case "open": return resolveDelimitedBlockSpan(lineTable, startLine, ["--"]);
-		case "quote":
-		case "verse": return resolveDelimitedBlockSpan(lineTable, startLine, ["____"]);
-		case "sidebar": return resolveDelimitedBlockSpan(lineTable, startLine, ["****"]);
-		case "stem": return resolveDelimitedBlockSpan(lineTable, startLine, ["++++"]);
-		case "table": return resolveDelimitedBlockSpan(lineTable, startLine, ["|==="]);
-		default: return;
-	}
-}
-function resolveDelimitedBlockSpan(lineTable, startLine, allowedDelimiters) {
-	const opening = lineText(lineTable, startLine).trim();
-	if (!allowedDelimiters.includes(opening)) return;
-	for (let line = startLine + 1; line <= lineTable.lines.length; line += 1) if (lineText(lineTable, line).trim() === opening) return {
+function resolveDelimitedBlockSpan(lineTable, startLine, surface) {
+	const delimiter = officialDelimiter(lineText(lineTable, startLine).trimEnd());
+	if (!delimiter || !delimiterOpens(delimiter, surface.context, surface.block.getStyle?.())) return;
+	for (let line = startLine + 1; line <= lineTable.lines.length; line += 1) if (lineText(lineTable, line).trimEnd() === delimiter.terminator) return {
 		span: {
 			startLine,
 			endLine: line
@@ -2295,6 +2370,42 @@ function resolveDelimitedBlockSpan(lineTable, startLine, allowedDelimiters) {
 		}
 	};
 }
+function resolveUndelimitedBlockSpan(lineTable, startLine, surface) {
+	const firstLine = firstSourceLine(surface);
+	if (firstLine === void 0 || withoutWhitespace(lineText(lineTable, startLine)) !== withoutWhitespace(firstLine)) return;
+	if (surface.children.length > 0) {
+		const childEnds = surface.children.map((child) => resolveSourceInterval(child, lineTable)?.span.endLine).filter((line) => line !== void 0);
+		return {
+			startLine,
+			endLine: Math.max(startLine, ...childEnds)
+		};
+	}
+	return {
+		startLine,
+		endLine: lastSourceLine(lineTable, startLine, surface.block)
+	};
+}
+function withoutWhitespace(text) {
+	return text.replace(/\s+/gu, "");
+}
+function lastSourceLine(lineTable, startLine, block) {
+	const count = Math.max(1, block.getSourceLines?.().length ?? block.getSource?.().split(/\r?\n/u).length ?? 1);
+	const skipsLineComments = block.getContentModel?.() !== "verbatim";
+	let counted = 0;
+	for (let line = startLine; line <= lineTable.lines.length; line += 1) {
+		const text = lineText(lineTable, line);
+		if (skipsLineComments && text.startsWith("//") && !text.startsWith("///")) continue;
+		counted += 1;
+		if (counted === count) return line;
+	}
+	return Math.max(startLine, lineTable.lines.length);
+}
+function firstSourceLine(surface) {
+	const own = surface.block.getSourceLines?.()[0];
+	if (own !== void 0) return own;
+	const firstChild = surface.children[0];
+	return firstChild ? firstSourceLine(firstChild) : void 0;
+}
 function contentSpanForContext(surface, span) {
 	if (surface.context === "paragraph") return {
 		startLine: surface.sourceLine ?? span.startLine,
@@ -2308,13 +2419,12 @@ function contentSpanForContext(surface, span) {
 		};
 	}
 }
-function sourceContentSpanForContext(surface, startLine) {
+function sourceContentSpanForContext(surface, lineTable, startLine) {
 	if (surface.context !== "paragraph" && surface.context !== "admonition") return;
-	const source = surface.block.getSource?.();
-	if (source === void 0) return;
+	if (surface.block.getSourceLines === void 0 && surface.block.getSource === void 0) return;
 	return {
 		startLine,
-		endLine: startLine + Math.max(1, source.split(/\r?\n/u).length) - 1
+		endLine: lastSourceLine(lineTable, startLine, surface.block)
 	};
 }
 function titleSpanForSurface(surface, lineTable) {
@@ -2357,13 +2467,12 @@ function projectSourceSurfaces(options) {
 	const blockSurfaces = walkOfficialBlocks(options.officialDocument);
 	const intervalByBlock = /* @__PURE__ */ new WeakMap();
 	const projectableBlocks = /* @__PURE__ */ new WeakSet();
-	const containerFallbackBlocks = /* @__PURE__ */ new WeakSet();
 	const toolDiagnostics = [];
 	const mainSourcePath = options.sourcePath ? options.sourceIdentity.normalize(options.sourceIdentity.resolve(options.sourcePath)) : void 0;
 	const sourceAwareDocument = sourceAwareDocumentForLineTable(options.lineTable);
 	const logicalSource = logicalSourceForLineTable(options.lineTable);
 	for (const surface of blockSurfaces) {
-		const policy = officialBlockPolicy(surface.context);
+		const policy = officialBlockPolicy(surface.block);
 		if (isExternalSourceSurface(surface, mainSourcePath, options.sourceIdentity)) {
 			if (policy === "diagnostic") toolDiagnostics.push(unknownContextDiagnostic(surface));
 			toolDiagnostics.push({
@@ -2380,7 +2489,6 @@ function projectSourceSurfaces(options) {
 				code: "source-location.missing",
 				message: `Official block source location is missing for context '${surface.context ?? "undefined"}' node '${surface.nodeName ?? "undefined"}'.`
 			});
-			if (canUseContainerFallbackSurface(surface, policy)) containerFallbackBlocks.add(surface.block);
 			continue;
 		}
 		const interval = resolveSourceInterval(surface, options.lineTable);
@@ -2424,7 +2532,6 @@ function projectSourceSurfaces(options) {
 		blockSurfaces,
 		intervalByBlock,
 		projectableBlocks,
-		containerFallbackBlocks,
 		sectionByBlock,
 		sections,
 		xrefOccurrences,
@@ -2457,9 +2564,6 @@ function unknownContextDiagnostic(surface, interval) {
 		source: interval?.sourceSpan
 	});
 }
-function canUseContainerFallbackSurface(surface, policy) {
-	return surface.context === "paragraph" && policy === "scan" && !hasDiagnosticPolicyAncestor(surface);
-}
 function buildSectionSurfaces(blockSurfaces, intervalByBlock, lineTable, toolDiagnostics, logicalSource, sourceAwareDocument) {
 	const sections = [];
 	const sectionByBlock = /* @__PURE__ */ new WeakMap();
@@ -2577,7 +2681,7 @@ function sourceAwareOriginForLine(document, logicalLine) {
 function hasDiagnosticPolicyAncestor(surface) {
 	let current = surface.parent;
 	while (current) {
-		if (officialBlockPolicy(current.context) === "diagnostic") return true;
+		if (officialBlockPolicy(current.block) === "diagnostic") return true;
 		current = current.parent;
 	}
 	return false;
@@ -2594,6 +2698,7 @@ function mapSectionScope(sections, totalLines) {
 //#endregion
 //#region src/parser-core.ts
 async function parseAsciidoctorDocument(input) {
+	completeSynthesizedSourceLocations(input.officialDocument);
 	const sourceSurfaces = projectSourceSurfaces({
 		officialDocument: input.officialDocument,
 		lineTable: input.lineTable,
@@ -2610,7 +2715,6 @@ async function parseAsciidoctorDocument(input) {
 		headingInlineMetadataOccurrences: sourceSurfaces.headingInlineMetadataOccurrences,
 		intervalByBlock: sourceSurfaces.intervalByBlock,
 		projectableBlocks: sourceSurfaces.projectableBlocks,
-		containerFallbackBlocks: sourceSurfaces.containerFallbackBlocks,
 		sectionByBlock: sourceSurfaces.sectionByBlock
 	});
 	await resolveOfficialBindings(officialProjection.bindingRequests, input.officialDocument, input.adapter);

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as parseAbundantTree, i as serializeAbundantTreeToJson, n as formatAbundantTree, t as rdf12 } from "./src-CNTTQlPJ.mjs";
+import { a as parseAbundantTree, i as serializeAbundantTreeToJson, n as formatAbundantTree, t as rdf12 } from "./src-DMOLXZbF.mjs";
 import { relative, resolve, sep } from "node:path";
 import { existsSync } from "node:fs";
 import process from "node:process";

package/dist/index.d.mts

@@ -213,6 +213,23 @@ type ParseAbundantTreeOptions = {
   sourcePath: string;
   mode: "book-entry";
   documentRoot: string;
+  includeResolvers?: readonly IncludeResolver[];
+};
+type IncludeResolver = {
+  readonly prefix: string;
+  resolve(request: IncludeResolverRequest): IncludeResolution | Promise<IncludeResolution>;
+};
+type IncludeResolverRequest = {
+  readonly target: string;
+  readonly attributes: Readonly<Record<string, string>>;
+  readonly sourcePath: string;
+};
+type IncludeResolution = {
+  readonly text: string;
+  readonly origin: {
+    readonly path: string;
+    readonly startLine: number;
+  };
 };
 //#endregion
 //#region src/rdf12-projection/options.d.ts
@@ -354,4 +371,4 @@ type Rdf12Result = Rdf12Projection & {
 };
 declare function rdf12(document: AbundantDocument, options: Rdf12Options): Rdf12Result;
 //#endregion
-export { type AbundantDocument, type AbundantNode, type AnchorOccurrenceNode, type AsciidoctorLayer, type ExportAnimationYamlOptions, type ExportAnimationYamlResult, type LineSpan, type ListingNode, type MetadataNode, type OutputFormat, type ParagraphNode, type ParseAbundantTreeOptions, type ParserInfo, Rdf12Result, type SectionNode, type SourceFileNode, type SourceLayer, type SourcePosition, type SourceSpan, type TableNode, type TargetNode, type TargetType, type TextNode, type TitleNode, type ToolDiagnostic, type XrefOccurrenceNode, exportAnimationYaml, formatAbundantTree, parseAbundantTree, rdf12, serializeAbundantTree, serializeAbundantTreeToJson };
+export { type AbundantDocument, type AbundantNode, type AnchorOccurrenceNode, type AsciidoctorLayer, type ExportAnimationYamlOptions, type ExportAnimationYamlResult, type IncludeResolution, type IncludeResolver, type IncludeResolverRequest, type LineSpan, type ListingNode, type MetadataNode, type OutputFormat, type ParagraphNode, type ParseAbundantTreeOptions, type ParserInfo, Rdf12Result, type SectionNode, type SourceFileNode, type SourceLayer, type SourcePosition, type SourceSpan, type TableNode, type TargetNode, type TargetType, type TextNode, type TitleNode, type ToolDiagnostic, type XrefOccurrenceNode, exportAnimationYaml, formatAbundantTree, parseAbundantTree, rdf12, serializeAbundantTree, serializeAbundantTreeToJson };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as parseAbundantTree, i as serializeAbundantTreeToJson, n as formatAbundantTree, o as exportAnimationYaml, r as serializeAbundantTree, t as rdf12 } from "./src-CNTTQlPJ.mjs";
+import { a as parseAbundantTree, i as serializeAbundantTreeToJson, n as formatAbundantTree, o as exportAnimationYaml, r as serializeAbundantTree, t as rdf12 } from "./src-DMOLXZbF.mjs";
 export { exportAnimationYaml, formatAbundantTree, parseAbundantTree, rdf12, serializeAbundantTree, serializeAbundantTreeToJson };

package/dist/{src-CNTTQlPJ.mjs → src-DMOLXZbF.mjs}

@@ -2544,6 +2544,90 @@ function isElement(node) {
 	return "tagName" in node;
 }
 //#endregion
+//#region src/book-entry/diagnostics.ts
+var BookEntryConstructionError = class extends Error {
+	code;
+	diagnostic;
+	constructor(diagnostic) {
+		super(`${diagnostic.code}: ${diagnostic.message}`);
+		this.name = "BookEntryConstructionError";
+		this.code = diagnostic.code;
+		this.diagnostic = diagnostic;
+	}
+};
+function constructionError(code, message, source) {
+	return new BookEntryConstructionError({
+		level: "error",
+		code,
+		message,
+		...source ? { source } : {}
+	});
+}
+//#endregion
+//#region src/book-entry/path-boundary.ts
+function normalizeDocumentRoot(documentRoot) {
+	return resolve(documentRoot);
+}
+function resolveEntryPath(sourcePath) {
+	return resolve(sourcePath);
+}
+function resolveIncludeTarget(containingFilePath, targetPath) {
+	return resolve(containingFilePath, "..", targetPath);
+}
+function relativePathWithinDocumentRoot(documentRoot, absolutePath) {
+	const normalizedRoot = normalizeDocumentRoot(documentRoot);
+	const normalizedPath = resolve(absolutePath);
+	const relativePath = relative(normalizedRoot, normalizedPath);
+	if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`) || relativePath.includes(`${sep}..${sep}`) || relativePath.startsWith(`${sep}`)) throw constructionError("include.outside-document-root", `Resolved include path is outside documentRoot: ${normalizedPath}.`);
+	return toPortableRelativePath(relativePath);
+}
+function toPortableRelativePath(value) {
+	return value.split(sep).join("/");
+}
+//#endregion
+//#region src/book-entry/include-resolvers.ts
+function claimingResolver(resolvers, target) {
+	return resolvers.find((resolver) => target.startsWith(resolver.prefix));
+}
+function registerIncludeResolvers(registry, resolvers, documentRoot, resolutions) {
+	registry.includeProcessor(function() {
+		this.handles((target) => claimingResolver(resolvers, target) !== void 0);
+		this.process(async (_document, reader, target, attributes) => {
+			const resolver = claimingResolver(resolvers, target);
+			if (!resolver) return;
+			const sourcePath = reader.getCursor().getFile() ?? "";
+			const resolution = await resolveOrFail(resolver, target, attributes, sourcePath);
+			const absolutePath = resolve(documentRoot, resolution.origin.path);
+			let relativePath;
+			try {
+				relativePath = relativePathWithinDocumentRoot(documentRoot, absolutePath);
+			} catch {
+				throw constructionError("include.outside-document-root", `Include resolver '${resolver.prefix}' returned a source outside documentRoot for include::${target}[] in ${sourcePath}: ${absolutePath}.`);
+			}
+			const text = resolution.text.replace(/\r?\n$/u, "");
+			reader.pushInclude(text, absolutePath, relativePath, resolution.origin.startLine, attributes);
+			const frame = reader.includeStack.at(-1);
+			if (frame && text !== "") resolutions.set(frame, {
+				target,
+				absolutePath,
+				startLine: resolution.origin.startLine,
+				lineCount: text.split(/\r?\n/u).length
+			});
+		});
+	});
+}
+async function resolveOrFail(resolver, target, attributes, sourcePath) {
+	try {
+		return await resolver.resolve({
+			target: target.slice(resolver.prefix.length),
+			attributes,
+			sourcePath
+		});
+	} catch (error) {
+		throw constructionError("include.resolver-failed", `Include resolver '${resolver.prefix}' failed for include::${target}[] in ${sourcePath}: ${error instanceof Error ? error.message : String(error)}.`);
+	}
+}
+//#endregion
 //#region src/asciidoctor-file-adapter.ts
 function createAsciidoctorFileAdapter() {
 	const extensionRegistry = createExtensionRegistry();
@@ -2558,6 +2642,9 @@ function createAsciidoctorFileAdapter() {
 			});
 		},
 		async readPreprocessedLines(options) {
+			const resolutions = /* @__PURE__ */ new WeakMap();
+			const registry = Extensions.create();
+			if (options.includeResolution) registerIncludeResolvers(registry, options.includeResolution.resolvers, options.includeResolution.documentRoot, resolutions);
 			const reader = (await loadFile(options.sourcePath, {
 				safe: "unsafe",
 				base_dir: options.baseDir,
@@ -2565,7 +2652,7 @@ function createAsciidoctorFileAdapter() {
 				parse: false,
 				to_file: false,
 				attributes: options.attributes ?? {},
-				extension_registry: extensionRegistry
+				extension_registry: registry
 			})).getReader();
 			const lines = [];
 			const pushIds = /* @__PURE__ */ new WeakMap();
@@ -2581,12 +2668,14 @@ function createAsciidoctorFileAdapter() {
 					pushes += 1;
 					pushIds.set(frame, pushes);
 				}
+				const resolved = frame ? resolutions.get(frame) : void 0;
 				lines.push({
 					text,
 					cursor: cursorForReturnedReaderLine(before, after),
 					push: {
 						id: frame ? pushIds.get(frame) ?? 0 : 0,
-						depth: stack.length
+						depth: stack.length,
+						...resolved ? { resolved } : {}
 					}
 				});
 			}
@@ -2619,26 +2708,6 @@ function cursorForReturnedReaderLine(before, after) {
 	return before;
 }
 //#endregion
-//#region src/book-entry/diagnostics.ts
-var BookEntryConstructionError = class extends Error {
-	code;
-	diagnostic;
-	constructor(diagnostic) {
-		super(`${diagnostic.code}: ${diagnostic.message}`);
-		this.name = "BookEntryConstructionError";
-		this.code = diagnostic.code;
-		this.diagnostic = diagnostic;
-	}
-};
-function constructionError(code, message, source) {
-	return new BookEntryConstructionError({
-		level: "error",
-		code,
-		message,
-		...source ? { source } : {}
-	});
-}
-//#endregion
 //#region src/book-entry/include-attribute-model.ts
 const mappedAttributeNames = new Set([
 	"tag",
@@ -2919,27 +2988,6 @@ function buildParserSafeLogicalText(lineRecords) {
 	};
 }
 //#endregion
-//#region src/book-entry/path-boundary.ts
-function normalizeDocumentRoot(documentRoot) {
-	return resolve(documentRoot);
-}
-function resolveEntryPath(sourcePath) {
-	return resolve(sourcePath);
-}
-function resolveIncludeTarget(containingFilePath, targetPath) {
-	return resolve(containingFilePath, "..", targetPath);
-}
-function relativePathWithinDocumentRoot(documentRoot, absolutePath) {
-	const normalizedRoot = normalizeDocumentRoot(documentRoot);
-	const normalizedPath = resolve(absolutePath);
-	const relativePath = relative(normalizedRoot, normalizedPath);
-	if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`) || relativePath.includes(`${sep}..${sep}`) || relativePath.startsWith(`${sep}`)) throw constructionError("include.outside-document-root", `Resolved include path is outside documentRoot: ${normalizedPath}.`);
-	return toPortableRelativePath(relativePath);
-}
-function toPortableRelativePath(value) {
-	return value.split(sep).join("/");
-}
-//#endregion
 //#region src/book-entry/reader-boundary-policy.ts
 function readerPreprocessingOptions(options) {
 	const sourcePath = resolve(options.sourcePath);
@@ -3025,13 +3073,14 @@ function createSourceSet(options) {
 //#endregion
 //#region src/book-entry/official-reader-preprocessor.ts
 const asciidocExtensionPattern = /\.(?:adoc|asciidoc|asc|ad|txt)$/u;
-function validateIncludeGraph(absolutePath, documentRoot, stack) {
+function validateIncludeGraph(absolutePath, documentRoot, stack, includeResolvers) {
 	const cycleStart = stack.indexOf(absolutePath);
 	if (cycleStart !== -1) throw constructionError("include.cycle", `Include graph contains a cycle: ${[...stack.slice(cycleStart), absolutePath].join(" -> ")}.`);
 	const nextStack = [...stack, absolutePath];
 	for (const line of authoredTextLines(readFileSync(absolutePath, "utf8"))) {
 		const directive = parseReaderIncludeDirective(line);
 		if (!directive || directive.escaped) continue;
+		if (claimingResolver(includeResolvers, directive.target)) continue;
 		const attributes = parseIncludeAttributes(directive.attrlist);
 		if (attributes.classification === "unmapped") continue;
 		if (isUriTarget(directive.target) || directive.target.includes("{")) throwDiagnostic(classifyReaderBoundaryDiagnostic({
@@ -3064,7 +3113,7 @@ function validateIncludeGraph(absolutePath, documentRoot, stack) {
 			}));
 		}
 		if (selectionSurface(attributes) || !asciidocExtensionPattern.test(includePath)) continue;
-		validateIncludeGraph(includePath, documentRoot, nextStack);
+		validateIncludeGraph(includePath, documentRoot, nextStack, includeResolvers);
 	}
 }
 async function preprocessBookEntryWithOfficialReader(options) {
@@ -3072,13 +3121,21 @@ async function preprocessBookEntryWithOfficialReader(options) {
 	const documentRoot = normalizeDocumentRoot(options.documentRoot);
 	relativePathWithinDocumentRoot(documentRoot, entryPath);
 	if (!existsSync(entryPath)) throw constructionError("entry.missing-source", `Entry source file does not exist: ${entryPath}.`);
-	validateIncludeGraph(entryPath, documentRoot, []);
+	const includeResolvers = options.includeResolvers ?? [];
+	validateIncludeGraph(entryPath, documentRoot, [], includeResolvers);
 	const state = {
 		documentRoot,
-		officialLines: await options.adapter.readPreprocessedLines(readerPreprocessingOptions({
-			sourcePath: entryPath,
-			attributes: options.attributes
-		})),
+		includeResolvers,
+		officialLines: await options.adapter.readPreprocessedLines({
+			...readerPreprocessingOptions({
+				sourcePath: entryPath,
+				attributes: options.attributes
+			}),
+			includeResolution: {
+				resolvers: includeResolvers,
+				documentRoot
+			}
+		}),
 		sourceSet: createSourceSet({ documentRoot }),
 		records: [],
 		diagnostics: [],
@@ -3128,6 +3185,10 @@ function appendSourceFile(absolutePath, state) {
 	}
 }
 function appendIncludeDirective(containingFile, line, directive, state) {
+	if (claimingResolver(state.includeResolvers, directive.target)) {
+		appendResolvedInclude(containingFile, line, directive, state);
+		return;
+	}
 	const attributes = parseIncludeAttributes(directive.attrlist);
 	state.diagnostics.push(...attributes.diagnostics);
 	if (attributes.classification === "unmapped") {
@@ -3166,18 +3227,40 @@ function appendIncludeDirective(containingFile, line, directive, state) {
 	}
 	const targetFile = state.sourceSet.registerFile(includePath);
 	const selector = selectionSurface(attributes);
+	appendPushedInclude(containingFile, line, targetFile, attributes, selector ? {
+		selector,
+		selection: mapIncludeSelection(targetFile.text, selector)
+	} : void 0, state);
+}
+function appendResolvedInclude(containingFile, line, directive, state) {
+	const first = state.officialLines[state.officialIndex];
+	const resolved = first && first.push.depth === state.currentPush.depth + 1 ? first.push.resolved : void 0;
+	if (!resolved || resolved.target !== directive.target) return;
+	appendPushedInclude(containingFile, line, state.sourceSet.registerFile(resolved.absolutePath), parseIncludeAttributes(directive.attrlist), {
+		selector: {
+			kind: "resolver",
+			target: directive.target
+		},
+		selection: {
+			ok: true,
+			lines: Array.from({ length: resolved.lineCount }, (_, index) => resolved.startLine + index)
+		}
+	}, state);
+}
+function appendPushedInclude(containingFile, line, targetFile, attributes, selected, state) {
+	const includePath = targetFile.absolutePath;
 	const leveloffset = hasLeveloffsetSurface(attributes);
 	const parent = state.currentPush;
 	const first = state.officialLines[state.officialIndex];
-	const selection = selector ? mapIncludeSelection(targetFile.text, selector) : void 0;
+	const selection = selected?.selection;
 	const candidate = first && first.push.depth === parent.depth + 1 && selection?.ok !== false ? first.push : void 0;
 	const own = candidate && state.officialLines.slice(state.officialIndex, pushEnd(candidate, state)).some((official) => official.push.id === candidate.id && official.cursor.file === includePath) ? candidate : void 0;
 	const end = own ? pushEnd(own, state) : state.officialIndex;
 	state.currentPush = own ?? parent;
 	consumeGeneratedPreludeForInclude(leveloffset, own, state);
-	if (selector && selection) appendSelectedInclude(targetFile, selector, indentSurface(attributes), state, `${containingFile.relativePath}:${line.number}`, selection, own, leveloffset ? generatedTailStart(end, state) : end);
+	if (selected) appendSelectedInclude(targetFile, selected.selector, indentSurface(attributes), state, `${containingFile.relativePath}:${line.number}`, selected.selection, own, leveloffset ? generatedTailStart(end, state) : end);
 	else appendFullFileInclude(targetFile, indentSurface(attributes), state);
-	if (leveloffset && own) consumeGeneratedTailForInclude(state);
+	if (leveloffset && own) consumeGeneratedTailForInclude(own, state);
 	state.currentPush = parent;
 }
 function pushEnd(own, state) {
@@ -3265,7 +3348,11 @@ function degradeRestOfPush(targetFile, selector, includeSite, bodyEnd, state) {
 	});
 }
 function selectorSurface(selector) {
-	return selector.kind === "tag" ? `tag=${selector.name}` : `${selector.kind}=${selector.expression}`;
+	switch (selector.kind) {
+		case "tag": return `tag=${selector.name}`;
+		case "resolver": return `the resolver for ${selector.target}`;
+		default: return `${selector.kind}=${selector.expression}`;
+	}
 }
 function sameLine(officialText, sourceText, indent) {
 	const official = officialText.trimEnd();
@@ -3348,15 +3435,13 @@ function consumeGeneratedPreludeForInclude(hasLeveloffset, own, state) {
 	const blank = state.officialLines[state.officialIndex];
 	if (blank?.push.id === own.id && blank.text === "") appendGeneratedControl(consumeOfficialLine(state)?.text ?? "", state);
 }
-function consumeGeneratedTailForInclude(state) {
+function consumeGeneratedTailForInclude(own, state) {
 	while (state.officialIndex < state.officialLines.length) {
 		const next = state.officialLines[state.officialIndex];
-		if (!next || !(next.text === "" || next.text.startsWith(":leveloffset"))) break;
-		const official = consumeOfficialLine(state);
-		if (official?.text.startsWith(":leveloffset")) {
-			appendGeneratedControl(official.text, state);
-			break;
-		}
+		if (!next || next.push.id !== own.id || !(next.text === "" || next.text.startsWith(":leveloffset"))) break;
+		consumeOfficialLine(state);
+		appendGeneratedControl(next.text, state);
+		if (next.text.startsWith(":leveloffset")) break;
 	}
 }
 function consumeUnmappedOfficialTail(state) {
@@ -3853,8 +3938,8 @@ function recoveryFailure(code, message, source) {
 }
 //#endregion
 //#region src/official-block-policy.ts
-function officialBlockPolicy(context) {
-	switch (context) {
+function officialBlockPolicy(block) {
+	switch (block.getContext?.()) {
 		case "admonition":
 		case "dlist":
 		case "list_item":
@@ -3862,12 +3947,13 @@ function officialBlockPolicy(context) {
 		case "table":
 		case "verse": return "scan";
 		case "example":
-		case "olist":
 		case "quote":
-		case "section":
 		case "sidebar":
-		case "ulist":
-		case "open": return "recurse";
+		case "open": return block.getContentModel?.() === "simple" ? "scan" : "recurse";
+		case "olist":
+		case "preamble":
+		case "section":
+		case "ulist": return "recurse";
 		case "listing":
 		case "literal":
 		case "pass":
@@ -3926,7 +4012,6 @@ function projectOfficialDocument(options) {
 		usedAnchorKeys: /* @__PURE__ */ new Set(),
 		intervalByBlock: options.intervalByBlock,
 		projectableBlocks: options.projectableBlocks,
-		containerFallbackBlocks: options.containerFallbackBlocks,
 		sectionByBlock: options.sectionByBlock,
 		bindingRequests,
 		targets,
@@ -3944,19 +4029,18 @@ function buildChildren(officialDocument, context) {
 	for (const block of childBlocksOf(officialDocument)) topLevel.push(...toNodes(buildNode(block, context)));
 	return topLevel;
 }
-function buildNode(block, context, fallbackLine) {
+function buildNode(block, context) {
 	const blockContext = block.getContext?.();
 	const officialLine = block.getSourceLocation?.()?.getLineNumber?.();
-	const line = officialLine ?? fallbackLine;
 	const interval = context.intervalByBlock.get(block);
-	if (!canProjectBlock(block, context, officialLine, fallbackLine)) return;
+	if (!canProjectBlock(block, context)) return;
 	if (blockContext === "section" && officialLine !== void 0) return buildSection(block, context);
-	if (blockContext === "paragraph" && line !== void 0) return buildParagraph(block, line, context, interval);
+	if (blockContext === "paragraph" && officialLine !== void 0) return buildParagraph(block, officialLine, context, interval);
 	if (blockContext === "listing" && officialLine !== void 0) return buildListing(block, officialLine, context, interval);
 	if (blockContext === "table" && officialLine !== void 0) return buildTable(block, officialLine, context, interval);
 	if (blockContext === "dlist" && officialLine !== void 0) return buildDescriptionList(block, officialLine, context, interval);
-	if (blockContext === "open" && line !== void 0) return buildOpenChildren(block, line, context);
-	if (officialBlockPolicy(blockContext) === "diagnostic") return;
+	if (blockContext === "open" && officialLine !== void 0) return childBlocksOf(block).flatMap((child) => toNodes(buildNode(child, context)));
+	if (officialBlockPolicy(block) === "diagnostic") return;
 	if (officialLine !== void 0) {
 		registerOfficialBlockTarget(context, block, {
 			targetType: "block",
@@ -3968,10 +4052,8 @@ function buildNode(block, context, fallbackLine) {
 		return childBlocksOf(block).flatMap((child) => toNodes(buildNode(child, context)));
 	}
 }
-function canProjectBlock(block, context, officialLine, fallbackLine) {
-	if (!context.projectableBlocks) return true;
-	if (context.projectableBlocks.has(block)) return true;
-	return officialLine === void 0 && fallbackLine !== void 0 && (context.containerFallbackBlocks?.has(block) ?? false);
+function canProjectBlock(block, context) {
+	return context.projectableBlocks?.has(block) ?? true;
 }
 function buildSection(block, context) {
 	const section = context.sectionByBlock.get(block);
@@ -3997,16 +4079,6 @@ function buildSection(block, context) {
 	section.children = childBlocksOf(block).flatMap((child) => toNodes(buildNode(child, context)));
 	return section;
 }
-function buildOpenChildren(block, line, context) {
-	const nodes = [];
-	let cursor = line;
-	for (const child of childBlocksOf(block)) {
-		const built = toNodes(buildNode(child, context, child.getSourceLocation?.()?.getLineNumber?.() ?? findBlockSourceLine(context, child, cursor)));
-		nodes.push(...built);
-		cursor = Math.max(cursor, ...built.map(nodeEndLine).filter(isNumber)) + 1;
-	}
-	return nodes;
-}
 function buildDescriptionList(block, startLine, context, interval) {
 	const metadata = interval?.metadata ?? [];
 	const span = interval?.span ?? {
@@ -4238,17 +4310,6 @@ function sourceSpanOf(node) {
 function isLineSpan(value) {
 	return value !== void 0;
 }
-function findBlockSourceLine(context, block, startLine) {
-	const firstSourceLine = block.getSource?.()?.split(/\r?\n/u).find((line) => line.trim() !== "")?.trim();
-	if (!firstSourceLine) return;
-	for (let line = startLine; line <= context.lineTable.lines.length; line += 1) if (lineText(context.lineTable, line).trim() === firstSourceLine) return line;
-}
-function nodeEndLine(node) {
-	return node.source?.span?.endLine ?? node.source?.line;
-}
-function isNumber(value) {
-	return typeof value === "number";
-}
 function buildParagraph(block, line, context, interval) {
 	const blockSpan = interval?.span ?? {
 		startLine: line,
@@ -4513,6 +4574,37 @@ function isRecord$1(value) {
 	return value !== null && typeof value === "object";
 }
 //#endregion
+//#region src/official-source-location.ts
+const takenFromParent = /* @__PURE__ */ new WeakSet();
+const borrowedFromChild = /* @__PURE__ */ new WeakSet();
+function completeSynthesizedSourceLocations(officialDocument) {
+	for (const block of childBlocksOf(officialDocument)) complete(block, void 0);
+}
+function takesParentSourceLocation(block) {
+	return takenFromParent.has(block);
+}
+function borrowsChildSourceLocation(block) {
+	return borrowedFromChild.has(block);
+}
+function complete(block, parent) {
+	if (!block.getSourceLocation?.() && block.getContext?.() === "paragraph" && parent?.getContext?.() === "open") {
+		locate(block, parent.getSourceLocation?.());
+		takenFromParent.add(block);
+	}
+	const children = childBlocksOf(block);
+	for (const child of children) complete(child, block);
+	if (!block.getSourceLocation?.() && block.getContext?.() === "open") {
+		const location = children.find((child) => child.getSourceLocation?.())?.getSourceLocation?.();
+		if (location) {
+			locate(block, location);
+			borrowedFromChild.add(block);
+		}
+	}
+}
+function locate(block, location) {
+	if (location) block.sourceLocation = location;
+}
+//#endregion
 //#region src/book-entry/source-scope-index.ts
 const sectionSourceScopeBySection = /* @__PURE__ */ new WeakMap();
 function registerSectionSourceScope(section, scope) {
@@ -4582,7 +4674,7 @@ function scanInlineOccurrencesInOfficialBlocks(options) {
 		}
 		if (interval.metadataSpan) scanMetadataRange(options.lineTable, interval.metadataSpan.startLine, interval.metadataSpan.endLine, xrefOccurrences, anchorOccurrences);
 		const span = interval.contentSpan ?? interval.span;
-		if (officialBlockPolicy(surface.context) !== "scan") continue;
+		if (officialBlockPolicy(surface.block) !== "scan") continue;
 		if (!scansMacroSubstitutedContent(surface)) continue;
 		if (surface.context === "table") scanTableInlineRange(options.lineTable, surface.block, span.startLine, span.endLine, xrefOccurrences, anchorOccurrences, headingInlineMetadataOccurrences, options.toolDiagnostics);
 		else scanInlineRange(options.lineTable, span.startLine, span.endLine, xrefOccurrences, anchorOccurrences, headingInlineMetadataOccurrences, options.toolDiagnostics, descendantUnscannableRanges(surface, options.intervalByBlock));
@@ -4630,7 +4722,7 @@ function recoverSourceAwareInlineOrigins(occurrences, sourceAwareDocument, toolD
 function hasDiagnosticPolicyAncestor$1(surface) {
 	let current = surface.parent;
 	while (current) {
-		if (officialBlockPolicy(current.context) === "diagnostic") return true;
+		if (officialBlockPolicy(current.block) === "diagnostic") return true;
 		current = current.parent;
 	}
 	return false;
@@ -4827,7 +4919,7 @@ function descendantUnscannableRanges(surface, intervalByBlock) {
 	return mergeLineSpans(ranges);
 }
 function collectUnscannableRanges(surface, intervalByBlock, ranges) {
-	const policy = officialBlockPolicy(surface.context);
+	const policy = officialBlockPolicy(surface.block);
 	const interval = intervalByBlock.get(surface.block);
 	if (policy === "skip" || policy === "diagnostic") {
 		if (interval) ranges.push(interval.span);
@@ -5112,6 +5204,85 @@ function parseStyleIdRoles(part) {
 	});
 }
 //#endregion
+//#region src/official-delimiter.ts
+const DELIMITED_BLOCKS = {
+	"--": ["open", new Set([
+		"comment",
+		"example",
+		"literal",
+		"listing",
+		"pass",
+		"quote",
+		"sidebar",
+		"source",
+		"verse",
+		"admonition",
+		"abstract",
+		"partintro"
+	])],
+	"----": ["listing", new Set(["literal", "source"])],
+	"....": ["literal", new Set(["listing", "source"])],
+	"====": ["example", new Set(["admonition"])],
+	"****": ["sidebar", /* @__PURE__ */ new Set()],
+	____: ["quote", new Set(["verse"])],
+	"++++": ["pass", new Set([
+		"stem",
+		"latexmath",
+		"asciimath"
+	])],
+	"|===": ["table", /* @__PURE__ */ new Set()],
+	",===": ["table", /* @__PURE__ */ new Set()],
+	":===": ["table", /* @__PURE__ */ new Set()],
+	"!===": ["table", /* @__PURE__ */ new Set()],
+	"~~~~": ["open", new Set(["abstract", "partintro"])],
+	"////": ["comment", /* @__PURE__ */ new Set()],
+	"```": ["fenced_code", /* @__PURE__ */ new Set()]
+};
+const DELIMITED_BLOCK_HEADS = new Set(Object.keys(DELIMITED_BLOCKS).map((delimiter) => delimiter.slice(0, 2)));
+const DELIMITED_BLOCK_TAILS = Object.fromEntries(Object.keys(DELIMITED_BLOCKS).filter((delimiter) => delimiter.length === 4).map((delimiter) => [delimiter, delimiter.slice(-1)]));
+function officialDelimiter(line) {
+	let candidate = line;
+	let lineLength = candidate.length;
+	if (lineLength < 2 || !DELIMITED_BLOCK_HEADS.has(candidate.slice(0, 2))) return;
+	let tip;
+	let tipLength;
+	if (lineLength === 2) {
+		tip = candidate;
+		tipLength = 2;
+	} else {
+		tipLength = lineLength < 5 ? lineLength : 4;
+		tip = candidate.slice(0, tipLength);
+		if (tip.startsWith("`")) {
+			if (tipLength === 4) {
+				if (tip === "````") return;
+				tip = tip.slice(0, 3);
+				if (tip !== "```") return;
+				candidate = tip;
+				lineLength = 3;
+				tipLength = 3;
+			} else if (tip !== "```") return;
+		} else if (tipLength === 3) return;
+	}
+	const entry = DELIMITED_BLOCKS[tip];
+	if (!entry) return;
+	const tail = DELIMITED_BLOCK_TAILS[tip];
+	if (!(lineLength === tipLength || tail !== void 0 && isUniform(candidate.slice(1), tail))) return;
+	const [context, masq] = entry;
+	return {
+		context,
+		masq,
+		terminator: candidate
+	};
+}
+function delimiterOpens(delimiter, context, style) {
+	if (context === void 0) return false;
+	if (delimiter.context === "fenced_code") return context === "listing";
+	return delimiter.context === context || delimiter.masq.has(context) || style !== null && style !== void 0 && delimiter.masq.has(style);
+}
+function isUniform(text, character) {
+	return [...text].every((each) => each === character);
+}
+//#endregion
 //#region src/source-interval-resolver.ts
 function resolveSourceInterval(surface, lineTable) {
 	if (surface.sourceLine === void 0) return;
@@ -5119,11 +5290,14 @@ function resolveSourceInterval(surface, lineTable) {
 	const metadata = metadataForSurface(surface, lineTable, blockStartLine);
 	const startLine = metadata.at(0)?.line ?? blockStartLine;
 	const diagnostics = [];
-	const delimited = resolveContextDelimitedSpan(lineTable, blockStartLine, surface.context);
-	const sourceContentSpan = sourceContentSpanForContext(surface, blockStartLine);
+	const delimitedContext = isDelimitedContext(surface.context);
+	const synthesized = borrowsChildSourceLocation(surface.block);
+	const delimited = delimitedContext ? resolveDelimitedBlockSpan(lineTable, blockStartLine, surface) : void 0;
+	const undelimited = delimitedContext && delimited === void 0 && !synthesized ? resolveUndelimitedBlockSpan(lineTable, blockStartLine, surface) : void 0;
+	const sourceContentSpan = sourceContentSpanForContext(surface, lineTable, blockStartLine);
 	const nextSiblingStart = nextSiblingStartLine(surface, lineTable);
 	const childEndLine = surface.context === "dlist" ? lastChildEndLine(surface, lineTable) : void 0;
-	const endLine = delimited?.span.endLine ?? sourceContentSpan?.endLine ?? childEndLine ?? (nextSiblingStart !== void 0 ? nextSiblingStart - 1 : void 0) ?? parentEndLine(surface, lineTable) ?? lineTable.lines.length;
+	const endLine = delimited?.span.endLine ?? undelimited?.endLine ?? sourceContentSpan?.endLine ?? childEndLine ?? (nextSiblingStart !== void 0 ? nextSiblingStart - 1 : void 0) ?? parentEndLine(surface, lineTable) ?? lineTable.lines.length;
 	const span = normalizeLineSpan({
 		startLine,
 		endLine: Math.max(startLine, endLine)
@@ -5132,13 +5306,13 @@ function resolveSourceInterval(surface, lineTable) {
 		startLine,
 		endLine: blockStartLine - 1
 	} : void 0;
-	if (delimited === void 0 && isDelimitedContext(surface.context) && blockStartLine <= lineTable.lines.length) diagnostics.push({
+	if (delimitedContext && delimited === void 0 && undelimited === void 0 && !synthesized && blockStartLine <= lineTable.lines.length) diagnostics.push({
 		level: "warning",
 		code: "source-interval.delimiter-not-found",
 		message: `Could not locate ${surface.context} block delimiter from official source line ${blockStartLine}.`,
 		source: spanForLineText(lineTable, blockStartLine, 1)
 	});
-	const contentSpan = delimited?.contentSpan ?? sourceContentSpan ?? contentSpanForContext(surface, span);
+	const contentSpan = delimited?.contentSpan ?? undelimited ?? sourceContentSpan ?? contentSpanForContext(surface, span);
 	const sourceSpan = sourceSpanFromLineSpan(lineTable, span);
 	const titleSpan = titleSpanForSurface(surface, lineTable);
 	return {
@@ -5160,6 +5334,7 @@ function nextSiblingStartLine(surface, lineTable) {
 }
 function metadataForSurface(surface, lineTable, blockStartLine) {
 	if (surface.context === "list_item") return [];
+	if (takesParentSourceLocation(surface.block)) return [];
 	return collectPrecedingMetadata(lineTable, blockStartLine);
 }
 function lastChildEndLine(surface, lineTable) {
@@ -5175,25 +5350,10 @@ function parentEndLine(surface, lineTable) {
 	if (!parent) return lineTable.lines.length;
 	return resolveSourceInterval(parent, lineTable)?.span.endLine;
 }
-function resolveContextDelimitedSpan(lineTable, startLine, context) {
-	switch (context) {
-		case "example": return resolveDelimitedBlockSpan(lineTable, startLine, ["===="]);
-		case "listing": return resolveDelimitedBlockSpan(lineTable, startLine, ["----", "```"]);
-		case "literal": return resolveDelimitedBlockSpan(lineTable, startLine, ["...."]);
-		case "pass": return resolveDelimitedBlockSpan(lineTable, startLine, ["++++"]);
-		case "open": return resolveDelimitedBlockSpan(lineTable, startLine, ["--"]);
-		case "quote":
-		case "verse": return resolveDelimitedBlockSpan(lineTable, startLine, ["____"]);
-		case "sidebar": return resolveDelimitedBlockSpan(lineTable, startLine, ["****"]);
-		case "stem": return resolveDelimitedBlockSpan(lineTable, startLine, ["++++"]);
-		case "table": return resolveDelimitedBlockSpan(lineTable, startLine, ["|==="]);
-		default: return;
-	}
-}
-function resolveDelimitedBlockSpan(lineTable, startLine, allowedDelimiters) {
-	const opening = lineText(lineTable, startLine).trim();
-	if (!allowedDelimiters.includes(opening)) return;
-	for (let line = startLine + 1; line <= lineTable.lines.length; line += 1) if (lineText(lineTable, line).trim() === opening) return {
+function resolveDelimitedBlockSpan(lineTable, startLine, surface) {
+	const delimiter = officialDelimiter(lineText(lineTable, startLine).trimEnd());
+	if (!delimiter || !delimiterOpens(delimiter, surface.context, surface.block.getStyle?.())) return;
+	for (let line = startLine + 1; line <= lineTable.lines.length; line += 1) if (lineText(lineTable, line).trimEnd() === delimiter.terminator) return {
 		span: {
 			startLine,
 			endLine: line
@@ -5204,6 +5364,42 @@ function resolveDelimitedBlockSpan(lineTable, startLine, allowedDelimiters) {
 		}
 	};
 }
+function resolveUndelimitedBlockSpan(lineTable, startLine, surface) {
+	const firstLine = firstSourceLine(surface);
+	if (firstLine === void 0 || withoutWhitespace(lineText(lineTable, startLine)) !== withoutWhitespace(firstLine)) return;
+	if (surface.children.length > 0) {
+		const childEnds = surface.children.map((child) => resolveSourceInterval(child, lineTable)?.span.endLine).filter((line) => line !== void 0);
+		return {
+			startLine,
+			endLine: Math.max(startLine, ...childEnds)
+		};
+	}
+	return {
+		startLine,
+		endLine: lastSourceLine(lineTable, startLine, surface.block)
+	};
+}
+function withoutWhitespace(text) {
+	return text.replace(/\s+/gu, "");
+}
+function lastSourceLine(lineTable, startLine, block) {
+	const count = Math.max(1, block.getSourceLines?.().length ?? block.getSource?.().split(/\r?\n/u).length ?? 1);
+	const skipsLineComments = block.getContentModel?.() !== "verbatim";
+	let counted = 0;
+	for (let line = startLine; line <= lineTable.lines.length; line += 1) {
+		const text = lineText(lineTable, line);
+		if (skipsLineComments && text.startsWith("//") && !text.startsWith("///")) continue;
+		counted += 1;
+		if (counted === count) return line;
+	}
+	return Math.max(startLine, lineTable.lines.length);
+}
+function firstSourceLine(surface) {
+	const own = surface.block.getSourceLines?.()[0];
+	if (own !== void 0) return own;
+	const firstChild = surface.children[0];
+	return firstChild ? firstSourceLine(firstChild) : void 0;
+}
 function contentSpanForContext(surface, span) {
 	if (surface.context === "paragraph") return {
 		startLine: surface.sourceLine ?? span.startLine,
@@ -5217,13 +5413,12 @@ function contentSpanForContext(surface, span) {
 		};
 	}
 }
-function sourceContentSpanForContext(surface, startLine) {
+function sourceContentSpanForContext(surface, lineTable, startLine) {
 	if (surface.context !== "paragraph" && surface.context !== "admonition") return;
-	const source = surface.block.getSource?.();
-	if (source === void 0) return;
+	if (surface.block.getSourceLines === void 0 && surface.block.getSource === void 0) return;
 	return {
 		startLine,
-		endLine: startLine + Math.max(1, source.split(/\r?\n/u).length) - 1
+		endLine: lastSourceLine(lineTable, startLine, surface.block)
 	};
 }
 function titleSpanForSurface(surface, lineTable) {
@@ -5266,13 +5461,12 @@ function projectSourceSurfaces(options) {
 	const blockSurfaces = walkOfficialBlocks(options.officialDocument);
 	const intervalByBlock = /* @__PURE__ */ new WeakMap();
 	const projectableBlocks = /* @__PURE__ */ new WeakSet();
-	const containerFallbackBlocks = /* @__PURE__ */ new WeakSet();
 	const toolDiagnostics = [];
 	const mainSourcePath = options.sourcePath ? options.sourceIdentity.normalize(options.sourceIdentity.resolve(options.sourcePath)) : void 0;
 	const sourceAwareDocument = sourceAwareDocumentForLineTable(options.lineTable);
 	const logicalSource = logicalSourceForLineTable(options.lineTable);
 	for (const surface of blockSurfaces) {
-		const policy = officialBlockPolicy(surface.context);
+		const policy = officialBlockPolicy(surface.block);
 		if (isExternalSourceSurface(surface, mainSourcePath, options.sourceIdentity)) {
 			if (policy === "diagnostic") toolDiagnostics.push(unknownContextDiagnostic(surface));
 			toolDiagnostics.push({
@@ -5289,7 +5483,6 @@ function projectSourceSurfaces(options) {
 				code: "source-location.missing",
 				message: `Official block source location is missing for context '${surface.context ?? "undefined"}' node '${surface.nodeName ?? "undefined"}'.`
 			});
-			if (canUseContainerFallbackSurface(surface, policy)) containerFallbackBlocks.add(surface.block);
 			continue;
 		}
 		const interval = resolveSourceInterval(surface, options.lineTable);
@@ -5333,7 +5526,6 @@ function projectSourceSurfaces(options) {
 		blockSurfaces,
 		intervalByBlock,
 		projectableBlocks,
-		containerFallbackBlocks,
 		sectionByBlock,
 		sections,
 		xrefOccurrences,
@@ -5366,9 +5558,6 @@ function unknownContextDiagnostic(surface, interval) {
 		source: interval?.sourceSpan
 	});
 }
-function canUseContainerFallbackSurface(surface, policy) {
-	return surface.context === "paragraph" && policy === "scan" && !hasDiagnosticPolicyAncestor(surface);
-}
 function buildSectionSurfaces(blockSurfaces, intervalByBlock, lineTable, toolDiagnostics, logicalSource, sourceAwareDocument) {
 	const sections = [];
 	const sectionByBlock = /* @__PURE__ */ new WeakMap();
@@ -5486,7 +5675,7 @@ function sourceAwareOriginForLine(document, logicalLine) {
 function hasDiagnosticPolicyAncestor(surface) {
 	let current = surface.parent;
 	while (current) {
-		if (officialBlockPolicy(current.context) === "diagnostic") return true;
+		if (officialBlockPolicy(current.block) === "diagnostic") return true;
 		current = current.parent;
 	}
 	return false;
@@ -5503,6 +5692,7 @@ function mapSectionScope(sections, totalLines) {
 //#endregion
 //#region src/parser-core.ts
 async function parseAsciidoctorDocument(input) {
+	completeSynthesizedSourceLocations(input.officialDocument);
 	const sourceSurfaces = projectSourceSurfaces({
 		officialDocument: input.officialDocument,
 		lineTable: input.lineTable,
@@ -5519,7 +5709,6 @@ async function parseAsciidoctorDocument(input) {
 		headingInlineMetadataOccurrences: sourceSurfaces.headingInlineMetadataOccurrences,
 		intervalByBlock: sourceSurfaces.intervalByBlock,
 		projectableBlocks: sourceSurfaces.projectableBlocks,
-		containerFallbackBlocks: sourceSurfaces.containerFallbackBlocks,
 		sectionByBlock: sourceSurfaces.sectionByBlock
 	});
 	await resolveOfficialBindings(officialProjection.bindingRequests, input.officialDocument, input.adapter);
@@ -5587,7 +5776,8 @@ async function parseAbundantTree(options) {
 		const sourceAwareDocument = await preprocessBookEntryWithOfficialReader({
 			adapter,
 			sourcePath,
-			documentRoot: options.documentRoot
+			documentRoot: options.documentRoot,
+			includeResolvers: options.includeResolvers
 		});
 		const constructionDiagnostic = sourceAwareDocument.diagnostics.find((diagnostic) => diagnostic.level === "error");
 		if (constructionDiagnostic) throw constructionError(constructionDiagnostic.code, constructionDiagnostic.message, constructionDiagnostic.source);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "asciidoc-abundant-tree",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Recover a source-aware, analysis-ready tree from AsciiDoc files and explicit book-entry include graphs.",
 	"license": "Apache-2.0",
 	"author": {