@savvy-web/changesets 0.4.2 → 0.5.0

package/esm/index.js

@@ -1,6 +1,7 @@
 import { BREAKING_CHANGES, PERFORMANCE, fromHeading, allHeadings, resolveCommitType, CI, TESTS, DEPENDENCIES, OTHER, CATEGORIES, FEATURES, BUG_FIXES, REVERTS, DOCUMENTATION, isValidHeading, BUILD_SYSTEM, REFACTORING, MAINTENANCE } from "./60.js";
-import { default as changelog, NonEmptyString } from "./160.js";
-import { Context, Schema } from "./795.js";
+import { default as changelog } from "./160.js";
+import { parseDependencyTable, serializeDependencyTable, collapseDependencyRows, serializeDependencyTableToMarkdown, NonEmptyString, sortDependencyRows } from "./891.js";
+import { Context, Schema } from "./855.js";
 class Categories {
     static BREAKING_CHANGES = BREAKING_CHANGES;
     static FEATURES = FEATURES;
@@ -37,6 +38,26 @@ class Changelog {
         return changelog.getDependencyReleaseLine(changesets, dependenciesUpdated, options);
     }
 }
+class DependencyTable {
+    static parse(tableNode) {
+        return parseDependencyTable(tableNode);
+    }
+    static serialize(rows) {
+        return serializeDependencyTable(rows);
+    }
+    static toMarkdown(rows) {
+        return serializeDependencyTableToMarkdown(rows);
+    }
+    static collapse(rows) {
+        return collapseDependencyRows(rows);
+    }
+    static sort(rows) {
+        return sortDependencyRows(rows);
+    }
+    static aggregate(rows) {
+        return sortDependencyRows(collapseDependencyRows(rows));
+    }
+}
 const _tag = Context.Tag("ChangelogService");
 const ChangelogServiceBase = _tag();
 class ChangelogService extends ChangelogServiceBase {
@@ -71,6 +92,7 @@ const DependencyUpdateSchema = Schema.Struct({
     newVersion: Schema.String
 });
 export { ChangelogTransformer, ChangesetLinter } from "./273.js";
-export { ChangesetOptionsSchema, GitHubInfoSchema, GitHubLive, GitHubService, GitHubServiceBase, IssueNumberSchema, MarkdownLive, MarkdownService, MarkdownServiceBase, NonEmptyString, PositiveInteger, RepoSchema, UrlOrMarkdownLinkSchema, UsernameSchema, makeGitHubTest } from "./160.js";
-export { ChangesetValidationError, ChangesetValidationErrorBase, ConfigurationError, ConfigurationErrorBase, GitHubApiError, GitHubApiErrorBase, JsonPathSchema, MarkdownParseError, MarkdownParseErrorBase, VersionFileConfigSchema, VersionFileError, VersionFileErrorBase, VersionFilesSchema } from "./795.js";
-export { Categories, Changelog, ChangelogService, ChangelogServiceBase, ChangesetSchema, ChangesetSummarySchema, CommitHashSchema, DependencyTypeSchema, DependencyUpdateSchema, SectionCategorySchema, VersionTypeSchema };
+export { ChangesetOptionsSchema, GitHubInfoSchema, GitHubLive, GitHubService, GitHubServiceBase, IssueNumberSchema, MarkdownLive, MarkdownService, MarkdownServiceBase, RepoSchema, UrlOrMarkdownLinkSchema, UsernameSchema, makeGitHubTest } from "./160.js";
+export { ChangesetValidationError, ChangesetValidationErrorBase, ConfigurationError, ConfigurationErrorBase, GitHubApiError, GitHubApiErrorBase, JsonPathSchema, MarkdownParseError, MarkdownParseErrorBase, VersionFileConfigSchema, VersionFileError, VersionFileErrorBase, VersionFilesSchema } from "./725.js";
+export { DependencyActionSchema, DependencyTableRowSchema, DependencyTableSchema, DependencyTableTypeSchema, NonEmptyString, PositiveInteger, VersionOrEmptySchema } from "./891.js";
+export { Categories, Changelog, ChangelogService, ChangelogServiceBase, ChangesetSchema, ChangesetSummarySchema, CommitHashSchema, DependencyTable, DependencyTypeSchema, DependencyUpdateSchema, SectionCategorySchema, VersionTypeSchema };

package/esm/markdownlint.d.ts

@@ -1,14 +1,24 @@
 /**
+ * \@savvy-web/changesets/markdownlint
+ *
  * markdownlint custom rules for validating changeset file structure.
  *
  * Provides the same validation as the remark-lint rules but using
  * markdownlint's micromark token API for integration with
  * markdownlint-cli2 and the VS Code markdownlint extension.
  *
- * - `changeset-heading-hierarchy` (CSH001): Enforce h2 start, no h1, no depth skips
- * - `changeset-required-sections` (CSH002): Validate section headings match known categories
- * - `changeset-content-structure` (CSH003): Content quality validation
- * - `changeset-uncategorized-content` (CSH004): Reject content before first h2 heading
+ * Rules included:
+ * - {@link HeadingHierarchyRule | changeset-heading-hierarchy} (CSH001): Enforce h2 start, no h1, no depth skips
+ * - {@link RequiredSectionsRule | changeset-required-sections} (CSH002): Validate section headings match known categories
+ * - {@link ContentStructureRule | changeset-content-structure} (CSH003): Content quality validation
+ * - {@link UncategorizedContentRule | changeset-uncategorized-content} (CSH004): Reject content before first h2 heading
+ * - {@link DependencyTableFormatRule | changeset-dependency-table-format} (CSH005): Validate dependency table structure
+ *
+ * @see {@link https://github.com/savvy-web/changesets/blob/main/docs/rules/CSH001.md | CSH001 docs}
+ * @see {@link https://github.com/savvy-web/changesets/blob/main/docs/rules/CSH002.md | CSH002 docs}
+ * @see {@link https://github.com/savvy-web/changesets/blob/main/docs/rules/CSH003.md | CSH003 docs}
+ * @see {@link https://github.com/savvy-web/changesets/blob/main/docs/rules/CSH004.md | CSH004 docs}
+ * @see {@link https://github.com/savvy-web/changesets/blob/main/docs/rules/CSH005.md | CSH005 docs}
  *
  * @packageDocumentation
  */
@@ -16,31 +26,103 @@
 import type { Rule } from 'markdownlint';
 
 /**
- * markdownlint rule: changeset-content-structure (CSH003)
+ * markdownlint rule: `changeset-content-structure` (CSH003).
+ *
+ * Validates content quality inside changeset markdown files by inspecting
+ * micromark tokens for three categories of structural problems:
+ *
+ * 1. **Empty sections** -- an `atxHeading` (h2) followed immediately by another
+ *    h2 or the end of the token stream with no intervening content tokens.
+ * 2. **Code blocks without a language identifier** -- a `codeFenced` token whose
+ *    opening fence child lacks a `codeFencedFenceInfo` token.
+ * 3. **Empty list items** -- a `listItemPrefix` token with no subsequent
+ *    `content` token before the next prefix or end of list.
  *
- * Validates content quality in changeset files:
- * - Sections must not be empty (h2 followed immediately by another h2 or EOF)
- * - Code blocks must have a language identifier
- * - List items should have meaningful content (not empty)
+ * @remarks
+ * This rule mirrors the remark-lint rule `remarkLintContentStructure` but uses
+ * markdownlint's micromark token API so it can run inside markdownlint-cli2 and
+ * the VS Code markdownlint extension.
+ *
+ * @example
+ * ```json
+ * {
+ *   "changeset-content-structure": true
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/savvy-web/changesets/blob/main/docs/rules/CSH003.md | CSH003 rule documentation}
+ * @see `src/remark/rules/content-structure.ts` for the corresponding remark-lint rule
+ *
+ * @public
  */
 export declare const ContentStructureRule: Rule;
 
 /**
- * markdownlint rule: changeset-heading-hierarchy (CSH001)
+ * The markdownlint `Rule` object for CSH005 (`changeset-dependency-table-format`).
+ *
+ * @public
+ */
+export declare const DependencyTableFormatRule: Rule;
+
+/**
+ * markdownlint rule: `changeset-heading-hierarchy` (CSH001).
+ *
+ * Validates heading structure in changeset markdown files by inspecting
+ * `atxHeading` micromark tokens for three constraints:
+ *
+ * 1. **No h1 headings** -- h1 is reserved for the version title generated by
+ *    the changelog formatter.
+ * 2. **Start at h2** -- the first heading in a changeset must be h2.
+ * 3. **No depth skips** -- heading levels must increase sequentially
+ *    (h2 then h3, not h2 then h4).
+ *
+ * @remarks
+ * This rule mirrors the remark-lint rule `remarkLintHeadingHierarchy` but uses
+ * markdownlint's micromark token API so it can run inside markdownlint-cli2 and
+ * the VS Code markdownlint extension.
+ *
+ * @example
+ * ```json
+ * {
+ *   "changeset-heading-hierarchy": true
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/savvy-web/changesets/blob/main/docs/rules/CSH001.md | CSH001 rule documentation}
+ * @see `src/remark/rules/heading-hierarchy.ts` for the corresponding remark-lint rule
  *
- * Validates heading structure in changeset files:
- * - No h1 headings allowed
- * - Headings must start at h2
- * - No depth skips (e.g., h2 ... h4 is invalid)
+ * @public
  */
 export declare const HeadingHierarchyRule: Rule;
 
 /**
- * markdownlint rule: changeset-required-sections (CSH002)
+ * markdownlint rule: `changeset-required-sections` (CSH002).
+ *
+ * Validates that every h2 (`atxHeading` with depth 2) in a changeset markdown
+ * file matches a known category heading from the category system. When an
+ * unrecognized heading is found, the error detail lists all valid headings.
+ *
+ * @remarks
+ * Heading comparison is case-insensitive. The set of valid headings is provided
+ * by `allHeadings()` and `isValidHeading()` from the category system
+ * (`src/categories/index.ts`). This rule inspects `atxHeading` micromark
+ * tokens and extracts their text via the {@link getHeadingText} utility.
+ *
+ * This rule mirrors the remark-lint rule `remarkLintRequiredSections` but uses
+ * markdownlint's micromark token API so it can run inside markdownlint-cli2 and
+ * the VS Code markdownlint extension.
+ *
+ * @example
+ * ```json
+ * {
+ *   "changeset-required-sections": true
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/savvy-web/changesets/blob/main/docs/rules/CSH002.md | CSH002 rule documentation}
+ * @see `src/remark/rules/required-sections.ts` for the corresponding remark-lint rule
  *
- * Validates that all h2 headings in changeset files match a known
- * category heading from the category system. Reports unrecognized
- * headings with the list of valid options.
+ * @public
  */
 export declare const RequiredSectionsRule: Rule;
 
@@ -60,10 +142,34 @@ declare const SilkChangesetsRules: Rule[];
 export default SilkChangesetsRules;
 
 /**
- * markdownlint rule: changeset-uncategorized-content (CSH004)
+ * markdownlint rule: `changeset-uncategorized-content` (CSH004).
+ *
+ * Detects content that appears before the first h2 heading in a changeset
+ * markdown file. All substantive content must be placed under a categorized
+ * section (`## heading`).
  *
- * Detects content that appears before the first h2 heading in a changeset file.
- * All content must be placed under a categorized section (## heading).
+ * @remarks
+ * The rule iterates over the top-level micromark token stream and stops at the
+ * first `atxHeading` with depth 2. Any token encountered before that heading
+ * that is not a `lineEnding`, `lineEndingBlank`, or `htmlFlow` (HTML comments)
+ * triggers an error. This ensures that changeset content is always grouped
+ * under a recognized category heading.
+ *
+ * This rule mirrors the remark-lint rule `remarkLintUncategorizedContent` but
+ * uses markdownlint's micromark token API so it can run inside
+ * markdownlint-cli2 and the VS Code markdownlint extension.
+ *
+ * @example
+ * ```json
+ * {
+ *   "changeset-uncategorized-content": true
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/savvy-web/changesets/blob/main/docs/rules/CSH004.md | CSH004 rule documentation}
+ * @see `src/remark/rules/uncategorized-content.ts` for the corresponding remark-lint rule
+ *
+ * @public
  */
 export declare const UncategorizedContentRule: Rule;
 

package/esm/markdownlint.js

@@ -67,6 +67,155 @@ const ContentStructureRule = {
         }
     }
 };
+const EM_DASH = "\u2014";
+const VALID_TYPES = new Set([
+    "dependency",
+    "devDependency",
+    "peerDependency",
+    "optionalDependency",
+    "workspace",
+    "config"
+]);
+const VALID_ACTIONS = new Set([
+    "added",
+    "updated",
+    "removed"
+]);
+const EXPECTED_HEADERS = [
+    "dependency",
+    "type",
+    "action",
+    "from",
+    "to"
+];
+const VERSION_RE = /^(\u2014|[~^]?\d+\.\d+\.\d+(?:[-+.][\w.+-]*)?)$/;
+function getCellText(cell) {
+    const content = cell.children.find((c)=>"tableContent" === c.type);
+    return content ? content.text.trim() : "";
+}
+function getRowCells(row) {
+    return row.children.filter((c)=>"tableHeader" === c.type || "tableData" === c.type).map(getCellText);
+}
+const DependencyTableFormatRule = {
+    names: [
+        "changeset-dependency-table-format",
+        "CSH005"
+    ],
+    description: "Dependencies section must contain a valid dependency table",
+    tags: [
+        "changeset"
+    ],
+    parser: "micromark",
+    function: function(params, onError) {
+        const tokens = params.parsers.micromark.tokens;
+        for(let i = 0; i < tokens.length; i++){
+            const token = tokens[i];
+            if ("atxHeading" !== token.type) continue;
+            if (2 !== getHeadingLevel(token)) continue;
+            if ("dependencies" !== getHeadingText(token).toLowerCase()) continue;
+            const headingLine = token.startLine;
+            let tableToken = null;
+            for(let j = i + 1; j < tokens.length; j++){
+                const next = tokens[j];
+                if ("lineEnding" !== next.type && "lineEndingBlank" !== next.type) {
+                    if ("atxHeading" === next.type) break;
+                    if ("table" === next.type) tableToken = next;
+                    break;
+                }
+            }
+            if (null === tableToken) {
+                onError({
+                    lineNumber: headingLine,
+                    detail: `Dependencies section must contain a table, not a list or paragraph. See: ${RULE_DOCS.CSH005}`
+                });
+                continue;
+            }
+            const tableHead = tableToken.children.find((c)=>"tableHead" === c.type);
+            if (!tableHead) {
+                onError({
+                    lineNumber: tableToken.startLine,
+                    detail: `Dependencies table is missing a header row. See: ${RULE_DOCS.CSH005}`
+                });
+                continue;
+            }
+            const headerRow = tableHead.children.find((c)=>"tableRow" === c.type);
+            if (!headerRow) {
+                onError({
+                    lineNumber: tableToken.startLine,
+                    detail: `Dependencies table is missing a header row. See: ${RULE_DOCS.CSH005}`
+                });
+                continue;
+            }
+            const headers = getRowCells(headerRow).map((h)=>h.toLowerCase());
+            if (headers.length !== EXPECTED_HEADERS.length || !headers.every((h, idx)=>h === EXPECTED_HEADERS[idx])) {
+                onError({
+                    lineNumber: headerRow.startLine,
+                    detail: `Dependencies table must have columns: Dependency, Type, Action, From, To. Got: ${headers.join(", ")}. See: ${RULE_DOCS.CSH005}`
+                });
+                continue;
+            }
+            const tableBody = tableToken.children.find((c)=>"tableBody" === c.type);
+            if (!tableBody) {
+                onError({
+                    lineNumber: tableToken.startLine,
+                    detail: `Dependencies table must have at least one data row. See: ${RULE_DOCS.CSH005}`
+                });
+                continue;
+            }
+            const dataRows = tableBody.children.filter((c)=>"tableRow" === c.type);
+            if (0 === dataRows.length) {
+                onError({
+                    lineNumber: tableToken.startLine,
+                    detail: `Dependencies table must have at least one data row. See: ${RULE_DOCS.CSH005}`
+                });
+                continue;
+            }
+            for (const row of dataRows){
+                const cells = getRowCells(row);
+                if (cells.length < 5) {
+                    onError({
+                        lineNumber: row.startLine,
+                        detail: `Dependencies table row has too few columns (expected 5, got ${cells.length}). See: ${RULE_DOCS.CSH005}`
+                    });
+                    continue;
+                }
+                const [dependency, type, action, from, to] = cells;
+                if (!dependency) onError({
+                    lineNumber: row.startLine,
+                    detail: `Dependencies table row has an empty 'Dependency' cell. See: ${RULE_DOCS.CSH005}`
+                });
+                if (!VALID_TYPES.has(type)) onError({
+                    lineNumber: row.startLine,
+                    detail: `Invalid dependency type '${type}'. Valid types are: ${[
+                        ...VALID_TYPES
+                    ].join(", ")}. See: ${RULE_DOCS.CSH005}`
+                });
+                if (!VALID_ACTIONS.has(action)) onError({
+                    lineNumber: row.startLine,
+                    detail: `Invalid dependency action '${action}'. Valid actions are: ${[
+                        ...VALID_ACTIONS
+                    ].join(", ")}. See: ${RULE_DOCS.CSH005}`
+                });
+                if (from && !VERSION_RE.test(from)) onError({
+                    lineNumber: row.startLine,
+                    detail: `Invalid 'from' value '${from}'. Must be a semver string or em dash (\u2014). See: ${RULE_DOCS.CSH005}`
+                });
+                if (to && !VERSION_RE.test(to)) onError({
+                    lineNumber: row.startLine,
+                    detail: `Invalid 'to' value '${to}'. Must be a semver string or em dash (\u2014). See: ${RULE_DOCS.CSH005}`
+                });
+                if ("added" === action && from !== EM_DASH) onError({
+                    lineNumber: row.startLine,
+                    detail: `'from' must be '\u2014' when action is 'added' (got '${from}'). See: ${RULE_DOCS.CSH005}`
+                });
+                if ("removed" === action && to !== EM_DASH) onError({
+                    lineNumber: row.startLine,
+                    detail: `'to' must be '\u2014' when action is 'removed' (got '${to}'). See: ${RULE_DOCS.CSH005}`
+                });
+            }
+        }
+    }
+};
 const HeadingHierarchyRule = {
     names: [
         "changeset-heading-hierarchy",
@@ -146,8 +295,9 @@ const SilkChangesetsRules = [
     HeadingHierarchyRule,
     RequiredSectionsRule,
     ContentStructureRule,
-    UncategorizedContentRule
+    UncategorizedContentRule,
+    DependencyTableFormatRule
 ];
 const markdownlint = SilkChangesetsRules;
 export default markdownlint;
-export { ContentStructureRule, HeadingHierarchyRule, RequiredSectionsRule, UncategorizedContentRule };
+export { ContentStructureRule, DependencyTableFormatRule, HeadingHierarchyRule, RequiredSectionsRule, UncategorizedContentRule };

package/esm/remark.d.ts

@@ -1,7 +1,54 @@
 /**
- * Consolidated remark plugins for changeset validation and CHANGELOG transformation.
+ * \@savvy-web/changesets/remark
  *
- * Re-exports all lint rules and transform plugins from a single entry point.
+ * Remark plugins for changeset validation and CHANGELOG transformation.
+ *
+ * This entry point re-exports all lint rules, transform plugins, and presets
+ * from a single import path. The exports are organized into three groups:
+ *
+ * **Lint rules** validate changeset markdown structure before changelog generation:
+ * - {@link HeadingHierarchyRule} (CSH001) -- heading depth and ordering
+ * - {@link RequiredSectionsRule} (CSH002) -- recognized section headings
+ * - {@link ContentStructureRule} (CSH003) -- non-empty sections, code fences, list items
+ * - {@link UncategorizedContentRule} (CSH004) -- content before the first heading
+ * - {@link DependencyTableFormatRule} (CSH005) -- dependency table schema compliance
+ *
+ * **Transform plugins** normalize and clean up generated CHANGELOG markdown:
+ * - {@link AggregateDependencyTablesPlugin} -- merge duplicate dependency sections
+ * - {@link MergeSectionsPlugin} -- merge duplicate h3 section headings
+ * - {@link ReorderSectionsPlugin} -- sort sections by category priority
+ * - {@link DeduplicateItemsPlugin} -- remove duplicate list items
+ * - {@link ContributorFootnotesPlugin} -- aggregate contributor attributions
+ * - {@link IssueLinkRefsPlugin} -- convert inline issue links to reference-style
+ * - {@link NormalizeFormatPlugin} -- remove empty sections and lists
+ *
+ * **Presets** bundle related rules or plugins for convenient consumption:
+ * - {@link SilkChangesetPreset} -- all five lint rules
+ * - {@link SilkChangesetTransformPreset} -- all seven transform plugins in execution order
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   SilkChangesetPreset,
+ *   SilkChangesetTransformPreset,
+ * } from "\@savvy-web/changesets/remark";
+ * import remarkParse from "remark-parse";
+ * import remarkStringify from "remark-stringify";
+ * import { unified } from "unified";
+ *
+ * // Lint a changeset file
+ * const linter = unified().use(remarkParse);
+ * for (const rule of SilkChangesetPreset) {
+ *   linter.use(rule);
+ * }
+ *
+ * // Transform a CHANGELOG
+ * const transformer = unified().use(remarkParse);
+ * for (const plugin of SilkChangesetTransformPreset) {
+ *   transformer.use(plugin);
+ * }
+ * transformer.use(remarkStringify);
+ * ```
  *
  * @packageDocumentation
  */
@@ -10,46 +57,24 @@ import { Plugin } from 'unified';
 import { Plugin as Plugin_2 } from 'unified-lint-rule';
 import { Root } from 'mdast';
 
+export declare const AggregateDependencyTablesPlugin: Plugin<[], Root>;
+
 export declare const ContentStructureRule: Plugin_2<Root, unknown>;
 
-/**
- * Extract inline contributor attributions and aggregate them into
- * a summary paragraph at the end of each version block.
- */
 export declare const ContributorFootnotesPlugin: Plugin<[], Root>;
 
-/**
- * Remove duplicate list items within each h3 section.
- *
- * Items are compared by their plain text content. If a list becomes
- * empty after deduplication, it is removed from the tree.
- */
 export declare const DeduplicateItemsPlugin: Plugin<[], Root>;
 
+export declare const DependencyTableFormatRule: Plugin_2<Root, unknown>;
+
 export declare const HeadingHierarchyRule: Plugin_2<Root, unknown>;
 
-/**
- * Convert inline issue links to reference-style links with definitions
- * at the end of each version block.
- */
 export declare const IssueLinkRefsPlugin: Plugin<[], Root>;
 
-/**
- * Merge duplicate h3 sections within each version block.
- *
- * Groups sections by heading text (case-insensitive via `fromHeading`),
- * keeps the first occurrence, and splices content from duplicates into it.
- */
 export declare const MergeSectionsPlugin: Plugin<[], Root>;
 
-/**
- * Remove empty sections and empty lists from the document.
- */
 export declare const NormalizeFormatPlugin: Plugin<[], Root>;
 
-/**
- * Reorder h3 sections within each version block by category priority.
- */
 export declare const ReorderSectionsPlugin: Plugin<[], Root>;
 
 export declare const RequiredSectionsRule: Plugin_2<Root, unknown>;
@@ -57,37 +82,81 @@ export declare const RequiredSectionsRule: Plugin_2<Root, unknown>;
 /**
  * Preset combining all changeset lint rules for convenient consumption.
  *
+ * @remarks
+ * Includes the following rules in order:
+ *
+ * 1. {@link HeadingHierarchyRule} (CSH001) -- no h1, no depth skips
+ * 2. {@link RequiredSectionsRule} (CSH002) -- h2 headings must match a known category
+ * 3. {@link ContentStructureRule} (CSH003) -- non-empty sections, code fence languages, non-empty list items
+ * 4. {@link UncategorizedContentRule} (CSH004) -- no content before the first h2 heading
+ * 5. {@link DependencyTableFormatRule} (CSH005) -- dependency table column/value validation
+ *
+ * Rule execution order is not significant for lint rules; all rules run
+ * independently over the same AST and report warnings to the virtual file.
+ *
  * @example
  * ```typescript
  * import { SilkChangesetPreset } from "\@savvy-web/changesets/remark";
  * import remarkParse from "remark-parse";
  * import { unified } from "unified";
+ * import { read } from "to-vfile";
  *
  * const processor = unified().use(remarkParse);
  * for (const rule of SilkChangesetPreset) {
  *   processor.use(rule);
  * }
+ *
+ * const file = await read("changeset.md");
+ * const result = await processor.process(file);
+ * console.log(result.messages); // lint warnings
  * ```
  *
+ * @see {@link SilkChangesetTransformPreset} for the corresponding transform preset
+ *
  * @public
  */
-export declare const SilkChangesetPreset: readonly [Plugin_2<Root, unknown>, Plugin_2<Root, unknown>, Plugin_2<Root, unknown>, Plugin_2<Root, unknown>];
+export declare const SilkChangesetPreset: readonly [Plugin_2<Root, unknown>, Plugin_2<Root, unknown>, Plugin_2<Root, unknown>, Plugin_2<Root, unknown>, Plugin_2<Root, unknown>];
 
 /**
  * Ordered array of all transform plugins in the correct execution order.
  *
  * @remarks
- * Plugin ordering is significant:
- * 1. `MergeSectionsPlugin` -- merge duplicate h3 headings (must run before reorder)
- * 2. `ReorderSectionsPlugin` -- sort sections by category priority
- * 3. `DeduplicateItemsPlugin` -- remove duplicate list items
- * 4. `ContributorFootnotesPlugin` -- aggregate contributor attributions
- * 5. `IssueLinkRefsPlugin` -- convert inline issue links to reference-style
- * 6. `NormalizeFormatPlugin` -- final cleanup (remove empty sections/lists)
+ * Plugin ordering is significant -- each plugin may depend on the output of
+ * earlier plugins in the pipeline:
+ *
+ * 1. {@link AggregateDependencyTablesPlugin} -- merge duplicate dependency sections (must run first so downstream plugins see a single Dependencies section)
+ * 2. {@link MergeSectionsPlugin} -- merge duplicate h3 headings (must run before reorder so that priority is computed on consolidated sections)
+ * 3. {@link ReorderSectionsPlugin} -- sort sections by category priority (Breaking Changes first, Other last)
+ * 4. {@link DeduplicateItemsPlugin} -- remove duplicate list items within each section
+ * 5. {@link ContributorFootnotesPlugin} -- extract inline `Thanks \@user!` attributions and aggregate them into a summary paragraph per version block
+ * 6. {@link IssueLinkRefsPlugin} -- convert inline `[#N](url)` links to reference-style `[#N]` with definitions at the end of each version block
+ * 7. {@link NormalizeFormatPlugin} -- final cleanup removing empty sections and empty lists
+ *
+ * @example
+ * ```typescript
+ * import { SilkChangesetTransformPreset } from "\@savvy-web/changesets/remark";
+ * import remarkGfm from "remark-gfm";
+ * import remarkParse from "remark-parse";
+ * import remarkStringify from "remark-stringify";
+ * import { unified } from "unified";
+ * import { read } from "to-vfile";
+ *
+ * const processor = unified().use(remarkParse).use(remarkGfm);
+ * for (const plugin of SilkChangesetTransformPreset) {
+ *   processor.use(plugin);
+ * }
+ * processor.use(remarkStringify);
+ *
+ * const file = await read("CHANGELOG.md");
+ * const result = await processor.process(file);
+ * console.log(String(result));
+ * ```
+ *
+ * @see {@link SilkChangesetPreset} for the corresponding lint preset
  *
  * @public
  */
-export declare const SilkChangesetTransformPreset: readonly [Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>];
+export declare const SilkChangesetTransformPreset: readonly [Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>];
 
 export declare const UncategorizedContentRule: Plugin_2<Root, unknown>;