@effected/markdown 0.21.0 → 0.23.0

package/FrontmatterResolver.js

@@ -1,4 +1,4 @@
-import { Effect, Predicate, Result, Schema } from "effect";
+import { Effect, Option, Predicate, Result, Schema } from "effect";
 
 // src/FrontmatterResolver.ts
 /**
@@ -189,24 +189,11 @@ var SchemaResolver = class SchemaResolver {
 			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 (!Predicate.isObject(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/Markdown.js

@@ -3,7 +3,9 @@ import { isGuardExceeded, isRawMarkdownError } from "./internal/carriers.js";
 import { parseBlocks } from "./internal/blockParser.js";
 import { parsePhrasingText } from "./internal/phrasing.js";
 import { stringifyBlocks } from "./internal/stringify.js";
+import { assertWithinNestingDepth } from "./internal/treeDepth.js";
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
+import { MarkdownTransform } from "./MarkdownTransform.js";
 import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
 // src/Markdown.ts
@@ -282,8 +284,8 @@ var Markdown = class Markdown {
 	* surgical editing goes through the offset-splice edit layer instead.
 	*
 	* **The canonical form is a stability commitment, so a test may assert
-	* against these bytes.** There are no options to configure and therefore
-	* nothing to drift, the choices below are pinned by byte-level tests, and
+	* against these bytes.** The one option, `canonical`, only selects
+	* between these bytes and the author's spelling; the choices below are pinned by byte-level tests, and
 	* the engine is cross-checked against commonmark.js over the full
 	* CommonMark 0.31.2 corpus. Changing any of them is a **breaking** change
 	* to this package, never a patch. A consumer asserting on rendered
@@ -352,13 +354,24 @@ var Markdown = class Markdown {
 	* trip on a tree nesting past the depth cap fails, and only synthesized
 	* or decoded trees can nest that far.
 	*
+	* **`canonical: true` ignores fidelity fields.** With
+	* {@link MarkdownStringifyOptions.canonical} set, every fidelity field is
+	* cleared first, so a parsed `* a` list, setext heading, `_em_`, `~~~` fence
+	* or `***` break all emit the canonical spelling. It is the same as
+	* serializing `MarkdownTransform.canonicalize(node)`, without the
+	* `Mdast.toMdast` / `Mdast.fromMdastResult` round trip. The default keeps
+	* honouring fidelity fields.
+	*
 	* @param node - The document tree, or a single flow node, to serialize.
+	* @param options - Optional {@link MarkdownStringifyOptions}.
 	* @returns A `Result` succeeding with markdown source, or failing with
 	*   {@link MarkdownStringifyError}.
 	*/
-	static stringifyResult(node) {
+	static stringifyResult(node, options) {
 		try {
-			return Result.succeed(stringifyBlocks(node.type === "root" ? node.children : [node]));
+			if (options?.canonical === true) assertWithinNestingDepth(node);
+			const source = options?.canonical === true ? MarkdownTransform.canonicalize(node) : node;
+			return Result.succeed(stringifyBlocks(source.type === "root" ? source.children : [source]));
 		} catch (caught) {
 			if (isGuardExceeded(caught)) return Result.fail(new MarkdownStringifyError({ diagnostic: MarkdownDiagnostic.make({
 				code: caught.reason,
@@ -394,10 +407,12 @@ var Markdown = class Markdown {
 	* see {@link Markdown.stringifyResult}.
 	*
 	* @param node - The document tree, or a single flow node, to serialize.
+	* @param options - Optional {@link MarkdownStringifyOptions}; `canonical: true`
+	*   discards fidelity fields.
 	* @returns An `Effect` that succeeds with markdown source, or fails with
 	*   {@link MarkdownStringifyError}.
 	*/
-	static stringify = Effect.fn("Markdown.stringify")((node) => Effect.fromResult(Markdown.stringifyResult(node)));
+	static stringify = Effect.fn("Markdown.stringify")((node, options) => Effect.fromResult(Markdown.stringifyResult(node, options)));
 	/**
 	* A `Schema<Root, string>` decoding markdown source into a {@link Root}
 	* tree and encoding a tree back to canonical markdown via

package/MarkdownDocument.js

@@ -4,8 +4,8 @@ import { scanFrontmatter } from "./internal/blocks/frontmatter.js";
 import { preprocessLines } from "./internal/preprocess.js";
 import { normalizeLabelText } from "./internal/references.js";
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
-import { parsePassResult } from "./Markdown.js";
 import { rootHeadingBounds } from "./internal/sectionBounds.js";
+import { parsePassResult } from "./Markdown.js";
 import { Effect, Option, Result, Schema } from "effect";
 
 // src/MarkdownDocument.ts

package/MarkdownTransform.js

@@ -1,3 +1,4 @@
+import { FIDELITY_FIELDS, clearFidelity } from "./internal/fidelity.js";
 import { rootHeadingBounds } from "./internal/sectionBounds.js";
 
 // src/MarkdownTransform.ts
@@ -76,6 +77,32 @@ var MarkdownTransform = class {
 		} });
 	}
 	/**
+	* Return a copy of the tree with every fidelity field cleared, so
+	* `Markdown.stringify` emits the canonical form instead of the author's
+	* spelling.
+	*
+	* @remarks
+	* Clears `headingStyle`, `markerChar` (emphasis, strong, thematic break),
+	* `fenceChar` and `fenceLength`, `bulletChar` and `delimiter`, and
+	* `breakStyle`. `Text`'s `escapeStyle` is an emitter instruction rather
+	* than a recorded spelling and is kept. Positions and all mdast fields are
+	* untouched. The input is never mutated; a subtree carrying no fidelity
+	* field is returned as the same instance, following
+	* {@link MarkdownTransform.(map:1)}, on which this is built. Like `map` it
+	* recurses without a depth guard, so a tree nested past the stack throws a
+	* `RangeError`; `Markdown.stringifyResult` with `canonical: true` checks
+	* depth first and fails typed at the stringifier's own limit instead.
+	*
+	* `Markdown.stringify(tree, { canonical: true })` is exactly
+	* `Markdown.stringify(MarkdownTransform.canonicalize(tree))`.
+	*
+	* @param node - The node whose fidelity fields to clear.
+	* @returns The node with fidelity fields cleared.
+	*/
+	static canonicalize(node) {
+		return mapNode(node, canonicalHandlers);
+	}
+	/**
 	* Locate the root-level sections of one heading depth by child index —
 	* no source text needed, so it works on a tree a
 	* `MarkdownTransform.map` has reshaped.
@@ -140,6 +167,7 @@ var MarkdownTransform = class {
 	}
 };
 const isHeadingDepth = (value) => Number.isInteger(value) && value >= 1 && value <= 6;
+const canonicalHandlers = Object.fromEntries(Object.keys(FIDELITY_FIELDS).map((type) => [type, clearFidelity]));
 function mapNode(node, handlers) {
 	let current = node;
 	if ("children" in node) {

package/README.md

@@ -314,7 +314,9 @@ Serialization matches `mdxJsxToMarkdown`'s defaults — `"` quotes, spaced self-
 
 ## The canonical form is stable
 
-`Markdown.stringify` takes no options. It emits one canonical form, that form is pinned by byte-level tests, the engine behind it is cross-checked against commonmark.js over the full CommonMark 0.31.2 corpus, and **changing any of it is a breaking change to this package rather than a patch**. So a test may assert on these bytes, and a pipeline that needs stable rendered markdown should serialize through here instead of a third-party stringifier whose defaults are free to move between releases.
+`Markdown.stringify` emits one canonical form, that form is pinned by byte-level tests, the engine behind it is cross-checked against commonmark.js over the full CommonMark 0.31.2 corpus, and **changing any of it is a breaking change to this package rather than a patch**. So a test may assert on these bytes, and a pipeline that needs stable rendered markdown should serialize through here instead of a third-party stringifier whose defaults are free to move between releases.
+
+By default a node's fidelity fields (`bulletChar`, `headingStyle`, `markerChar`, `fenceChar`, `delimiter`) win, so a parsed `* a` list or setext heading re-emits as written. To drop them, pass `{ canonical: true }` to `stringify` or `stringifyResult`, or call the pure `MarkdownTransform.canonicalize(tree)` to get a cleared copy of the tree (the input is never mutated). Both give identical output and replace the `Mdast.toMdast` / `Mdast.fromMdastResult` round trip.
 
 For a node carrying no fidelity field:
 

package/index.d.ts

@@ -1013,6 +1013,19 @@ export declare const MarkdownDialect: Schema.Literals<readonly ["commonmark", "g
  * @public
  */
 export type MarkdownDialect = typeof MarkdownDialect.Type;
+/**
+ * Options for `Markdown.stringify` and `Markdown.stringifyResult`.
+ *
+ * @public
+ */
+interface MarkdownStringifyOptions {
+  /**
+   * Ignore fidelity fields (marker characters, fence style, heading
+   * spelling) and emit the canonical form. Defaults to `false`, which honours
+   * them.
+   */
+  readonly canonical?: boolean;
+}
 declare const MarkdownParseOptions_base: Schema.Class<MarkdownParseOptions, Schema.Struct<{
   readonly dialect: Schema.optionalKey<Schema.Literals<readonly ["commonmark", "gfm"]>>;
   readonly frontmatter: Schema.optionalKey<Schema.Boolean>;
@@ -1225,8 +1238,8 @@ export declare class Markdown {
    * surgical editing goes through the offset-splice edit layer instead.
    *
    * **The canonical form is a stability commitment, so a test may assert
-   * against these bytes.** There are no options to configure and therefore
-   * nothing to drift, the choices below are pinned by byte-level tests, and
+   * against these bytes.** The one option, `canonical`, only selects
+   * between these bytes and the author's spelling; the choices below are pinned by byte-level tests, and
    * the engine is cross-checked against commonmark.js over the full
    * CommonMark 0.31.2 corpus. Changing any of them is a **breaking** change
    * to this package, never a patch. A consumer asserting on rendered
@@ -1295,11 +1308,20 @@ export declare class Markdown {
    * trip on a tree nesting past the depth cap fails, and only synthesized
    * or decoded trees can nest that far.
    *
+   * **`canonical: true` ignores fidelity fields.** With
+   * {@link MarkdownStringifyOptions.canonical} set, every fidelity field is
+   * cleared first, so a parsed `* a` list, setext heading, `_em_`, `~~~` fence
+   * or `***` break all emit the canonical spelling. It is the same as
+   * serializing `MarkdownTransform.canonicalize(node)`, without the
+   * `Mdast.toMdast` / `Mdast.fromMdastResult` round trip. The default keeps
+   * honouring fidelity fields.
+   *
    * @param node - The document tree, or a single flow node, to serialize.
+   * @param options - Optional {@link MarkdownStringifyOptions}.
    * @returns A `Result` succeeding with markdown source, or failing with
    *   {@link MarkdownStringifyError}.
    */
-  static stringifyResult(node: Root | FlowContent): Result.Result<string, MarkdownStringifyError>;
+  static stringifyResult(node: Root | FlowContent, options?: MarkdownStringifyOptions): Result.Result<string, MarkdownStringifyError>;
   /**
    * Serialize a {@link Root} tree, or a single {@link (FlowContent:type)} node, to
    * canonical markdown. Defined in terms of {@link Markdown.stringifyResult}
@@ -1323,10 +1345,12 @@ export declare class Markdown {
    * see {@link Markdown.stringifyResult}.
    *
    * @param node - The document tree, or a single flow node, to serialize.
+   * @param options - Optional {@link MarkdownStringifyOptions}; `canonical: true`
+   *   discards fidelity fields.
    * @returns An `Effect` that succeeds with markdown source, or fails with
    *   {@link MarkdownStringifyError}.
    */
-  static readonly stringify: (node: Root | FlowContent) => Effect.Effect<string, MarkdownStringifyError, never>;
+  static readonly stringify: (node: Root | FlowContent, options?: MarkdownStringifyOptions | undefined) => Effect.Effect<string, MarkdownStringifyError, never>;
   /**
    * A `Schema<Root, string>` decoding markdown source into a {@link Root}
    * tree and encoding a tree back to canonical markdown via
@@ -2251,19 +2275,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.
@@ -2858,6 +2897,30 @@ export declare class MarkdownTransform {
    *   a heading depth or `min > max` — a wiring error, not a data error.
    */
   static shiftHeadings<N extends MarkdownNode>(node: N, by: number, options?: ShiftHeadingsOptions): N;
+  /**
+   * Return a copy of the tree with every fidelity field cleared, so
+   * `Markdown.stringify` emits the canonical form instead of the author's
+   * spelling.
+   *
+   * @remarks
+   * Clears `headingStyle`, `markerChar` (emphasis, strong, thematic break),
+   * `fenceChar` and `fenceLength`, `bulletChar` and `delimiter`, and
+   * `breakStyle`. `Text`'s `escapeStyle` is an emitter instruction rather
+   * than a recorded spelling and is kept. Positions and all mdast fields are
+   * untouched. The input is never mutated; a subtree carrying no fidelity
+   * field is returned as the same instance, following
+   * {@link MarkdownTransform.(map:1)}, on which this is built. Like `map` it
+   * recurses without a depth guard, so a tree nested past the stack throws a
+   * `RangeError`; `Markdown.stringifyResult` with `canonical: true` checks
+   * depth first and fails typed at the stringifier's own limit instead.
+   *
+   * `Markdown.stringify(tree, { canonical: true })` is exactly
+   * `Markdown.stringify(MarkdownTransform.canonicalize(tree))`.
+   *
+   * @param node - The node whose fidelity fields to clear.
+   * @returns The node with fidelity fields cleared.
+   */
+  static canonicalize<N extends MarkdownNode>(node: N): N;
   /**
    * Locate the root-level sections of one heading depth by child index —
    * no source text needed, so it works on a tree a
@@ -3380,5 +3443,5 @@ export declare const TomlFrontmatter: FrontmatterCodec;
  * @public
  */
 export declare const YamlFrontmatter: FrontmatterCodec;
-export type { DocumentHeading, DocumentLink, FrontmatterCodec, FrontmatterResolveError, FrontmatterSchemaError, FrontmatterSchemaResolver, FrontmatterWriteError, LinkBearingNode, MarkdownNodeOfType, MarkdownNodeType, MarkdownPath, MarkdownPhrasingOnlyType, MarkdownRangeLike, MarkdownSegment, MarkdownTransformHandlers, MarkdownTransformResult, MdastNode, MdastToTextOptions, SectionHeadingMatch, SectionQueryOptions, SectionSpan, SectionSpanOptions, ShiftHeadingsOptions };
+export type { DocumentHeading, DocumentLink, FrontmatterCodec, FrontmatterResolveError, FrontmatterSchemaError, FrontmatterSchemaResolver, FrontmatterWriteError, LinkBearingNode, MarkdownNodeOfType, MarkdownNodeType, MarkdownPath, MarkdownPhrasingOnlyType, MarkdownRangeLike, MarkdownSegment, MarkdownStringifyOptions, MarkdownTransformHandlers, MarkdownTransformResult, MdastNode, MdastToTextOptions, SectionHeadingMatch, SectionQueryOptions, SectionSpan, SectionSpanOptions, ShiftHeadingsOptions };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -5,10 +5,10 @@ import { SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, Sc
 import { FrontmatterNewline, FrontmatterSource, FrontmatterSourceBlock, FrontmatterSourceSplit } from "./FrontmatterSource.js";
 import { JsonFrontmatter } from "./JsonFrontmatter.js";
 import { MarkdownDiagnostic, MarkdownParseErrorCode } from "./MarkdownDiagnostic.js";
+import { MarkdownTransform } from "./MarkdownTransform.js";
 import { Markdown, MarkdownDialect, MarkdownParseError, MarkdownParseOptions, MarkdownStringifyError } from "./Markdown.js";
 import { DocumentSection, MarkdownDocument } from "./MarkdownDocument.js";
 import { CodeBlockStyle, MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode } from "./MarkdownFormat.js";
-import { MarkdownTransform } from "./MarkdownTransform.js";
 import { MarkdownVisitor, MarkdownVisitorEvent } from "./MarkdownVisitor.js";
 import { Mdast, MdastDecodeError } from "./Mdast.js";
 import { TomlFrontmatter } from "./TomlFrontmatter.js";

package/internal/fidelity.js

@@ -0,0 +1,25 @@
+// src/internal/fidelity.ts
+/** Node type to the fidelity keys that node may carry. */
+const FIDELITY_FIELDS = {
+	heading: ["headingStyle"],
+	emphasis: ["markerChar"],
+	strong: ["markerChar"],
+	thematicBreak: ["markerChar"],
+	code: ["fenceChar", "fenceLength"],
+	list: ["bulletChar", "delimiter"],
+	break: ["breakStyle"]
+};
+/**
+* Return `node` without its fidelity keys; the same instance when it carries
+* none, so structural sharing holds.
+*/
+const clearFidelity = (node) => {
+	const keys = FIDELITY_FIELDS[node.type];
+	if (keys === void 0 || !keys.some((key) => key in node)) return node;
+	const rest = { ...node };
+	for (const key of keys) delete rest[key];
+	const ctor = node.constructor;
+	return new ctor(rest, { disableChecks: true });
+};
+
+export { FIDELITY_FIELDS, clearFidelity };

package/internal/treeDepth.js

@@ -0,0 +1,19 @@
+import { GuardExceeded } from "./carriers.js";
+
+// src/internal/treeDepth.ts
+/**
+* Throws {@link GuardExceeded} when `node` nests deeper than `MAX_NESTING_DEPTH`;
+* returns otherwise. Never recurses, so it is safe on a tree of any depth.
+*
+* @internal
+*/
+const assertWithinNestingDepth = (node) => {
+	const stack = [[node, 0]];
+	while (stack.length > 0) {
+		const [current, depth] = stack.pop();
+		if (current.type !== "root" && depth > 256) throw new GuardExceeded("NestingDepthExceeded", 256, depth, current.position.start.offset);
+		if ("children" in current) for (const child of current.children) stack.push([child, depth + 1]);
+	}
+};
+
+export { assertWithinNestingDepth };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/markdown",
-	"version": "0.21.0",
+	"version": "0.23.0",
 	"private": false,
 	"description": "CommonMark and GFM markdown parse, edit and transform schemas for Effect",
 	"keywords": [
@@ -41,7 +41,7 @@
 	"peerDependencies": {
 		"@effected/jsonc": "^0.20.0",
 		"@effected/toml": "^0.16.0",
-		"@effected/yaml": "^0.24.0",
+		"@effected/yaml": "^0.25.1",
 		"effect": "^4.0.0"
 	},
 	"peerDependenciesMeta": {