@effected/markdown 0.6.2 → 0.6.3

package/Markdown.js

@@ -192,6 +192,54 @@ var Markdown = class Markdown {
 	* contract — but is not a byte-level round-trip of any original source;
 	* 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
+	* 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
+	* markdown should serialize through here rather than through a third-party
+	* stringifier whose defaults are free to move.
+	*
+	* The canonical choices a byte-level assertion depends on, for a node
+	* carrying no fidelity field:
+	*
+	* | Construct | Canonical form |
+	* | --- | --- |
+	* | Heading | ATX (`## x`), at every depth |
+	* | Thematic break | `***` |
+	* | Bullet list marker | `-` |
+	* | Ordered list delimiter | `.`, flipping to `)` to separate an immediately adjacent sibling list |
+	* | Emphasis / strong | `*` / `**` |
+	* | Code block | fenced when the node carries a `lang` or a `fenceChar`, with the fence grown past any interior backtick run; otherwise indented — **except where indenting would not re-parse as a code block**, which forces a fence (see below) |
+	* | Block separation | exactly one blank line |
+	* | Document | a single trailing newline |
+	*
+	* A node carrying a fidelity field overrides the corresponding row —
+	* `headingStyle: "setext"`, `markerChar`, `fenceChar`, `delimiter` — which
+	* is how a parsed document re-serializes in its author's spelling. The
+	* rows describe a synthesized node, which is the case a test asserting on
+	* generated markdown actually has.
+	*
+	* **Representability wins over the table.** The canonical form never emits
+	* text that would re-parse as something else, so a row yields where the two
+	* conflict. The case that reaches a consumer is the indented code block: an
+	* indented block directly after a list is absorbed as list content, so a
+	* `Code` node with neither `lang` nor `fenceChar` emits **fenced** in that
+	* position and indented everywhere else. A byte-level assertion over
+	* synthesized code blocks therefore depends on the preceding sibling.
+	*
+	* **The posture that makes this a non-issue**, and the one a consumer
+	* building trees for byte-level assertion should adopt: set `fenceChar` on
+	* every `Code` node that carries neither a `lang` nor one already, in a
+	* post-decode walk that reaches nested nodes. The choice then leaves the
+	* emitter entirely and no output depends on a node's neighbours.
+	*
+	* To *normalize* a document to different choices — a `-` list rewritten to
+	* `*`, setext headings rewritten to ATX — use `MarkdownFormat` with
+	* `MarkdownFormattingOptions`. That is the configurable surface; this one
+	* deliberately is not.
+	*
 	* Failure is rare by design, symmetric with parse: only a hardening-guard
 	* trip on a tree nesting past the depth cap fails, and only synthesized
 	* or decoded trees can nest that far.
@@ -220,6 +268,18 @@ var Markdown = class Markdown {
 	* {@link Markdown.stringifyResult} — synchronous callers can use that
 	* variant directly.
 	*
+	* @remarks
+	* The canonical form is a **stability commitment** and safe to assert
+	* against byte-for-byte; the choices it makes, and the reason changing one
+	* is a breaking change, are documented on
+	* {@link Markdown.stringifyResult}.
+	*
+	* **Fidelity fields must be set on the DECODED tree.** `Mdast.fromMdast`
+	* admits spec mdast and strips everything outside it, so a `fenceChar`,
+	* `headingStyle`, `markerChar` or `delimiter` placed on a plain mdast tree
+	* before admission is silently dropped and the canonical default applies.
+	* Set them on the nodes that come back.
+	*
 	* @param root - The document tree to serialize.
 	* @returns An `Effect` that succeeds with markdown source, or fails with
 	*   {@link MarkdownStringifyError}.

package/Mdast.js

@@ -361,6 +361,14 @@ var Mdast = class Mdast {
 	* decode into the {@link Frontmatter} capture. Unknown node types fail
 	* typed.
 	*
+	* **This package's fidelity fields are among the fields dropped**, because
+	* they are not spec mdast. A `fenceChar`, `headingStyle`, `markerChar` or
+	* `delimiter` set on the tree BEFORE admission is silently discarded, and
+	* the node then serializes with the canonical default — set them on the
+	* decoded nodes this returns instead. The drop is correct (the boundary
+	* admits spec mdast and nothing else) but it is silent, which is why it is
+	* called out here.
+	*
 	* @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/README.md

@@ -261,6 +261,33 @@ if (Result.isSuccess(parsed)) {
 
 `Mdast.fromMdast` goes the other way as a checked admission boundary: it validates a foreign tree and synthesizes zero-width sentinel positions where one is absent or incomplete. Trees admitted that way serve tree-level workflows and canonical `stringify`; offset-splice editing needs the real positions only a parse produces.
 
+## 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.
+
+For a node carrying no fidelity field:
+
+| Construct | Canonical form |
+| --- | --- |
+| Heading | ATX (`## x`), at every depth |
+| Thematic break | `***` |
+| Bullet list marker | `-` |
+| Ordered list delimiter | `.`, flipping to `)` to separate an immediately adjacent sibling list |
+| Emphasis / strong | `*` / `**` |
+| Code block | fenced when the node carries a `lang` or a `fenceChar`, with the fence grown past any interior backtick run; otherwise indented — except where indenting would not re-parse as a code block, which forces a fence |
+| Block separation | exactly one blank line |
+| Document | a single trailing newline |
+
+**Representability wins over the table.** The canonical form never emits text that would re-parse as something else, so a row yields where the two conflict. The case that reaches a consumer is the indented code block: an indented block directly after a list is absorbed as list content, so a `Code` node with neither `lang` nor `fenceChar` emits fenced in that position and indented everywhere else. A byte-level assertion over synthesized code blocks therefore depends on the preceding sibling.
+
+The posture that makes this a non-issue — and the one to adopt if you build trees and assert on their bytes — is to set `fenceChar` on every `Code` node carrying neither a `lang` nor one already, in a post-decode walk that reaches nested nodes. The choice then leaves the emitter entirely and no output depends on a node's neighbours.
+
+Fidelity fields must be set on the **decoded** tree: `Mdast.fromMdast` admits spec mdast and strips everything outside it, so a `fenceChar` placed on a plain mdast tree before admission is silently dropped.
+
+A node that carries a fidelity field overrides the matching row — `headingStyle`, `markerChar`, `fenceChar`, `delimiter` — which is how a parsed document re-serializes in its author's spelling. The table describes a synthesized node, which is what a test asserting on generated markdown actually holds.
+
+To *normalize* an existing document to different choices, use `MarkdownFormat` with `MarkdownFormattingOptions`. That is the configurable surface; this one deliberately is not.
+
 ## Features
 
 - `Markdown` — `parse`/`stringify` as `Effect`s with typed `MarkdownParseError`/`MarkdownStringifyError` channels, the pure `parseResult`/`stringifyResult` twins for synchronous callers, and the `MarkdownFromString` two-way codec.

package/index.d.ts

@@ -946,6 +946,54 @@ declare class Markdown {
    * contract — but is not a byte-level round-trip of any original source;
    * 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
+   * 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
+   * markdown should serialize through here rather than through a third-party
+   * stringifier whose defaults are free to move.
+   *
+   * The canonical choices a byte-level assertion depends on, for a node
+   * carrying no fidelity field:
+   *
+   * | Construct | Canonical form |
+   * | --- | --- |
+   * | Heading | ATX (`## x`), at every depth |
+   * | Thematic break | `***` |
+   * | Bullet list marker | `-` |
+   * | Ordered list delimiter | `.`, flipping to `)` to separate an immediately adjacent sibling list |
+   * | Emphasis / strong | `*` / `**` |
+   * | Code block | fenced when the node carries a `lang` or a `fenceChar`, with the fence grown past any interior backtick run; otherwise indented — **except where indenting would not re-parse as a code block**, which forces a fence (see below) |
+   * | Block separation | exactly one blank line |
+   * | Document | a single trailing newline |
+   *
+   * A node carrying a fidelity field overrides the corresponding row —
+   * `headingStyle: "setext"`, `markerChar`, `fenceChar`, `delimiter` — which
+   * is how a parsed document re-serializes in its author's spelling. The
+   * rows describe a synthesized node, which is the case a test asserting on
+   * generated markdown actually has.
+   *
+   * **Representability wins over the table.** The canonical form never emits
+   * text that would re-parse as something else, so a row yields where the two
+   * conflict. The case that reaches a consumer is the indented code block: an
+   * indented block directly after a list is absorbed as list content, so a
+   * `Code` node with neither `lang` nor `fenceChar` emits **fenced** in that
+   * position and indented everywhere else. A byte-level assertion over
+   * synthesized code blocks therefore depends on the preceding sibling.
+   *
+   * **The posture that makes this a non-issue**, and the one a consumer
+   * building trees for byte-level assertion should adopt: set `fenceChar` on
+   * every `Code` node that carries neither a `lang` nor one already, in a
+   * post-decode walk that reaches nested nodes. The choice then leaves the
+   * emitter entirely and no output depends on a node's neighbours.
+   *
+   * To *normalize* a document to different choices — a `-` list rewritten to
+   * `*`, setext headings rewritten to ATX — use `MarkdownFormat` with
+   * `MarkdownFormattingOptions`. That is the configurable surface; this one
+   * deliberately is not.
+   *
    * Failure is rare by design, symmetric with parse: only a hardening-guard
    * trip on a tree nesting past the depth cap fails, and only synthesized
    * or decoded trees can nest that far.
@@ -960,6 +1008,18 @@ declare class Markdown {
    * {@link Markdown.stringifyResult} — synchronous callers can use that
    * variant directly.
    *
+   * @remarks
+   * The canonical form is a **stability commitment** and safe to assert
+   * against byte-for-byte; the choices it makes, and the reason changing one
+   * is a breaking change, are documented on
+   * {@link Markdown.stringifyResult}.
+   *
+   * **Fidelity fields must be set on the DECODED tree.** `Mdast.fromMdast`
+   * admits spec mdast and strips everything outside it, so a `fenceChar`,
+   * `headingStyle`, `markerChar` or `delimiter` placed on a plain mdast tree
+   * before admission is silently dropped and the canonical default applies.
+   * Set them on the nodes that come back.
+   *
    * @param root - The document tree to serialize.
    * @returns An `Effect` that succeeds with markdown source, or fails with
    *   {@link MarkdownStringifyError}.
@@ -2344,6 +2404,14 @@ declare class Mdast {
    * decode into the {@link Frontmatter} capture. Unknown node types fail
    * typed.
    *
+   * **This package's fidelity fields are among the fields dropped**, because
+   * they are not spec mdast. A `fenceChar`, `headingStyle`, `markerChar` or
+   * `delimiter` set on the tree BEFORE admission is silently discarded, and
+   * the node then serializes with the canonical default — set them on the
+   * decoded nodes this returns instead. The drop is correct (the boundary
+   * admits spec mdast and nothing else) but it is silent, which is why it is
+   * called out here.
+   *
    * @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.6.2",
+	"version": "0.6.3",
 	"private": false,
 	"description": "CommonMark and GFM markdown parse, edit and transform schemas for Effect",
 	"keywords": [