@savvy-web/silk-effects 9.6.0 → 10.0.0

package/changesets/transforms/maintenance-note.js

@@ -0,0 +1,65 @@
+import { getHeadingText, getVersionBlocks, isHeadingOfDepth } from "../utils/blocks.js";
+import { Heading, InlineCode, List, ListItem, Mdast, Paragraph, Root, Text } from "@effected/markdown";
+
+// src/changesets/transforms/maintenance-note.ts
+/**
+* Placeholder sentence `@changesets/apply-release-plan` (>= 8.1.0) emits as the
+* body of a version block that would otherwise render as a bare heading.
+*/
+const ENGINE_PLACEHOLDER = "No changes in this release.";
+/** True when the block's only content is the engine's empty-release placeholder. */
+function isPlaceholderOnly(children, block) {
+	if (block.endIndex - block.startIndex !== 1) return false;
+	const node = children[block.startIndex];
+	return node.type === "paragraph" && Mdast.toText(node).trim() === ENGINE_PLACEHOLDER;
+}
+function buildNoteChildren(reason) {
+	if (reason.kind === "unspecified" || reason.triggers.length === 0) return [new Text({ value: "Version-only release to keep workspace versions consistent; no changes to this package." })];
+	const label = reason.kind === "fixed" ? "fixed version group" : "linked version group";
+	const nodes = [new Text({ value: "Released in lockstep with " })];
+	reason.triggers.forEach((trigger, index) => {
+		if (index > 0) nodes.push(new Text({ value: ", " }));
+		nodes.push(new InlineCode({ value: `${trigger.name}@${trigger.version}` }));
+	});
+	nodes.push(new Text({ value: ` (${label}).` }));
+	return nodes;
+}
+/**
+* Build a transform that adds a Maintenance note to the targeted empty version block.
+*
+* @param options - The target version and the release reason
+* @returns A transform; a no-op when the block is absent or non-empty
+*
+* @internal
+*/
+function maintenanceNote(options) {
+	return (root) => {
+		const children = [...root.children];
+		const block = getVersionBlocks(children).find((b) => {
+			const node = children[b.headingIndex];
+			return isHeadingOfDepth(node, [2]) && getHeadingText(node) === options.version;
+		});
+		if (!block) return root;
+		const placeholderOnly = isPlaceholderOnly(children, block);
+		if (block.endIndex > block.startIndex && !placeholderOnly) return root;
+		const heading = new Heading({
+			depth: 3,
+			children: [new Text({ value: "Maintenance" })]
+		});
+		const list = new List({
+			ordered: false,
+			spread: false,
+			children: [new ListItem({
+				spread: false,
+				children: [new Paragraph({ children: buildNoteChildren(options.reason) })]
+			})]
+		});
+		children.splice(block.startIndex, placeholderOnly ? 1 : 0, heading, list);
+		return new Root({
+			...root,
+			children
+		});
+	};
+}
+
+export { maintenanceNote };

package/changesets/transforms/merge-sections.js

@@ -0,0 +1,56 @@
+import { fromHeading } from "../categories/index.js";
+import { getBlockSections, getHeadingText, getVersionBlocks } from "../utils/blocks.js";
+import { Root } from "@effected/markdown";
+
+// src/changesets/transforms/merge-sections.ts
+/**
+* Changelog transform: merge duplicate h3 section headings.
+*
+* @remarks
+* Kit transform. Groups h3 sections within each version
+* block by normalized heading text (via the category system's `fromHeading`)
+* and moves the content of duplicates under the first occurrence, then drops
+* the duplicate headings. Runs after dependency-table aggregation and before
+* section reordering.
+*
+* @internal
+*/
+/**
+* Merge duplicate h3 sections within each version block.
+*
+* @param root - The changelog tree
+* @returns A tree with a single section per heading in each version block
+*
+* @internal
+*/
+const mergeSections = (root) => {
+	const children = [...root.children];
+	const blocks = getVersionBlocks(children);
+	for (let b = blocks.length - 1; b >= 0; b--) {
+		const sections = getBlockSections(children, blocks[b]);
+		if (sections.length <= 1) continue;
+		const groups = /* @__PURE__ */ new Map();
+		for (let s = 0; s < sections.length; s++) {
+			const text = getHeadingText(sections[s].heading);
+			const category = fromHeading(text);
+			const key = category ? category.heading.toLowerCase() : text.toLowerCase();
+			const existing = groups.get(key);
+			if (existing) existing.push(s);
+			else groups.set(key, [s]);
+		}
+		if (![...groups.values()].some((indices) => indices.length > 1)) continue;
+		const block = blocks[b];
+		const rebuilt = children.slice(block.startIndex, sections[0].headingIndex);
+		for (const indices of groups.values()) {
+			const [target, ...duplicates] = indices.map((s) => sections[s]);
+			rebuilt.push(target.heading, ...target.contentNodes, ...duplicates.flatMap((d) => d.contentNodes));
+		}
+		children.splice(block.startIndex, block.endIndex - block.startIndex, ...rebuilt);
+	}
+	return new Root({
+		...root,
+		children
+	});
+};
+
+export { mergeSections };

package/changesets/transforms/normalize-format.js

@@ -0,0 +1,53 @@
+import { getVersionBlocks, isHeadingOfDepth } from "../utils/blocks.js";
+import { Mdast, Root } from "@effected/markdown";
+
+// src/changesets/transforms/normalize-format.ts
+/**
+* Changelog transform: remove empty sections and empty lists.
+*
+* @remarks
+* Kit transform. Within each version block, drops empty
+* lists and h3 sections with no content before the next h2/h3 (or the end of
+* the block), along with whitespace-only paragraphs that trail them.
+*
+* @internal
+*/
+/**
+* Remove empty h3 sections and empty lists from each version block.
+*
+* @param root - The changelog tree
+* @returns The normalized tree
+*
+* @internal
+*/
+const normalizeFormat = (root) => {
+	const children = [...root.children];
+	const indicesToRemove = /* @__PURE__ */ new Set();
+	for (const block of getVersionBlocks(children)) for (let i = block.startIndex; i < block.endIndex; i++) {
+		const node = children[i];
+		if (node.type === "list" && node.children.length === 0) {
+			indicesToRemove.add(i);
+			continue;
+		}
+		if (!isHeadingOfDepth(node, [3])) continue;
+		let hasContent = false;
+		for (let j = i + 1; j < block.endIndex; j++) {
+			const next = children[j];
+			if (next.type === "paragraph" && Mdast.toText(next).trim() === "") {
+				indicesToRemove.add(j);
+				continue;
+			}
+			if (isHeadingOfDepth(next, [2, 3])) break;
+			if (next.type === "definition") continue;
+			hasContent = true;
+			break;
+		}
+		if (!hasContent) indicesToRemove.add(i);
+	}
+	return new Root({
+		...root,
+		children: children.filter((_, i) => !indicesToRemove.has(i))
+	});
+};
+
+export { normalizeFormat };

package/changesets/transforms/reorder-sections.js

@@ -0,0 +1,53 @@
+import { fromHeading } from "../categories/index.js";
+import { getBlockSections, getHeadingText, getVersionBlocks } from "../utils/blocks.js";
+import { Root } from "@effected/markdown";
+
+// src/changesets/transforms/reorder-sections.ts
+/**
+* Changelog transform: reorder h3 sections by category priority.
+*
+* @remarks
+* Kit transform. Sorts sections within each version
+* block so Breaking Changes come first and Other last; unknown headings sort
+* after every category and a `Thanks` section is pinned to the very end.
+*
+* @internal
+*/
+/** Default priority for unrecognized headings (after all known categories). */
+const UNKNOWN_PRIORITY = 999;
+/** Priority for the `Thanks` section; closes the version block. */
+const THANKS_PRIORITY = 1e3;
+/** Resolve the sort priority for a section heading. */
+function headingPriority(text) {
+	if (text.trim().toLowerCase() === "thanks") return THANKS_PRIORITY;
+	return fromHeading(text)?.priority ?? UNKNOWN_PRIORITY;
+}
+/**
+* Reorder h3 sections within each version block by category priority.
+*
+* @param root - The changelog tree
+* @returns A tree with sections in priority order
+*
+* @internal
+*/
+const reorderSections = (root) => {
+	const children = [...root.children];
+	const blocks = getVersionBlocks(children);
+	for (let b = blocks.length - 1; b >= 0; b--) {
+		const block = blocks[b];
+		const sections = getBlockSections(children, block);
+		if (sections.length <= 1) continue;
+		const preamble = children.slice(block.startIndex, sections[0].headingIndex);
+		const sorted = [...sections].sort((x, y) => headingPriority(getHeadingText(x.heading)) - headingPriority(getHeadingText(y.heading)));
+		if (sorted.every((s, i) => s.headingIndex === sections[i].headingIndex)) continue;
+		const rebuilt = [...preamble];
+		for (const section of sorted) rebuilt.push(section.heading, ...section.contentNodes);
+		children.splice(block.startIndex, block.endIndex - block.startIndex, ...rebuilt);
+	}
+	return new Root({
+		...root,
+		children
+	});
+};
+
+export { reorderSections };

package/changesets/utils/blocks.js

@@ -0,0 +1,67 @@
+import { Mdast } from "@effected/markdown";
+
+// src/changesets/utils/blocks.ts
+/**
+* Whether a node is a heading of one of the given depths.
+*
+* @param node - The node to test
+* @param depths - Accepted heading depths
+* @returns True (narrowing to `Heading`) when the node matches
+*
+* @internal
+*/
+function isHeadingOfDepth(node, depths) {
+	return node.type === "heading" && depths.includes(node.depth);
+}
+/**
+* Extract all version (h2) blocks from a children array.
+*
+* @param children - The root children
+* @returns Version blocks in document order
+*
+* @internal
+*/
+function getVersionBlocks(children) {
+	const headings = [];
+	for (let i = 0; i < children.length; i++) if (isHeadingOfDepth(children[i], [2])) headings.push(i);
+	return headings.map((headingIndex, n) => ({
+		headingIndex,
+		startIndex: headingIndex + 1,
+		endIndex: n + 1 < headings.length ? headings[n + 1] : children.length
+	}));
+}
+/**
+* Extract h3 sections within a version block; content before the first h3 is excluded.
+*
+* @param children - The root children
+* @param block - The version block to scan
+* @returns Sections in document order
+*
+* @internal
+*/
+function getBlockSections(children, block) {
+	const sections = [];
+	for (let i = block.startIndex; i < block.endIndex; i++) {
+		const node = children[i];
+		if (isHeadingOfDepth(node, [3])) sections.push({
+			heading: node,
+			headingIndex: i,
+			contentNodes: []
+		});
+		else if (sections.length > 0) sections[sections.length - 1].contentNodes.push(node);
+	}
+	return sections;
+}
+/**
+* Plain text of a heading.
+*
+* @param heading - The heading node
+* @returns Concatenated inline text
+*
+* @internal
+*/
+function getHeadingText(heading) {
+	return Mdast.toText(heading);
+}
+
+export { getBlockSections, getHeadingText, getVersionBlocks, isHeadingOfDepth };

package/changesets/utils/dependency-table.js

@@ -1,17 +1,18 @@
 import { DependencyTableRowSchema } from "../schemas/dependency-table.js";
-import { stringifyMarkdown } from "./remark-pipeline.js";
+import { emitKitMarkdown } from "./markdown-emit.js";
 import { Schema } from "effect";
-import { toString } from "mdast-util-to-string";
+import { Mdast, Root, Table, TableCell, TableRow, Text } from "@effected/markdown";
 
 // src/changesets/utils/dependency-table.ts
 /**
 * Dependency table utilities for parsing, serializing, collapsing, and sorting
-* dependency table rows between MDAST table nodes and typed representations.
+* dependency table rows between `@effected/markdown` `Table` nodes and typed
+* representations.
 *
 * @remarks
 * This module provides the low-level functional primitives that the
 * {@link DependencyTable} class wraps with a stateful, fluent API.
-* It operates on arrays of `DependencyTableRow` objects and MDAST `Table`
+* It operates on arrays of `DependencyTableRow` objects and kit `Table`
 * nodes, converting between the two representations.
 *
 * The collapse algorithm merges rows sharing the same `dependency + type`
@@ -55,14 +56,14 @@ const COLUMN_KEYS = [
 /** Schema decoder for validating raw cell values into a typed row. */
 const decode = Schema.decodeUnknownSync(DependencyTableRowSchema);
 /**
-* Parse an MDAST table node into validated dependency table rows.
+* Parse a kit table node into validated dependency table rows.
 *
 * @remarks
 * Validates the header row against {@link COLUMN_HEADERS} (case-insensitive),
 * then decodes each data row through the `DependencyTableRowSchema` for
 * type-safe validation of action values, version strings, and dependency types.
 *
-* @param table - An MDAST `Table` node (from remark-gfm)
+* @param table - An `@effected/markdown` `Table` node
 * @returns Array of validated `DependencyTableRow` objects
 * @throws If the table has fewer than 2 rows (header + at least one data row)
 * @throws If the header columns do not match the expected column names
@@ -71,11 +72,11 @@ const decode = Schema.decodeUnknownSync(DependencyTableRowSchema);
 * @example
 * ```typescript
 * import { parseDependencyTable } from "../utils/dependency-table.js";
-* import { parseMarkdown } from "../utils/remark-pipeline.js";
-* import type { Table } from "mdast";
+* import { parseKitMarkdown } from "../utils/markdown-emit.js";
+* import type { Table } from "\@effected/markdown";
 *
-* const tree = parseMarkdown("| Dependency | Type | Action | From | To |\n| --- | --- | --- | --- | --- |\n| foo | dependency | added | — | 1.0.0 |");
-* const table = tree.children.find((n) => n.type === "table") as Table;
+* const tree = parseKitMarkdown("| Dependency | Type | Action | From | To |\n| --- | --- | --- | --- | --- |\n| foo | dependency | added | — | 1.0.0 |");
+* const table = tree.children.find((n): n is Table => n.type === "table");
 * const rows = parseDependencyTable(table);
 * // rows[0].dependency === "foo"
 * ```
@@ -85,14 +86,17 @@ const decode = Schema.decodeUnknownSync(DependencyTableRowSchema);
 function parseDependencyTable(table) {
 	const rows = table.children;
 	if (rows.length < 2) throw new Error("Dependency table must have at least one data row");
-	const headers = rows[0].children.map((cell) => toString(cell).trim().toLowerCase());
+	const headers = rows[0].children.map((cell) => Mdast.toText(cell).trim().toLowerCase());
 	const expected = COLUMN_HEADERS.map((h) => h.toLowerCase());
 	if (headers.length !== expected.length || !headers.every((h, i) => h === expected[i])) throw new Error(`Table must have columns: ${COLUMN_HEADERS.join(", ")}. Got: ${headers.join(", ")}`);
 	const result = [];
 	for (let i = 1; i < rows.length; i++) {
 		const cells = rows[i].children;
 		const raw = {};
-		for (let c = 0; c < COLUMN_KEYS.length; c++) raw[COLUMN_KEYS[c]] = toString(cells[c]).trim();
+		for (let c = 0; c < COLUMN_KEYS.length; c++) {
+			const cell = cells[c];
+			raw[COLUMN_KEYS[c]] = cell === void 0 ? "" : Mdast.toText(cell).trim();
+		}
 		result.push(decode(raw));
 	}
 	return result;
@@ -113,36 +117,29 @@ function parseDependencyTable(table) {
 * through parse-and-reserialize regardless of which spelling produced them.
 *
 * @param text - The cell text content
-* @returns An MDAST `TableCell` node
+* @returns A kit `TableCell` node
 *
 * @internal
 */
 function makeCell(text) {
-	return {
-		type: "tableCell",
-		children: [{
-			type: "text",
-			value: text,
-			escapeStyle: "literal"
-		}]
-	};
+	return new TableCell({ children: [new Text({
+		value: text,
+		escapeStyle: "literal"
+	})] });
 }
 /**
 * Create a table row from an array of cell texts.
 *
 * @param texts - Array of cell text values
-* @returns An MDAST `TableRow` node
+* @returns A kit `TableRow` node
 *
 * @internal
 */
 function makeRow(texts) {
-	return {
-		type: "tableRow",
-		children: texts.map(makeCell)
-	};
+	return new TableRow({ children: texts.map(makeCell) });
 }
 /**
-* Serialize dependency table rows into an MDAST `Table` node.
+* Serialize dependency table rows into a kit `Table` node.
 *
 * @remarks
 * Creates a well-formed GFM table with the canonical header row
@@ -150,7 +147,7 @@ function makeRow(texts) {
 * The inverse of {@link parseDependencyTable}.
 *
 * @param rows - Array of `DependencyTableRow` objects
-* @returns An MDAST `Table` node ready for insertion into an AST
+* @returns A kit `Table` node ready for insertion into a kit tree
 *
 * @example
 * ```typescript
@@ -168,10 +165,9 @@ function makeRow(texts) {
 * @internal
 */
 function serializeDependencyTable(rows) {
-	return {
-		type: "table",
-		children: [makeRow([...COLUMN_HEADERS]), ...rows.map((row) => makeRow(COLUMN_KEYS.map((key) => row[key])))]
-	};
+	const headerRow = makeRow([...COLUMN_HEADERS]);
+	const dataRows = rows.map((row) => makeRow(COLUMN_KEYS.map((key) => row[key])));
+	return new Table({ children: [headerRow, ...dataRows] });
 }
 /**
 * Serialize dependency table rows to a markdown table string.
@@ -200,10 +196,7 @@ function serializeDependencyTable(rows) {
 */
 function serializeDependencyTableToMarkdown(rows) {
 	const table = serializeDependencyTable(rows);
-	return stringifyMarkdown({
-		type: "root",
-		children: [table]
-	}).trim();
+	return emitKitMarkdown(new Root({ children: [table] })).trim();
 }
 /**
 * Sort priority for dependency actions: removed first, then updated, then added.

package/changesets/utils/markdown-emit.js

@@ -7,8 +7,8 @@ import { Code, Markdown, MarkdownTransform, Mdast } from "@effected/markdown";
 * into a defect.
 *
 * @remarks
-* The trees this pipeline emits are either parsed by our own remark pipeline
-* or synthesized by our own plugins, so a decode or stringify failure is a
+* The trees this pipeline emits are either parsed by our own parser or
+* synthesized by our own transforms, so a decode or stringify failure is a
 * programmer error, not an operational condition — the sync call sites treat
 * it as a defect with the typed error preserved as `cause`.
 *
@@ -26,18 +26,17 @@ function unwrap(result, context) {
 *
 * @remarks
 * The kit's canonical form emits a code node carrying neither `lang` nor
-* `fenceChar` as an INDENTED block — and `lang: null` is exactly what
-* remark-parse produces for a ``` fence with no info string, so without this
-* pass every language-less snippet in changelog content would change shape.
+* `fenceChar` as an INDENTED block — and that is exactly what a ``` fence with
+* no info string becomes once {@link parseKitMarkdown}'s mdast round trip
+* strips fidelity fields, so without this pass every language-less snippet in
+* changelog content would change shape.
 * Worse, the indented default is neighbor-dependent: the serializer takes a
 * representability escape back to a backtick fence when the indented form
 * would misparse (e.g. code immediately after a list), so the same node
 * spells differently depending on what precedes it — inconsistent raw
 * output. House policy is fenced code everywhere, so the ONE emit boundary defaults
-* the kit's own per-node fidelity field, `fenceChar`, post-decode. It has to
-* happen post-decode: `Mdast.fromMdast` drops non-mdast fields from foreign
-* trees, so a `fenceChar` set on the plain tree would never survive the
-* boundary. `MarkdownTransform.map` rebuilds only the paths to a changed
+* the kit's own per-node fidelity field, `fenceChar`, at emit time.
+* `MarkdownTransform.map` rebuilds only the paths to a changed
 * code node; every other subtree is returned by reference.
 *
 * @internal
@@ -49,34 +48,11 @@ function ensureFencedCode(node) {
 	}) : code });
 }
 /**
-* Serialize a plain MDAST tree to canonical markdown.
-*
-* @remarks
-* The single emit chokepoint for the changesets pipeline: decodes the plain
-* mdast tree into `@effected/markdown`'s node classes via
-* `Mdast.fromMdastResult` and serializes it with `Markdown.stringifyResult`.
-* Synchronous on purpose — every call site is a sync string pipeline — and
-* failures (an undecodable node type, the nesting-depth hardening guard) are
-* defects on self-built trees, so they throw rather than surface typed.
-*
-* The output always ends with exactly one trailing newline, matching the
-* kit's document-level canonical rule.
-*
-* @param tree - The plain mdast root to serialize
-* @returns Canonical markdown text
-*
-* @internal
-*/
-function emitMarkdown(tree) {
-	const fenced = ensureFencedCode(unwrap(Mdast.fromMdastResult(tree), "markdown emit: mdast tree failed to decode"));
-	return unwrap(Markdown.stringifyResult(fenced), "markdown emit: canonical stringify failed");
-}
-/**
 * Parse markdown text straight into `@effected/markdown`'s node classes (GFM
 * dialect, frontmatter capture off).
 *
 * @remarks
-* Synchronous for the same reason as {@link emitMarkdown}; the kit's parser
+* Synchronous because every call site is a sync string pipeline; the kit's parser
 * is total over text, so a failure here is a defect (the nesting-depth
 * hardening guard), not an operational condition.
 *
@@ -93,8 +69,7 @@ function parseKitMarkdown(text) {
 * Serialize a kit root, or a single kit block node, to canonical markdown.
 *
 * @remarks
-* The kit-tree twin of {@link emitMarkdown}: the same fence normalization,
-* then `Markdown.stringifyResult`. A lone block node emits byte-identically
+* Applies the fence normalization, then `Markdown.stringifyResult`. A lone block node emits byte-identically
 * to a one-child root, trailing newline included.
 *
 * @param node - The kit root or block node to serialize
@@ -106,4 +81,4 @@ function emitKitMarkdown(node) {
 	return unwrap(Markdown.stringifyResult(ensureFencedCode(node)), "markdown emit: canonical stringify failed");
 }
 
-export { emitKitMarkdown, emitMarkdown, parseKitMarkdown };
+export { emitKitMarkdown, parseKitMarkdown };