@effected/markdown 0.2.5 → 0.3.0

package/MarkdownDocument.js

@@ -6,6 +6,80 @@ import { parsePassResult } from "./Markdown.js";
 import { Effect, Result, Schema } from "effect";
 
 //#region src/MarkdownDocument.ts
+/**
+* A heading-delimited span from {@link MarkdownDocument.sections}: the
+* heading, its depth, the source `range` the section occupies and the
+* root-level blocks that follow the heading inside it.
+*
+* @remarks
+* A section runs from its heading's start offset to the start of the next
+* root-level heading of equal or shallower depth, or to the end of the
+* source. Deeper headings nest inside, so a parent section's `range` and
+* `children` include its subsections — the list is flat, in document order,
+* with `depth` carrying the hierarchy.
+*
+* Instances come from {@link MarkdownDocument.sections} and the two finders;
+* there is no reason to construct one directly.
+*
+* @public
+*/
+var DocumentSection = class {
+	/** The heading that opens the section. */
+	heading;
+	/** The heading's depth, and the section's. */
+	depth;
+	/** The whole section including its heading — spliceable by `MarkdownEdit`. */
+	range;
+	/** The root-level blocks after the heading, subsections included. */
+	children;
+	/**
+	* The heading's plain-text content.
+	*
+	* @remarks
+	* The same derivation as {@link DocumentHeading.text}: text and inline-code
+	* values concatenated, image `alt` where present, a hard break as one space,
+	* nothing for raw HTML or footnote references. So `## **1.2.3**` reads
+	* `1.2.3`.
+	*/
+	text;
+	/**
+	* The section WITHOUT its heading: from the heading's end offset to the
+	* section's end.
+	*
+	* @remarks
+	* This is the span a "give me the release notes under this version" reader
+	* wants, and the one that is fiddly to derive by hand.
+	*/
+	bodyRange;
+	/** The document source these ranges index into. */
+	#documentSource;
+	constructor(options) {
+		this.heading = options.heading;
+		this.depth = options.depth;
+		this.range = options.range;
+		this.children = options.children;
+		this.text = options.text;
+		this.bodyRange = options.bodyRange;
+		this.#documentSource = options.documentSource;
+	}
+	/** The section's source text, heading included. */
+	get source() {
+		return this.#documentSource.slice(this.range.offset, this.range.offset + this.range.length);
+	}
+	/**
+	* The section's source text without its heading.
+	*
+	* @remarks
+	* **Untrimmed, deliberately.** It is exactly the bytes {@link
+	* DocumentSection.bodyRange} describes, so the string and the offsets can
+	* never disagree — a package that publishes a span's offsets and then hands
+	* back a different span is lying about it. Callers that want the tidy form
+	* write `.body.trim()`, visibly.
+	*/
+	get body() {
+		return this.#documentSource.slice(this.bodyRange.offset, this.bodyRange.offset + this.bodyRange.length);
+	}
+};
 const walkTree = (node, depth, visit) => {
 	if (depth > 256) throw new Error(`NestingDepthExceeded: limit ${256} exceeded while walking the document tree`);
 	visit(node);
@@ -145,19 +219,68 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 				}
 			}
 			const start = block.position.start.offset;
-			sections.push({
+			const bodyStart = block.position.end.offset;
+			sections.push(new DocumentSection({
 				heading: block,
 				depth: block.depth,
 				range: MarkdownRange.make({
 					offset: start,
 					length: boundary - start
 				}),
-				children: blocks.slice(index + 1, end).filter((child) => child.type !== "frontmatter")
-			});
+				children: blocks.slice(index + 1, end).filter((child) => child.type !== "frontmatter"),
+				text: phrasingText(block.children),
+				bodyRange: MarkdownRange.make({
+					offset: bodyStart,
+					length: Math.max(0, boundary - bodyStart)
+				}),
+				documentSource: this.source
+			}));
 		}
 		return sections;
 	}
 	/**
+	* The first section in document order, optionally restricted by heading
+	* depth.
+	*
+	* @remarks
+	* `firstSection({ depth: 2 })` is "the newest entry" for a changelog whose
+	* releases are H2s under an H1 title. Like the other navigation accessors
+	* this recomputes {@link MarkdownDocument.sections}; a caller scanning one
+	* document repeatedly should bind `document.sections` once instead.
+	*
+	* @param options - Depth restriction.
+	* @returns The first matching section, or `undefined`.
+	*/
+	firstSection(options) {
+		const depth = options?.depth;
+		return this.sections.find((section) => depth === void 0 || section.depth === depth);
+	}
+	/**
+	* The first section whose heading matches, in document order.
+	*
+	* @remarks
+	* A **string matches the trimmed heading text exactly** — never a substring.
+	* That is a deliberate refusal of the obvious convenience: `"1.2.3"` would
+	* otherwise match a `## 1.2.30` heading, and in a changelog (where `1.2.30`
+	* sorts newer and therefore sits *earlier*) that silently publishes the
+	* wrong release. A `RegExp` is tested against the same trimmed text, and its
+	* `lastIndex` is reset first so a `/g/` pattern cannot skip sections. A
+	* predicate receives the raw {@link DocumentSection.text} plus the section
+	* itself and decides freely.
+	*
+	* @param match - A string, a RegExp, or a predicate.
+	* @param options - Depth restriction, applied before matching.
+	* @returns The first matching section, or `undefined`.
+	*/
+	sectionByHeading(match, options) {
+		const depth = options?.depth;
+		const matches = typeof match === "string" ? (section) => section.text.trim() === match : match instanceof RegExp ? (section) => {
+			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));
+	}
+	/**
 	* Every link-bearing node in the document, in document order: links,
 	* images, definitions, and the reference forms resolved through the
 	* definition index.
@@ -245,4 +368,4 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 };
 
 //#endregion
-export { MarkdownDocument };
+export { DocumentSection, MarkdownDocument };

package/index.d.ts

@@ -1049,14 +1049,88 @@ interface DocumentHeading {
  * `children` include its subsections — the list is flat, in document order,
  * with `depth` carrying the hierarchy.
  *
+ * Instances come from {@link MarkdownDocument.sections} and the two finders;
+ * there is no reason to construct one directly.
+ *
  * @public
  */
-interface DocumentSection {
+declare class DocumentSection {
+  #private;
+  /** The heading that opens the section. */
   readonly heading: Heading;
+  /** The heading's depth, and the section's. */
   readonly depth: HeadingDepth;
+  /** The whole section including its heading — spliceable by `MarkdownEdit`. */
   readonly range: MarkdownRange;
+  /** The root-level blocks after the heading, subsections included. */
   readonly children: ReadonlyArray<FlowContent>;
+  /**
+   * The heading's plain-text content.
+   *
+   * @remarks
+   * The same derivation as {@link DocumentHeading.text}: text and inline-code
+   * values concatenated, image `alt` where present, a hard break as one space,
+   * nothing for raw HTML or footnote references. So `## **1.2.3**` reads
+   * `1.2.3`.
+   */
+  readonly text: string;
+  /**
+   * The section WITHOUT its heading: from the heading's end offset to the
+   * section's end.
+   *
+   * @remarks
+   * This is the span a "give me the release notes under this version" reader
+   * wants, and the one that is fiddly to derive by hand.
+   */
+  readonly bodyRange: MarkdownRange;
+  constructor(options: {
+    readonly heading: Heading;
+    readonly depth: HeadingDepth;
+    readonly range: MarkdownRange;
+    readonly children: ReadonlyArray<FlowContent>;
+    readonly text: string;
+    readonly bodyRange: MarkdownRange;
+    readonly documentSource: string;
+  });
+  /** The section's source text, heading included. */
+  get source(): string;
+  /**
+   * The section's source text without its heading.
+   *
+   * @remarks
+   * **Untrimmed, deliberately.** It is exactly the bytes {@link
+   * DocumentSection.bodyRange} describes, so the string and the offsets can
+   * never disagree — a package that publishes a span's offsets and then hands
+   * back a different span is lying about it. Callers that want the tidy form
+   * write `.body.trim()`, visibly.
+   */
+  get body(): string;
 }
+/**
+ * Narrowing options for {@link MarkdownDocument.firstSection} and
+ * {@link MarkdownDocument.sectionByHeading}.
+ *
+ * @public
+ */
+interface SectionQueryOptions {
+  /**
+   * Restrict to sections opened by a heading of exactly this depth.
+   *
+   * @remarks
+   * Equality, not a maximum: `{ depth: 2 }` is "the H2 sections", which is the
+   * changelog idiom. A depth *range* is a different question and belongs in a
+   * predicate.
+   */
+  readonly depth?: HeadingDepth;
+}
+/**
+ * How {@link MarkdownDocument.sectionByHeading} decides a section matches: an
+ * exact trimmed-text string, a `RegExp`, or a predicate over the text and the
+ * section.
+ *
+ * @public
+ */
+type SectionHeadingMatch = string | RegExp | ((text: string, section: DocumentSection) => boolean);
 /**
  * The node types {@link MarkdownDocument.links} collects: the nodes that
  * carry an outbound URL themselves ({@link Link}, {@link Image},
@@ -1154,6 +1228,38 @@ declare class MarkdownDocument extends MarkdownDocument_base {
    * boundary heading's start, or to the end of the source.
    */
   get sections(): ReadonlyArray<DocumentSection>;
+  /**
+   * The first section in document order, optionally restricted by heading
+   * depth.
+   *
+   * @remarks
+   * `firstSection({ depth: 2 })` is "the newest entry" for a changelog whose
+   * releases are H2s under an H1 title. Like the other navigation accessors
+   * this recomputes {@link MarkdownDocument.sections}; a caller scanning one
+   * document repeatedly should bind `document.sections` once instead.
+   *
+   * @param options - Depth restriction.
+   * @returns The first matching section, or `undefined`.
+   */
+  firstSection(options?: SectionQueryOptions): DocumentSection | undefined;
+  /**
+   * The first section whose heading matches, in document order.
+   *
+   * @remarks
+   * A **string matches the trimmed heading text exactly** — never a substring.
+   * That is a deliberate refusal of the obvious convenience: `"1.2.3"` would
+   * otherwise match a `## 1.2.30` heading, and in a changelog (where `1.2.30`
+   * sorts newer and therefore sits *earlier*) that silently publishes the
+   * wrong release. A `RegExp` is tested against the same trimmed text, and its
+   * `lastIndex` is reset first so a `/g/` pattern cannot skip sections. A
+   * predicate receives the raw {@link DocumentSection.text} plus the section
+   * itself and decides freely.
+   *
+   * @param match - A string, a RegExp, or a predicate.
+   * @param options - Depth restriction, applied before matching.
+   * @returns The first matching section, or `undefined`.
+   */
+  sectionByHeading(match: SectionHeadingMatch, options?: SectionQueryOptions): DocumentSection | undefined;
   /**
    * Every link-bearing node in the document, in document order: links,
    * images, definitions, and the reference forms resolved through the
@@ -2186,5 +2292,5 @@ declare const TomlFrontmatter: FrontmatterCodec;
  */
 declare const YamlFrontmatter: FrontmatterCodec;
 //#endregion
-export { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, type DocumentHeading, type DocumentLink, type DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, type FrontmatterCodec, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, type FrontmatterResolveError, type FrontmatterSchemaError, type FrontmatterSchemaResolver, FrontmatterValidationError, type FrontmatterWriteError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, type LinkBearingNode, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, type MarkdownNodeOfType, type MarkdownNodeType, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, type MarkdownPath, MarkdownRange, type MarkdownRangeLike, type MarkdownSegment, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, type MdastNode, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
+export { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, type DocumentHeading, type DocumentLink, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, type FrontmatterCodec, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, type FrontmatterResolveError, type FrontmatterSchemaError, type FrontmatterSchemaResolver, FrontmatterValidationError, type FrontmatterWriteError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, type LinkBearingNode, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, type MarkdownNodeOfType, type MarkdownNodeType, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, type MarkdownPath, MarkdownRange, type MarkdownRangeLike, type MarkdownSegment, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, type MdastNode, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, type SectionHeadingMatch, type SectionQueryOptions, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -5,11 +5,11 @@ import { SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, Sc
 import { JsonFrontmatter } from "./JsonFrontmatter.js";
 import { MarkdownDiagnostic, MarkdownParseErrorCode } from "./MarkdownDiagnostic.js";
 import { Markdown, MarkdownDialect, MarkdownParseError, MarkdownParseOptions, MarkdownStringifyError } from "./Markdown.js";
-import { MarkdownDocument } from "./MarkdownDocument.js";
+import { DocumentSection, MarkdownDocument } from "./MarkdownDocument.js";
 import { MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode } from "./MarkdownFormat.js";
 import { MarkdownVisitor, MarkdownVisitorEvent } from "./MarkdownVisitor.js";
 import { Mdast, MdastDecodeError } from "./Mdast.js";
 import { TomlFrontmatter } from "./TomlFrontmatter.js";
 import { YamlFrontmatter } from "./YamlFrontmatter.js";
 
-export { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterValidationError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, MarkdownRange, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
+export { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterValidationError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, MarkdownRange, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/markdown",
-	"version": "0.2.5",
+	"version": "0.3.0",
 	"private": false,
 	"description": "CommonMark and GFM markdown parse, edit and transform schemas for Effect",
 	"keywords": [