@effected/markdown 0.20.0 → 0.22.0

package/Frontmatter.js

@@ -1,6 +1,6 @@
 import { MarkdownEdit } from "./MarkdownEdit.js";
 import { FrontmatterFormat } from "./MarkdownNode.js";
-import { Effect, Schema } from "effect";
+import { Effect, Option, Schema } from "effect";
 
 // src/Frontmatter.ts
 /**
@@ -212,7 +212,7 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 	*/
 	static schema(schema, codec) {
 		return (document) => {
-			const node = document.frontmatter;
+			const node = Option.getOrUndefined(document.frontmatter);
 			return node === void 0 ? Effect.fail(new FrontmatterMissingError({ reason: document.hasFrontmatterBlock ? "captureDisabled" : "absent" })) : codec.decode(node).pipe(Effect.flatMap((data) => Schema.decodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new FrontmatterValidationError({ issue: error.issue }))))));
 		};
 	}
@@ -258,7 +258,7 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 	*/
 	static set(schema, codec) {
 		return (document, data) => {
-			const node = document.frontmatter;
+			const node = Option.getOrUndefined(document.frontmatter);
 			if (node !== void 0 && node.format !== codec.format) return Effect.fail(new FrontmatterFormatMismatchError({
 				expected: codec.format,
 				actual: node.format

package/FrontmatterResolver.js

@@ -1,4 +1,4 @@
-import { Effect, Result, Schema } from "effect";
+import { Effect, Option, Predicate, Result, Schema } from "effect";
 
 // src/FrontmatterResolver.ts
 /**
@@ -140,7 +140,6 @@ const parseVersionSegments = (version) => {
 	if (!/^\d+(\.\d+){0,2}$/.test(version)) return;
 	return version.split(".").map((segment) => Number.parseInt(segment, 10));
 };
-const isMapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
 * The `$schema` declaration classifier and the package's one built-in
 * resolver implementation.
@@ -184,30 +183,17 @@ var SchemaResolver = class SchemaResolver {
 				version
 			}));
 		}
-		if (isMapping(value)) return Result.succeed(new SchemaDeclarationInline({ document: value }));
+		if (Predicate.isObject(value)) return Result.succeed(new SchemaDeclarationInline({ document: value }));
 		return Result.fail(new SchemaDeclarationInvalidError({
 			reason: "the declaration is neither a string nor a mapping",
 			value
 		}));
 	}
-	/**
-	* Extract and classify the `$schema` declaration from decoded frontmatter
-	* data.
-	*
-	* @remarks
-	* Non-mapping data and a mapping without a `$schema` key both carry no
-	* declaration: the result succeeds with `undefined` by default, or fails
-	* with {@link SchemaDeclarationMissingError} under `requireDeclaration`.
-	*
-	* @param data - The decoded frontmatter data.
-	* @param options - `requireDeclaration` makes a missing `$schema` a typed
-	*   error.
-	* @returns The classified declaration, `undefined` when absent and
-	*   tolerated, or the typed error.
-	*/
 	static declarationOf(data, options) {
-		if (!isMapping(data) || !Object.hasOwn(data, "$schema")) return options?.requireDeclaration === true ? Result.fail(new SchemaDeclarationMissingError()) : Result.succeed(void 0);
-		return SchemaResolver.classify(data.$schema);
+		const required = options?.requireDeclaration === true;
+		if (!Predicate.isObject(data) || !Object.hasOwn(data, "$schema")) return required ? Result.fail(new SchemaDeclarationMissingError()) : Result.succeed(Option.none());
+		const classified = SchemaResolver.classify(data.$schema);
+		return required ? classified : Result.map(classified, Option.some);
 	}
 	/**
 	* The package's one built-in resolver: a name-keyed registry with

package/MarkdownDocument.js

@@ -6,7 +6,7 @@ import { normalizeLabelText } from "./internal/references.js";
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
 import { parsePassResult } from "./Markdown.js";
 import { rootHeadingBounds } from "./internal/sectionBounds.js";
-import { Effect, Result, Schema } from "effect";
+import { Effect, Option, Result, Schema } from "effect";
 
 // src/MarkdownDocument.ts
 /**
@@ -167,19 +167,26 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	definitions: Schema.ReadonlyMap(Schema.String, Definition)
 }) {
 	/**
-	* The document's frontmatter capture, or `undefined` when there is none.
+	* The document's frontmatter capture, or `Option.none()` when there is
+	* none.
 	*
 	* @remarks
 	* Derived from the tree rather than stored: a {@link Frontmatter} node can
 	* only ever sit at the head of `root.children` (the capture fires at most
 	* once, at offset 0), so the tree is the single source of truth and the
-	* accessor can never disagree with it. `undefined` covers both a document
-	* with no frontmatter block and one parsed with the capture toggle off —
-	* {@link MarkdownDocument.hasFrontmatterBlock} tells the two apart.
+	* accessor can never disagree with it. `Option.none()` covers both a
+	* document with no frontmatter block and one parsed with the capture toggle
+	* off — {@link MarkdownDocument.hasFrontmatterBlock} tells the two apart.
+	*
+	* An `Option` rather than `Frontmatter | undefined` because this is a
+	* lookup that can miss, and the kit's lookups return `Option` — the same
+	* shape as the sibling format packages' tree lookups (`JsoncNode.find`,
+	* `YamlNode.find`). A derived getter is a lookup, not a data field: it
+	* recomputes from the tree on every access.
 	*/
 	get frontmatter() {
 		const head = this.root.children[0];
-		return head !== void 0 && head.type === "frontmatter" ? head : void 0;
+		return head !== void 0 && head.type === "frontmatter" ? Option.some(head) : Option.none();
 	}
 	/**
 	* Whether the source opens with a well-formed frontmatter block —
@@ -187,10 +194,10 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	*
 	* @remarks
 	* The structural signal that disambiguates the `frontmatter` accessor's
-	* `undefined`: capture is opt-in (`MarkdownParseOptions.frontmatter`
+	* `Option.none()`: capture is opt-in (`MarkdownParseOptions.frontmatter`
 	* defaults off), so a document whose source visibly starts with `---` can
 	* still carry no capture node — spec-correct CommonMark reads the fences as
-	* a thematic break plus content. `frontmatter === undefined` with
+	* a thematic break plus content. An empty `frontmatter` with
 	* `hasFrontmatterBlock === true` means exactly "parsed with capture off";
 	* with `false` it means the source genuinely has no block.
 	*
@@ -274,11 +281,12 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	* document repeatedly should bind `document.sections` once instead.
 	*
 	* @param options - Depth restriction.
-	* @returns The first matching section, or `undefined`.
+	* @returns The first matching section, or `Option.none()` when no section
+	*   matches.
 	*/
 	firstSection(options) {
 		const depth = options?.depth;
-		return this.sections.find((section) => depth === void 0 || section.depth === depth);
+		return Option.fromUndefinedOr(this.sections.find((section) => depth === void 0 || section.depth === depth));
 	}
 	/**
 	* The first section whose heading matches, in document order.
@@ -295,7 +303,8 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	*
 	* @param match - A string, a RegExp, or a predicate.
 	* @param options - Depth restriction, applied before matching.
-	* @returns The first matching section, or `undefined`.
+	* @returns The first matching section, or `Option.none()` when no section
+	*   matches.
 	*/
 	sectionByHeading(match, options) {
 		const depth = options?.depth;
@@ -303,7 +312,7 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 			match.lastIndex = 0;
 			return match.test(section.text.trim());
 		} : (section) => match(section.text, section);
-		return this.sections.find((section) => (depth === void 0 || section.depth === depth) && matches(section));
+		return Option.fromUndefinedOr(this.sections.find((section) => (depth === void 0 || section.depth === depth) && matches(section)));
 	}
 	/**
 	* Every link-bearing node in the document, in document order: links,
@@ -343,7 +352,7 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 		return entries;
 	}
 	find(selector) {
-		return findInTree(this.root, 0, selectorPredicate(selector));
+		return Option.fromUndefinedOr(findInTree(this.root, 0, selectorPredicate(selector)));
 	}
 	findAll(selector) {
 		const predicate = selectorPredicate(selector);

package/MarkdownVisitor.js

@@ -11,8 +11,9 @@ import { Data, Stream } from "effect";
 */
 const MarkdownVisitorEvent = Data.taggedEnum();
 /**
-* Walks a parsed markdown tree as a lazy `Stream` of `Enter`/`Exit` events in
-* document pre-order. Not instantiable.
+* Walks a parsed markdown tree as a lazy sequence of `Enter`/`Exit` events in
+* document pre-order — synchronously with {@link MarkdownVisitor.walk}, or as
+* a `Stream` with {@link MarkdownVisitor.visit}. Not instantiable.
 *
 * @example
 * ```ts
@@ -32,9 +33,52 @@ const MarkdownVisitorEvent = Data.taggedEnum();
 *
 * @public
 */
-var MarkdownVisitor = class {
+var MarkdownVisitor = class MarkdownVisitor {
 	constructor() {}
 	/**
+	* Walk `root` synchronously, as a lazy `Iterable` of `MarkdownVisitorEvent`
+	* in document pre-order: `Enter` and `Exit` for every node including the
+	* root and every leaf. The primitive {@link MarkdownVisitor.visit} is
+	* defined in terms of, so the two yield the same events in the same order.
+	*
+	* @remarks
+	* For callers that cannot suspend — a lint rule whose host calls it
+	* synchronously, a getter, a non-Effect adapter. Events are produced on
+	* demand: a `for…of` that `break`s stops the walk without visiting the
+	* rest of the tree. The iterable is re-iterable — every `[Symbol.iterator]()`
+	* call starts a fresh walk from the root, so binding the result once and
+	* iterating it twice walks the tree twice, independently.
+	*
+	* Not named `walkResult`: it returns no `Result`, and the walk has no
+	* failure channel to put in one. A hand-constructed tree nested past the
+	* depth cap surfaces as a terminal `MarkdownVisitorEvent` `Error` event
+	* carrying a `NestingDepthExceeded` {@link MarkdownDiagnostic}, after which
+	* nothing is yielded — the same posture as `visit`. A tree produced by
+	* `Markdown.parse` or decoded by `Mdast.fromMdast` can never trip it.
+	*
+	* @example
+	* ```ts
+	* import { Markdown, MarkdownVisitor } from "@effected/markdown";
+	* import { Result } from "effect";
+	*
+	* const root = Result.getOrThrow(Markdown.parseResult("# Hi\n\ntext\n"));
+	* const entered: Array<string> = [];
+	* for (const event of MarkdownVisitor.walk(root)) {
+	*   if (event._tag === "Enter") entered.push(event.node.type);
+	* }
+	* console.log(entered);
+	* // => ["root", "heading", "text", "paragraph", "text"]
+	* ```
+	*
+	* @param root - The tree to walk.
+	* @returns A lazy, re-iterable `Iterable` of `MarkdownVisitorEvent`.
+	*/
+	static walk(root) {
+		return { [Symbol.iterator]() {
+			return walkNode(root, [], 0);
+		} };
+	}
+	/**
 	* Create a lazy `Stream` of `MarkdownVisitorEvent` walking `root` in
 	* document pre-order: `Enter` and `Exit` for every node including the
 	* root and every leaf. Events are produced on demand, so combining with
@@ -44,28 +88,24 @@ var MarkdownVisitor = class {
 	* @remarks
 	* Infallible at the type level. A tree produced by `Markdown.parse` can
 	* never trip the walk's depth guard — the parser refuses deeper input —
-	* but a decoded foreign tree (`Mdast.fromMdast`) can; the trip surfaces
-	* as a terminal `MarkdownVisitorEvent` `Error` event carrying a
-	* `NestingDepthExceeded` {@link MarkdownDiagnostic}, mirroring the typed
-	* failure `Markdown.stringify` produces for the same tree.
+	* and neither can a decoded foreign tree (`Mdast.fromMdast`), because the
+	* decode boundary refuses it first; only a hand-constructed tree can trip
+	* the guard. The trip surfaces as a terminal `MarkdownVisitorEvent`
+	* `Error` event carrying a `NestingDepthExceeded` {@link MarkdownDiagnostic},
+	* mirroring the typed failure `Markdown.stringify` produces for the same
+	* tree.
+	*
+	* Defined as `Stream.fromIterable(MarkdownVisitor.walk(root))`: every run
+	* of the stream walks afresh, and the two forms never diverge.
 	*
 	* @param root - The tree to walk.
 	* @returns A lazy `Stream` of `MarkdownVisitorEvent`, infallible at the type
 	*   level.
 	*/
 	static visit(root) {
-		return Stream.fromIterable(walkIterable(root));
+		return Stream.fromIterable(MarkdownVisitor.walk(root));
 	}
 };
-/** Lazy per-subscription iterable so each run of the stream walks afresh. */
-function walkIterable(root) {
-	return { [Symbol.iterator]() {
-		return walk(root)[Symbol.iterator]();
-	} };
-}
-function* walk(root) {
-	yield* walkNode(root, [], 0);
-}
 function* walkNode(node, path, depth) {
 	if (depth > 256) {
 		yield MarkdownVisitorEvent.Error({

package/Mdast.js

@@ -1,6 +1,7 @@
 import { Root } from "./MarkdownNode.js";
 import { unescapeString } from "./internal/unescape.js";
-import { Effect, Result, Schema } from "effect";
+import { GuardExceeded, isGuardExceeded } from "./internal/carriers.js";
+import { Effect, Predicate, Result, Schema, SchemaIssue } from "effect";
 
 // src/Mdast.ts
 /**
@@ -286,10 +287,9 @@ const admittedFields = {
 	mdxTextExpression: ["value"],
 	mdxjsEsm: ["value"]
 };
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const completePoint = (value) => isRecord(value) && typeof value.line === "number" && typeof value.column === "number" && typeof value.offset === "number";
+const completePoint = (value) => Predicate.isObject(value) && typeof value.line === "number" && typeof value.column === "number" && typeof value.offset === "number";
 const normalizePosition = (value) => {
-	if (isRecord(value) && completePoint(value.start) && completePoint(value.end)) {
+	if (Predicate.isObject(value) && completePoint(value.start) && completePoint(value.end)) {
 		const start = value.start;
 		const end = value.end;
 		return {
@@ -307,8 +307,9 @@ const normalizePosition = (value) => {
 	}
 	return sentinelPosition;
 };
-const normalizeNode = (value) => {
-	if (!isRecord(value) || typeof value.type !== "string") return value;
+const normalizeNode = (value, depth = 0) => {
+	if (!Predicate.isObject(value) || typeof value.type !== "string") return value;
+	if (depth > 256) throw new GuardExceeded("NestingDepthExceeded", 256, depth, 0);
 	const type = value.type;
 	const format = frontmatterTypes.get(type);
 	if (format !== void 0) return {
@@ -321,7 +322,7 @@ const normalizeNode = (value) => {
 		type,
 		name: value.name,
 		attributes: Array.isArray(value.attributes) ? value.attributes.map(normalizeMdxAttribute) : value.attributes,
-		children: Array.isArray(value.children) ? value.children.map(normalizeNode) : value.children,
+		children: Array.isArray(value.children) ? value.children.map((child) => normalizeNode(child, depth + 1)) : value.children,
 		position: normalizePosition(value.position)
 	};
 	const admitted = admittedFields[type];
@@ -335,12 +336,12 @@ const normalizeNode = (value) => {
 		const code = normalized.value;
 		normalized.value = code.endsWith("\n") ? code : `${code}\n`;
 	}
-	if (Array.isArray(value.children)) normalized.children = value.children.map(normalizeNode);
+	if (Array.isArray(value.children)) normalized.children = value.children.map((child) => normalizeNode(child, depth + 1));
 	normalized.position = normalizePosition(value.position);
 	return normalized;
 };
 const normalizeMdxAttribute = (value) => {
-	if (!isRecord(value) || typeof value.type !== "string") return value;
+	if (!Predicate.isObject(value) || typeof value.type !== "string") return value;
 	if (value.type === "mdxJsxExpressionAttribute") return {
 		type: "mdxJsxExpressionAttribute",
 		value: value.value,
@@ -353,7 +354,7 @@ const normalizeMdxAttribute = (value) => {
 			name: value.name,
 			position: normalizePosition(value.position)
 		};
-		if (raw !== void 0) normalized.value = isRecord(raw) && raw.type === "mdxJsxAttributeValueExpression" ? {
+		if (raw !== void 0) normalized.value = Predicate.isObject(raw) && raw.type === "mdxJsxAttributeValueExpression" ? {
 			type: "mdxJsxAttributeValueExpression",
 			value: raw.value,
 			position: normalizePosition(raw.position)
@@ -452,12 +453,27 @@ var Mdast = class Mdast {
 	* plain tree built for `Markdown.stringify` can carry it straight in. A
 	* value outside `"canonical" | "literal"` fails the decode typed.
 	*
+	* **Nesting is capped at 256 levels below the root**, the same cap the
+	* parser and `Markdown.stringify` enforce. A tree with any node deeper
+	* than that, leaves included, fails typed with a `SchemaIssue.InvalidValue`
+	* issue before the schema decode runs, so hostile depth is never a defect.
+	* Because leaves count, a document the parser accepts can still be
+	* refused here: `"> ".repeat(255) + "x"` parses, but its `text` leaf sits
+	* at depth 257, and `Markdown.stringify` refuses that tree too.
+	*
 	* @param input - A plain mdast tree, typically a `root`.
 	* @returns A `Result` succeeding with the decoded {@link Root}, or
 	*   failing with {@link MdastDecodeError} carrying the structured issue.
 	*/
 	static fromMdastResult(input) {
-		return Result.mapError(decodeRoot(normalizeNode(input)), (error) => new MdastDecodeError({ issue: error.issue }));
+		let normalized;
+		try {
+			normalized = normalizeNode(input);
+		} catch (error) {
+			if (!isGuardExceeded(error)) throw error;
+			return Result.fail(new MdastDecodeError({ issue: new SchemaIssue.InvalidValue({ message: error.message }) }));
+		}
+		return Result.mapError(decodeRoot(normalized), (error) => new MdastDecodeError({ issue: error.issue }));
 	}
 	/**
 	* Decode foreign plain mdast into the package's node classes. Defined in

package/README.md

@@ -85,7 +85,7 @@ Every parse has a synchronous twin — `MarkdownDocument.parseResult` and `Markd
 
 ```ts
 import { MarkdownDocument, MarkdownFormat } from "@effected/markdown";
-import { Effect } from "effect";
+import { Effect, Option } from "effect";
 
 const source = `# Release notes
 
@@ -94,7 +94,7 @@ See the [changelog](./CHANGELOG.md).
 
 const program = Effect.gen(function* () {
   const doc = yield* MarkdownDocument.parse(source);
-  const label = doc.find("text")!;
+  const label = Option.getOrThrow(doc.find("text"));
   return yield* MarkdownFormat.modifyToString(doc, label, "Release notes (2026)");
 });
 
@@ -104,7 +104,7 @@ Effect.runPromise(program).then(console.log);
 // See the [changelog](./CHANGELOG.md).
 ```
 
-`find` walks the tree in document pre-order and returns the document's own node, so the match feeds `modify` by identity. Replacements are literal strings or node fragments, and both render through the canonical stringifier, so a modified document re-parses cleanly by construction — you cannot splice in raw markdown that reopens a fence or breaks a table.
+`find` walks the tree in document pre-order and returns the document's own node inside an `Option` — `Option.none()` when nothing matches — so the match feeds `modify` by identity. Replacements are literal strings or node fragments, and both render through the canonical stringifier, so a modified document re-parses cleanly by construction — you cannot splice in raw markdown that reopens a fence or breaks a table.
 
 `MarkdownFormat.format` handles the other half: conservative marker normalization, never content rewriting. It converts heading style, bullet character, emphasis marker, fence character, thematic-break character and code-block style, and skips any conversion that would not be safe rather than attempting it cleverly:
 
@@ -198,11 +198,11 @@ Effect.runPromise(program).then(console.log);
 // [ "./CHANGELOG.md", "https://example.com/docs" ]
 ```
 
-`headings` lists every heading wherever it sits, including inside blockquotes and list items. `sections` are delimited by root-level headings only, and each section's range spans its subsections, so the edit layer can splice a whole section out in one edit. `firstSection` and `sectionByHeading` find one `DocumentSection` without scanning `sections` yourself — the second matches on an exact trimmed heading string, a `RegExp`, or a predicate, and both accept `{ depth }` to restrict to one heading level:
+`headings` lists every heading wherever it sits, including inside blockquotes and list items. `sections` are delimited by root-level headings only, and each section's range spans its subsections, so the edit layer can splice a whole section out in one edit. `firstSection` and `sectionByHeading` find one `DocumentSection` without scanning `sections` yourself — the second matches on an exact trimmed heading string, a `RegExp`, or a predicate, and both accept `{ depth }` to restrict to one heading level. Both return an `Option`, as every lookup in the kit does (the `frontmatter` accessor and `find` too):
 
 ```ts
 import { MarkdownDocument } from "@effected/markdown";
-import { Effect } from "effect";
+import { Effect, Option } from "effect";
 
 const source = `# Changelog
 
@@ -217,7 +217,10 @@ Initial release.
 
 const program = Effect.gen(function* () {
   const doc = yield* MarkdownDocument.parse(source);
-  return doc.sectionByHeading("1.2.3", { depth: 2 })?.body.trim();
+  return Option.match(doc.sectionByHeading("1.2.3", { depth: 2 }), {
+    onNone: () => "no such release",
+    onSome: (section) => section.body.trim(),
+  });
 });
 
 Effect.runPromise(program).then(console.log);
@@ -226,7 +229,7 @@ Effect.runPromise(program).then(console.log);
 
 `DocumentSection.body` is the section without its heading, and it is deliberately untrimmed — exactly the bytes `bodyRange` describes — so callers write `.body.trim()` when they want the tidy form.
 
-For anything the accessors do not cover, `find` and `findAll` walk the whole tree in document pre-order. A string selector matches the node's `type` and narrows the result — `doc.findAll("heading")` is `ReadonlyArray<Heading>`, `doc.find("table")` is `Table | undefined` — and a type-guard predicate narrows the same way. The nodes come back by identity, so `doc.findAll("heading")[1]` addresses the second heading for `MarkdownFormat.modify` without raw child indexing.
+For anything the accessors do not cover, `find` and `findAll` walk the whole tree in document pre-order. A string selector matches the node's `type` and narrows the result — `doc.findAll("heading")` is `ReadonlyArray<Heading>`, `doc.find("table")` is `Option<Table>` — and a type-guard predicate narrows the same way. The nodes come back by identity, so `doc.findAll("heading")[1]` addresses the second heading for `MarkdownFormat.modify` without raw child indexing.
 
 `MarkdownVisitor.visit` streams the same walk as `Enter`/`Exit` events carrying the node, its child-index path and its depth:
 
@@ -246,6 +249,21 @@ Effect.runPromise(program).then(console.log);
 //   "Exit:text", "Exit:emphasis", "Enter:text", "Exit:text", "Exit:paragraph", "Exit:root" ]
 ```
 
+`MarkdownVisitor.walk` is the same walk as a synchronous, lazy `Iterable` — the primitive `visit` is defined in terms of — for code that cannot suspend, such as a lint rule a host calls synchronously. Each iteration walks afresh from the root, and a `for…of` that `break`s stops the walk:
+
+```ts
+import { Markdown, MarkdownVisitor } from "@effected/markdown";
+import { Result } from "effect";
+
+const root = Result.getOrThrow(Markdown.parseResult("# Title\n\nA *b* c\n"));
+const headings: Array<number> = [];
+for (const event of MarkdownVisitor.walk(root)) {
+  if (event._tag === "Enter" && event.node.type === "heading") headings.push(event.node.depth);
+}
+console.log(headings);
+// [ 1 ]
+```
+
 ## mdast interop
 
 The node classes already use mdast's type names and field shapes; `Mdast.toMdast` strips the fidelity fields this package adds — bullet characters, fence style, ATX-versus-setext spelling — (keeping only a `Text` node's `escapeStyle` when set, see [Literal text](#literal-text)) and emits plain spec-valid mdast JSON that the remark ecosystem consumes directly, including `mdast-util-to-hast` if you want hast:
@@ -364,7 +382,7 @@ To *normalize* an existing document to different choices, use `MarkdownFormat` w
 - `FrontmatterSource` — string-level frontmatter `split`/`join` over the same closed fence grammar, byte-exact boundaries, no parsing of value or body; for bodies the CommonMark engine should not touch.
 - `MarkdownEdit` / `MarkdownRange` (with `applyAll`) — the non-mutating text-edit vocabulary, field-identical to `@effected/jsonc`'s, `@effected/yaml`'s and `@effected/toml`'s.
 - `MarkdownFormat` — `format`/`formatToString` compute conservative marker-normalization edits; `modify`/`modifyToString` replace a node by identity through the canonical stringifier.
-- `MarkdownVisitor` — walk a parsed tree as a lazy `Stream` of `Enter`/`Exit` events with child-index paths and depth.
+- `MarkdownVisitor` — walk a parsed tree as `Enter`/`Exit` events with child-index paths and depth: synchronously as a lazy `Iterable` (`walk`), or as a `Stream` (`visit`).
 - `Mdast` — `toMdast` projects to plain mdast JSON; `fromMdast`/`fromMdastResult` admit a foreign mdast tree with validation.
 - `MarkdownFrontmatter.schema` plus the `YamlFrontmatter`, `TomlFrontmatter` and `JsonFrontmatter` codecs — typed frontmatter decoding over optional per-format peers, with four separately catchable failure modes and a `FrontmatterMissingReason` on the absent one.
 - `SchemaResolver` — classify a frontmatter `$schema` declaration into `ByUrl`/`ByPath`/`Inline`/`ByName` and resolve names against a registry, with no IO and no dependencies.

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Data, Effect, Result, Schema, Stream } from "effect";
+import { Data, Effect, Option, Result, Schema, Stream } from "effect";
 declare const Point_base: Schema.Class<Point, Schema.Struct<{
   readonly line: Schema.Number;
   readonly column: Schema.Number;
@@ -1589,27 +1589,34 @@ declare const MarkdownDocument_base: Schema.Class<MarkdownDocument, Schema.Struc
  */
 export declare class MarkdownDocument extends MarkdownDocument_base {
   /**
-   * The document's frontmatter capture, or `undefined` when there is none.
+   * The document's frontmatter capture, or `Option.none()` when there is
+   * none.
    *
    * @remarks
    * Derived from the tree rather than stored: a {@link Frontmatter} node can
    * only ever sit at the head of `root.children` (the capture fires at most
    * once, at offset 0), so the tree is the single source of truth and the
-   * accessor can never disagree with it. `undefined` covers both a document
-   * with no frontmatter block and one parsed with the capture toggle off —
-   * {@link MarkdownDocument.hasFrontmatterBlock} tells the two apart.
+   * accessor can never disagree with it. `Option.none()` covers both a
+   * document with no frontmatter block and one parsed with the capture toggle
+   * off — {@link MarkdownDocument.hasFrontmatterBlock} tells the two apart.
+   *
+   * An `Option` rather than `Frontmatter | undefined` because this is a
+   * lookup that can miss, and the kit's lookups return `Option` — the same
+   * shape as the sibling format packages' tree lookups (`JsoncNode.find`,
+   * `YamlNode.find`). A derived getter is a lookup, not a data field: it
+   * recomputes from the tree on every access.
    */
-  get frontmatter(): Frontmatter | undefined;
+  get frontmatter(): Option.Option<Frontmatter>;
   /**
    * Whether the source opens with a well-formed frontmatter block —
    * regardless of how the document was parsed.
    *
    * @remarks
    * The structural signal that disambiguates the `frontmatter` accessor's
-   * `undefined`: capture is opt-in (`MarkdownParseOptions.frontmatter`
+   * `Option.none()`: capture is opt-in (`MarkdownParseOptions.frontmatter`
    * defaults off), so a document whose source visibly starts with `---` can
    * still carry no capture node — spec-correct CommonMark reads the fences as
-   * a thematic break plus content. `frontmatter === undefined` with
+   * a thematic break plus content. An empty `frontmatter` with
    * `hasFrontmatterBlock === true` means exactly "parsed with capture off";
    * with `false` it means the source genuinely has no block.
    *
@@ -1656,9 +1663,10 @@ export declare class MarkdownDocument extends MarkdownDocument_base {
    * document repeatedly should bind `document.sections` once instead.
    *
    * @param options - Depth restriction.
-   * @returns The first matching section, or `undefined`.
+   * @returns The first matching section, or `Option.none()` when no section
+   *   matches.
    */
-  firstSection(options?: SectionQueryOptions): DocumentSection | undefined;
+  firstSection(options?: SectionQueryOptions): Option.Option<DocumentSection>;
   /**
    * The first section whose heading matches, in document order.
    *
@@ -1674,9 +1682,10 @@ export declare class MarkdownDocument extends MarkdownDocument_base {
    *
    * @param match - A string, a RegExp, or a predicate.
    * @param options - Depth restriction, applied before matching.
-   * @returns The first matching section, or `undefined`.
+   * @returns The first matching section, or `Option.none()` when no section
+   *   matches.
    */
-  sectionByHeading(match: SectionHeadingMatch, options?: SectionQueryOptions): DocumentSection | undefined;
+  sectionByHeading(match: SectionHeadingMatch, options?: SectionQueryOptions): Option.Option<DocumentSection>;
   /**
    * Every link-bearing node in the document, in document order: links,
    * images, definitions, and the reference forms resolved through the
@@ -1697,7 +1706,7 @@ export declare class MarkdownDocument extends MarkdownDocument_base {
    *
    * @remarks
    * A string selector matches on the node's `type` tag and narrows the
-   * result (`find("heading")` is `Heading | undefined`); a type-guard
+   * result (`find("heading")` is `Option<Heading>`); a type-guard
    * predicate narrows the same way, and a plain predicate returns the wide
    * `MarkdownNode` union. The returned node is the document's own — matched
    * and returnable by identity, so it feeds `MarkdownFormat.modify`
@@ -1706,11 +1715,12 @@ export declare class MarkdownDocument extends MarkdownDocument_base {
    * hand-built or foreign decoded tree) is a thrown defect.
    *
    * @param selector - A node `type` tag or a predicate over nodes.
-   * @returns The first matching node in document order, or `undefined`.
+   * @returns The first matching node in document order, or `Option.none()`
+   *   when none matches.
    */
-  find<T extends MarkdownNodeType>(selector: T): MarkdownNodeOfType<T> | undefined;
-  find<T extends MarkdownNode>(selector: (node: MarkdownNode) => node is T): T | undefined;
-  find(selector: (node: MarkdownNode) => boolean): MarkdownNode | undefined;
+  find<T extends MarkdownNodeType>(selector: T): Option.Option<MarkdownNodeOfType<T>>;
+  find<T extends MarkdownNode>(selector: (node: MarkdownNode) => node is T): Option.Option<T>;
+  find(selector: (node: MarkdownNode) => boolean): Option.Option<MarkdownNode>;
   /**
    * Find every node matching a selector, in document pre-order — the same
    * order {@link MarkdownVisitor} enters nodes, starting at the root itself.
@@ -2241,19 +2251,34 @@ export declare class SchemaResolver {
    * data.
    *
    * @remarks
-   * Non-mapping data and a mapping without a `$schema` key both carry no
-   * declaration: the result succeeds with `undefined` by default, or fails
-   * with {@link SchemaDeclarationMissingError} under `requireDeclaration`.
+   * A lookup that can miss, so by default the success channel is an
+   * `Option`: non-mapping data and a mapping without a `$schema` key both
+   * carry no declaration and succeed with `Option.none()`, and the error
+   * union is {@link SchemaDeclarationInvalidError} alone. Under
+   * `requireDeclaration: true` the miss becomes a typed
+   * {@link SchemaDeclarationMissingError} and the success is the bare
+   * declaration, since it is statically always present. The two overloads
+   * keep each caller's types honest: no `Option` to unwrap when the
+   * declaration is required, no `SchemaDeclarationMissingError` to handle
+   * when it is not. A present key is classified by
+   * {@link SchemaResolver.classify}, and its
+   * {@link SchemaDeclarationInvalidError} propagates unchanged. Hand an
+   * optional declaration to a {@link FrontmatterSchemaResolver} with
+   * `Option.getOrUndefined`, since the seam takes the absent case as
+   * `undefined`; a required one passes straight through.
    *
    * @param data - The decoded frontmatter data.
-   * @param options - `requireDeclaration` makes a missing `$schema` a typed
-   *   error.
-   * @returns The classified declaration, `undefined` when absent and
-   *   tolerated, or the typed error.
+   * @param options - `requireDeclaration: true` makes a missing `$schema` a
+   *   typed error and narrows the success to the declaration itself.
+   * @returns The classified declaration under `requireDeclaration`;
+   *   otherwise `Option.some` of it, or `Option.none()` when absent.
    */
+  static declarationOf(data: unknown, options: {
+    readonly requireDeclaration: true;
+  }): Result.Result<SchemaDeclaration, SchemaDeclarationInvalidError | SchemaDeclarationMissingError>;
   static declarationOf(data: unknown, options?: {
-    readonly requireDeclaration?: boolean;
-  }): Result.Result<SchemaDeclaration | undefined, SchemaDeclarationInvalidError | SchemaDeclarationMissingError>;
+    readonly requireDeclaration?: false;
+  }): Result.Result<Option.Option<SchemaDeclaration>, SchemaDeclarationInvalidError>;
   /**
    * The package's one built-in resolver: a name-keyed registry with
    * exact version-segment resolution.
@@ -2902,7 +2927,7 @@ export declare class MarkdownTransform {
  * leaf the two fire back to back. Every variant carries `path` (child
  * indexes from the root; the root's own path is empty) and `depth`
  * (zero-based; the root is 0). `Error` is terminal: it carries the
- * depth-guard diagnostic for a decoded foreign tree nested past
+ * depth-guard diagnostic for a hand-constructed tree nested past
  * `MAX_NESTING_DEPTH` and nothing follows it.
  *
  * @public
@@ -3046,8 +3071,9 @@ export declare const MarkdownVisitorEvent: {
   }, "_tag">;
 };
 /**
- * Walks a parsed markdown tree as a lazy `Stream` of `Enter`/`Exit` events in
- * document pre-order. Not instantiable.
+ * Walks a parsed markdown tree as a lazy sequence of `Enter`/`Exit` events in
+ * document pre-order — synchronously with {@link MarkdownVisitor.walk}, or as
+ * a `Stream` with {@link MarkdownVisitor.visit}. Not instantiable.
  *
  * @example
  * ```ts
@@ -3069,6 +3095,45 @@ export declare const MarkdownVisitorEvent: {
  */
 export declare class MarkdownVisitor {
   private constructor();
+  /**
+   * Walk `root` synchronously, as a lazy `Iterable` of `MarkdownVisitorEvent`
+   * in document pre-order: `Enter` and `Exit` for every node including the
+   * root and every leaf. The primitive {@link MarkdownVisitor.visit} is
+   * defined in terms of, so the two yield the same events in the same order.
+   *
+   * @remarks
+   * For callers that cannot suspend — a lint rule whose host calls it
+   * synchronously, a getter, a non-Effect adapter. Events are produced on
+   * demand: a `for…of` that `break`s stops the walk without visiting the
+   * rest of the tree. The iterable is re-iterable — every `[Symbol.iterator]()`
+   * call starts a fresh walk from the root, so binding the result once and
+   * iterating it twice walks the tree twice, independently.
+   *
+   * Not named `walkResult`: it returns no `Result`, and the walk has no
+   * failure channel to put in one. A hand-constructed tree nested past the
+   * depth cap surfaces as a terminal `MarkdownVisitorEvent` `Error` event
+   * carrying a `NestingDepthExceeded` {@link MarkdownDiagnostic}, after which
+   * nothing is yielded — the same posture as `visit`. A tree produced by
+   * `Markdown.parse` or decoded by `Mdast.fromMdast` can never trip it.
+   *
+   * @example
+   * ```ts
+   * import { Markdown, MarkdownVisitor } from "@effected/markdown";
+   * import { Result } from "effect";
+   *
+   * const root = Result.getOrThrow(Markdown.parseResult("# Hi\n\ntext\n"));
+   * const entered: Array<string> = [];
+   * for (const event of MarkdownVisitor.walk(root)) {
+   *   if (event._tag === "Enter") entered.push(event.node.type);
+   * }
+   * console.log(entered);
+   * // => ["root", "heading", "text", "paragraph", "text"]
+   * ```
+   *
+   * @param root - The tree to walk.
+   * @returns A lazy, re-iterable `Iterable` of `MarkdownVisitorEvent`.
+   */
+  static walk(root: Root): Iterable<MarkdownVisitorEvent>;
   /**
    * Create a lazy `Stream` of `MarkdownVisitorEvent` walking `root` in
    * document pre-order: `Enter` and `Exit` for every node including the
@@ -3079,10 +3144,15 @@ export declare class MarkdownVisitor {
    * @remarks
    * Infallible at the type level. A tree produced by `Markdown.parse` can
    * never trip the walk's depth guard — the parser refuses deeper input —
-   * but a decoded foreign tree (`Mdast.fromMdast`) can; the trip surfaces
-   * as a terminal `MarkdownVisitorEvent` `Error` event carrying a
-   * `NestingDepthExceeded` {@link MarkdownDiagnostic}, mirroring the typed
-   * failure `Markdown.stringify` produces for the same tree.
+   * and neither can a decoded foreign tree (`Mdast.fromMdast`), because the
+   * decode boundary refuses it first; only a hand-constructed tree can trip
+   * the guard. The trip surfaces as a terminal `MarkdownVisitorEvent`
+   * `Error` event carrying a `NestingDepthExceeded` {@link MarkdownDiagnostic},
+   * mirroring the typed failure `Markdown.stringify` produces for the same
+   * tree.
+   *
+   * Defined as `Stream.fromIterable(MarkdownVisitor.walk(root))`: every run
+   * of the stream walks afresh, and the two forms never diverge.
    *
    * @param root - The tree to walk.
    * @returns A lazy `Stream` of `MarkdownVisitorEvent`, infallible at the type
@@ -3221,6 +3291,14 @@ export declare class Mdast {
    * plain tree built for `Markdown.stringify` can carry it straight in. A
    * value outside `"canonical" | "literal"` fails the decode typed.
    *
+   * **Nesting is capped at 256 levels below the root**, the same cap the
+   * parser and `Markdown.stringify` enforce. A tree with any node deeper
+   * than that, leaves included, fails typed with a `SchemaIssue.InvalidValue`
+   * issue before the schema decode runs, so hostile depth is never a defect.
+   * Because leaves count, a document the parser accepts can still be
+   * refused here: `"> ".repeat(255) + "x"` parses, but its `text` leaf sits
+   * at depth 257, and `Markdown.stringify` refuses that tree too.
+   *
    * @param input - A plain mdast tree, typically a `root`.
    * @returns A `Result` succeeding with the decoded {@link Root}, or
    *   failing with {@link MdastDecodeError} carrying the structured issue.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/markdown",
-	"version": "0.20.0",
+	"version": "0.22.0",
 	"private": false,
 	"description": "CommonMark and GFM markdown parse, edit and transform schemas for Effect",
 	"keywords": [
@@ -39,9 +39,9 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/jsonc": "^0.19.0",
-		"@effected/toml": "^0.15.0",
-		"@effected/yaml": "^0.23.0",
+		"@effected/jsonc": "^0.20.0",
+		"@effected/toml": "^0.16.0",
+		"@effected/yaml": "^0.25.0",
 		"effect": "^4.0.0"
 	},
 	"peerDependenciesMeta": {