@savvy-web/changesets 0.2.1 → 0.4.0

package/README.md

@@ -2,24 +2,24 @@
 
 [![npm version][npm-badge]][npm-url]
 [![License: MIT][license-badge]][license-url]
+[![Node.js >= 24][node-badge]][node-url]
 
 Custom changelog formatter and markdown processing pipeline for the Silk Suite. Replaces the default `@changesets/cli/changelog` formatter with a three-layer architecture that validates changeset files, formats structured changelog entries, and post-processes the generated CHANGELOG.md.
 
 ## Features
 
-- **Section-aware changesets** -- Use h2 headings in changeset files to categorize changes (Features, Bug Fixes, Breaking Changes, etc.)
+- **Section-aware changesets** -- Categorize changes with h2 headings (Features, Bug Fixes, Breaking Changes, etc.)
 - **Three-layer pipeline** -- Pre-validation (remark-lint), changelog formatting (Changesets API), and post-processing (remark-transform)
-- **13 section categories** -- Consistent categorization with priority-based ordering across all layers
-- **CLI tooling** -- `savvy-changesets` binary with init, lint, transform, check, and version subcommands for CI and local use
+- **CLI tooling** -- `savvy-changesets` binary with init, lint, check, transform, and version subcommands
 - **GitHub integration** -- Automatic PR links, commit references, and contributor attribution
-- **Version file syncing** -- Bump version fields in additional JSON files (beyond `package.json`) using glob patterns and JSONPath expressions
-- **Remark plugins** -- Lint rules and transform plugins via `@savvy-web/changesets/remark`
-- **markdownlint rules** -- Custom rules compatible with [markdownlint-cli2](https://www.npmjs.com/package/markdownlint-cli2) and the VS Code extension via `@savvy-web/changesets/markdownlint`
+- **Version file syncing** -- Bump version fields in additional JSON files using glob patterns and JSONPath expressions
+- **Editor support** -- markdownlint rules for real-time validation in VS Code and CI
+- **AI-agent-friendly errors** -- All lint and validation errors include inline fix instructions and documentation links, so AI agents can resolve issues without examining source code
 
 ## Installation
 
 ```bash
-pnpm add @savvy-web/changesets
+npm install @savvy-web/changesets -D
 ```
 
 ## Quick Start
@@ -30,7 +30,7 @@ Bootstrap your repository:
 savvy-changesets init
 ```
 
-This creates `.changeset/config.json` with auto-detected GitHub repo settings. Or configure manually:
+This creates `.changeset/config.json` with auto-detected GitHub repo settings and configures markdownlint rules. Or configure manually:
 
 ```json
 {
@@ -41,7 +41,7 @@ This creates `.changeset/config.json` with auto-detected GitHub repo settings. O
 }
 ```
 
-Write [section-aware changeset files](docs/section-aware-pipeline.md):
+Write section-aware changeset files:
 
 ```markdown
 ---
@@ -58,58 +58,14 @@ Added a new authentication system with OAuth2 support.
 - Updated integration test fixtures
 ```
 
-## Version File Syncing
-
-If your project has JSON files beyond `package.json` that contain version fields (e.g., `plugin.json`, `marketplace.json`), add `versionFiles` to your changelog options to keep them in sync during `changeset version`:
-
-```json
-{
-  "changelog": ["@savvy-web/changesets/changelog", {
-    "repo": "owner/repo",
-    "versionFiles": [
-      { "glob": "plugin.json" },
-      { "glob": ".claude-plugin/marketplace.json", "paths": ["$.metadata.version", "$.plugins[*].version"] }
-    ]
-  }]
-}
-```
-
-When `paths` is omitted it defaults to `["$.version"]`. In monorepos, each matched file inherits the version from its nearest workspace package. See [Configuration -- versionFiles](./docs/configuration.md#versionfiles-optional) for full details including supported JSONPath syntax.
-
-## markdownlint Integration
-
-Register the custom rules in your base config (e.g., `lib/configs/.markdownlint-cli2.jsonc`):
-
-```jsonc
-{
-  "customRules": [
-    "@savvy-web/changesets/markdownlint"
-  ],
-  "config": {
-    "changeset-heading-hierarchy": false,
-    "changeset-required-sections": false,
-    "changeset-content-structure": false
-  }
-}
-```
-
-Then enable the rules only for changeset files by creating `.changeset/.markdownlint.json`:
-
-```json
-{
-  "extends": "../lib/configs/.markdownlint-cli2.jsonc",
-  "default": false,
-  "changeset-heading-hierarchy": true,
-  "changeset-required-sections": true,
-  "changeset-content-structure": true,
-  "MD041": false
-}
-```
-
 ## Documentation
 
-- [Section-Aware Pipeline](./docs/section-aware-pipeline.md) -- End-to-end walkthrough of how section-aware changesets flow through the three-layer pipeline
-- [Full documentation](./docs/) -- CLI usage, API reference, configuration, and architecture
+- [Section-Aware Pipeline](./docs/section-aware-pipeline.md) -- End-to-end walkthrough of how section-aware changesets flow through the pipeline
+- [Configuration](./docs/configuration.md) -- Options, version files, markdownlint integration, CI scripts
+- [CLI Reference](./docs/cli.md) -- All commands and options
+- [API Reference](./docs/api.md) -- Classes, types, Effect services, remark plugins
+- [Architecture](./docs/architecture.md) -- Three-layer pipeline design and export map
+- [Markdownlint Rule Docs](./docs/rules/) -- Per-rule documentation with examples, fix instructions, and rationale
 
 ## License
 
@@ -119,3 +75,5 @@ MIT
 [npm-url]: https://www.npmjs.com/package/@savvy-web/changesets
 [license-badge]: https://img.shields.io/badge/License-MIT-yellow.svg
 [license-url]: https://opensource.org/licenses/MIT
+[node-badge]: https://img.shields.io/badge/node-%3E%3D24-brightgreen
+[node-url]: https://nodejs.org/

package/cjs/changelog.cjs

@@ -181,7 +181,7 @@ var __webpack_modules__ = {
             }
         }
         const UsernameSchema = effect__rspack_import_0.Schema.String.pipe(effect__rspack_import_0.Schema.pattern(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/, {
-            message: ()=>"Invalid GitHub username format"
+            message: ()=>'Invalid GitHub username format. Usernames must contain only alphanumeric characters and hyphens, and cannot start or end with a hyphen. Example: "octocat" or "my-user-123"'
         }));
         const IssueNumberSchema = _primitives_js__rspack_import_1.e.annotations({
             title: "IssueNumber",
@@ -192,7 +192,7 @@ var __webpack_modules__ = {
             const match = _utils_markdown_link_js__rspack_import_2.o.exec(value);
             return match?.[2] ? isValidUrl(match[2]) : false;
         }, {
-            message: ()=>"Invalid URL or markdown link format"
+            message: ()=>'Value must be a valid URL or a markdown link. Expected a plain URL (e.g., "https://github.com/owner/repo/pull/42") or a markdown link (e.g., "[#42](https://github.com/owner/repo/pull/42)")'
         }));
         const GitHubInfoSchema = effect__rspack_import_0.Schema.Struct({
             user: effect__rspack_import_0.Schema.optional(UsernameSchema),

package/cjs/index.cjs

@@ -490,7 +490,7 @@ var __webpack_modules__ = {
             }
         }
         const UsernameSchema = effect__rspack_import_0.Schema.String.pipe(effect__rspack_import_0.Schema.pattern(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/, {
-            message: ()=>"Invalid GitHub username format"
+            message: ()=>'Invalid GitHub username format. Usernames must contain only alphanumeric characters and hyphens, and cannot start or end with a hyphen. Example: "octocat" or "my-user-123"'
         }));
         const IssueNumberSchema = _primitives_js__rspack_import_1.e.annotations({
             title: "IssueNumber",
@@ -501,7 +501,7 @@ var __webpack_modules__ = {
             const match = _utils_markdown_link_js__rspack_import_2.o.exec(value);
             return match?.[2] ? isValidUrl(match[2]) : false;
         }, {
-            message: ()=>"Invalid URL or markdown link format"
+            message: ()=>'Value must be a valid URL or a markdown link. Expected a plain URL (e.g., "https://github.com/owner/repo/pull/42") or a markdown link (e.g., "[#42](https://github.com/owner/repo/pull/42)")'
         }));
         const GitHubInfoSchema = effect__rspack_import_0.Schema.Struct({
             user: effect__rspack_import_0.Schema.optional(UsernameSchema),
@@ -830,25 +830,32 @@ var __webpack_exports__ = {};
     var external_mdast_util_to_string_ = __webpack_require__("mdast-util-to-string");
     const external_unified_lint_rule_namespaceObject = require("unified-lint-rule");
     const external_unist_util_visit_namespaceObject = require("unist-util-visit");
+    const DOCS_BASE = "https://github.com/savvy-web/changesets/blob/main/docs/rules";
+    const RULE_DOCS = {
+        CSH001: `${DOCS_BASE}/CSH001.md`,
+        CSH002: `${DOCS_BASE}/CSH002.md`,
+        CSH003: `${DOCS_BASE}/CSH003.md`,
+        CSH004: `${DOCS_BASE}/CSH004.md`
+    };
     const ContentStructureRule = (0, external_unified_lint_rule_namespaceObject.lintRule)("remark-lint:changeset-content-structure", (tree, file)=>{
         (0, external_unist_util_visit_namespaceObject.visit)(tree, "heading", (node, index, parent)=>{
             if (2 !== node.depth || null == parent || null == index) return;
             const next = parent.children[index + 1];
-            if (!next || "heading" === next.type && 2 === next.depth) file.message("Empty section: heading has no content before the next section or end of file", node);
+            if (!next || "heading" === next.type && 2 === next.depth) file.message(`Empty section: heading has no content before the next section or end of file. Add a list of changes (e.g., "- Added feature X") under this heading, or remove the empty heading. See: ${RULE_DOCS.CSH003}`, node);
         });
         (0, external_unist_util_visit_namespaceObject.visit)(tree, "code", (node)=>{
-            if (!node.lang) file.message("Code block is missing a language identifier", node);
+            if (!node.lang) file.message(`Code block is missing a language identifier. Add a language after the opening fence (e.g., \`\`\`ts, \`\`\`json, \`\`\`bash). See: ${RULE_DOCS.CSH003}`, node);
         });
         (0, external_unist_util_visit_namespaceObject.visit)(tree, "listItem", (node)=>{
             const text = (0, external_mdast_util_to_string_.toString)(node).trim();
-            if (!text) file.message("Empty list item", node);
+            if (!text) file.message(`Empty list item. Each list item must contain descriptive text (e.g., "- Fixed login timeout issue"). See: ${RULE_DOCS.CSH003}`, node);
         });
     });
     const HeadingHierarchyRule = (0, external_unified_lint_rule_namespaceObject.lintRule)("remark-lint:changeset-heading-hierarchy", (tree, file)=>{
         let prevDepth = 0;
         (0, external_unist_util_visit_namespaceObject.visit)(tree, "heading", (node)=>{
-            if (1 === node.depth) return void file.message("h1 headings are not allowed in changeset files", node);
-            if (prevDepth > 0 && node.depth > prevDepth + 1) file.message(`Heading level skipped: expected h${prevDepth + 1} or lower, found h${node.depth}`, node);
+            if (1 === node.depth) return void file.message(`h1 headings are not allowed in changeset files. Use h2 (##) for top-level sections like "## Features" or "## Bug Fixes". h1 is reserved for the version title generated by the changelog formatter. See: ${RULE_DOCS.CSH001}`, node);
+            if (prevDepth > 0 && node.depth > prevDepth + 1) file.message(`Heading level skipped: expected h${prevDepth + 1} or lower, found h${node.depth}. Headings must increase sequentially (h2 → h3 → h4). Add the missing intermediate level or reduce this heading's depth. See: ${RULE_DOCS.CSH001}`, node);
             prevDepth = node.depth;
         });
     });
@@ -856,9 +863,22 @@ var __webpack_exports__ = {};
         (0, external_unist_util_visit_namespaceObject.visit)(tree, "heading", (node)=>{
             if (2 !== node.depth) return;
             const text = (0, external_mdast_util_to_string_.toString)(node);
-            if (!(0, categories.Lr)(text)) file.message(`Unknown section "${text}". Valid sections: ${(0, categories.Rr)().join(", ")}`, node);
+            if (!(0, categories.Lr)(text)) file.message(`Unknown section "${text}". Valid h2 headings are: ${(0, categories.Rr)().join(", ")}. Heading comparison is case-insensitive. See: ${RULE_DOCS.CSH002}`, node);
         });
     });
+    const IGNORED_TYPES = new Set([
+        "html"
+    ]);
+    function isContentNode(node) {
+        if ("heading" === node.type) return false;
+        return !IGNORED_TYPES.has(node.type);
+    }
+    const UncategorizedContentRule = (0, external_unified_lint_rule_namespaceObject.lintRule)("remark-lint:changeset-uncategorized-content", (tree, file)=>{
+        for (const node of tree.children){
+            if ("heading" === node.type && 2 === node.depth) break;
+            if (isContentNode(node)) file.message(`Content must be placed under a category heading (## heading). Move this content under an appropriate section like "## Features" or "## Bug Fixes". If it doesn't fit an existing category, use "## Other". See: ${RULE_DOCS.CSH004}`, node);
+        }
+    });
     function stripFrontmatter(content) {
         return content.replace(/^---\n[\s\S]*?\n---\n?/, "");
     }
@@ -869,7 +889,7 @@ var __webpack_exports__ = {};
         }
         static validateContent(content, filePath = "<input>") {
             const body = stripFrontmatter(content);
-            const processor = (0, external_unified_.unified)().use(external_remark_parse_default()).use(external_remark_stringify_default()).use(HeadingHierarchyRule).use(RequiredSectionsRule).use(ContentStructureRule);
+            const processor = (0, external_unified_.unified)().use(external_remark_parse_default()).use(external_remark_stringify_default()).use(HeadingHierarchyRule).use(RequiredSectionsRule).use(ContentStructureRule).use(UncategorizedContentRule);
             const file = processor.processSync(body);
             return file.messages.map((msg)=>({
                     file: filePath,
@@ -1215,14 +1235,14 @@ var __webpack_exports__ = {};
         description: external_effect_.Schema.String
     });
     const CommitHashSchema = external_effect_.Schema.String.pipe(external_effect_.Schema.pattern(/^[a-f0-9]{7,}$/, {
-        message: ()=>"Commit hash must be at least 7 hexadecimal characters"
+        message: ()=>'Commit hash must be 7 or more lowercase hexadecimal characters (0-9, a-f). Example: "a1b2c3d" or a full 40-character SHA like "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2". Uppercase letters are not allowed'
     }));
     const VersionTypeSchema = external_effect_.Schema.Literal("major", "minor", "patch", "none");
     var primitives = __webpack_require__("./src/schemas/primitives.ts");
     const ChangesetSummarySchema = external_effect_.Schema.String.pipe(external_effect_.Schema.minLength(1, {
-        message: ()=>"Changeset summary cannot be empty"
+        message: ()=>'Changeset summary cannot be empty. Provide a 1-1000 character description of the change (e.g., "Fix authentication timeout in login flow")'
     }), external_effect_.Schema.maxLength(1000, {
-        message: ()=>"Changeset summary is too long"
+        message: ()=>"Changeset summary exceeds the 1000 character limit. Shorten the summary to at most 1000 characters — use the changeset body for additional details"
     }));
     const ChangesetSchema = external_effect_.Schema.Struct({
         summary: ChangesetSummarySchema,

package/cjs/index.d.cts

@@ -256,9 +256,9 @@ export declare interface Changeset extends Schema.Schema.Type<typeof ChangesetSc
 /**
  * Static class for linting changeset files.
  *
- * Runs the three remark-lint rules (heading-hierarchy, required-sections,
- * content-structure) against changeset markdown and returns structured
- * diagnostic messages.
+ * Runs the four remark-lint rules (heading-hierarchy, required-sections,
+ * content-structure, uncategorized-content) against changeset markdown
+ * and returns structured diagnostic messages.
  *
  * @example
  * ```typescript

package/cjs/markdownlint.cjs

@@ -26,9 +26,17 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     ContentStructureRule: ()=>ContentStructureRule,
     HeadingHierarchyRule: ()=>HeadingHierarchyRule,
+    UncategorizedContentRule: ()=>UncategorizedContentRule,
     default: ()=>markdownlint,
     RequiredSectionsRule: ()=>RequiredSectionsRule
 });
+const DOCS_BASE = "https://github.com/savvy-web/changesets/blob/main/docs/rules";
+const RULE_DOCS = {
+    CSH001: `${DOCS_BASE}/CSH001.md`,
+    CSH002: `${DOCS_BASE}/CSH002.md`,
+    CSH003: `${DOCS_BASE}/CSH003.md`,
+    CSH004: `${DOCS_BASE}/CSH004.md`
+};
 function getHeadingLevel(heading) {
     const sequence = heading.children.find((c)=>"atxHeadingSequence" === c.type);
     return sequence ? sequence.text.length : 0;
@@ -63,7 +71,7 @@ const ContentStructureRule = {
             const nextIdx = i + 1 < h2Indices.length ? h2Indices[i + 1] : tokens.length;
             if (!hasContentBetween(tokens, currentIdx, nextIdx)) onError({
                 lineNumber: tokens[currentIdx].startLine,
-                detail: "Empty section: heading has no content before the next section or end of file"
+                detail: `Empty section: heading has no content before the next section or end of file. Add a list of changes (e.g., "- Added feature X") under this heading, or remove the empty heading. See: ${RULE_DOCS.CSH003}`
             });
         }
         for (const token of tokens){
@@ -72,7 +80,7 @@ const ContentStructureRule = {
             const hasInfo = openingFence?.children.some((c)=>"codeFencedFenceInfo" === c.type) ?? false;
             if (!hasInfo) onError({
                 lineNumber: token.startLine,
-                detail: "Code block is missing a language identifier"
+                detail: `Code block is missing a language identifier. Add a language after the opening fence (e.g., \`\`\`ts, \`\`\`json, \`\`\`bash). See: ${RULE_DOCS.CSH003}`
             });
         }
         for (const token of tokens){
@@ -90,7 +98,7 @@ const ContentStructureRule = {
                 }
                 if (!hasContent) onError({
                     lineNumber: children[i].startLine,
-                    detail: "Empty list item"
+                    detail: `Empty list item. Each list item must contain descriptive text (e.g., "- Fixed login timeout issue"). See: ${RULE_DOCS.CSH003}`
                 });
             }
         }
@@ -114,13 +122,13 @@ const HeadingHierarchyRule = {
             if (1 === depth) {
                 onError({
                     lineNumber: token.startLine,
-                    detail: "h1 headings are not allowed in changeset files"
+                    detail: `h1 headings are not allowed in changeset files. Use h2 (##) for top-level sections like "## Features" or "## Bug Fixes". h1 is reserved for the version title generated by the changelog formatter. See: ${RULE_DOCS.CSH001}`
                 });
                 continue;
             }
             if (prevDepth > 0 && depth > prevDepth + 1) onError({
                 lineNumber: token.startLine,
-                detail: `Heading level skipped: expected h${prevDepth + 1} or lower, found h${depth}`
+                detail: `Heading level skipped: expected h${prevDepth + 1} or lower, found h${depth}. Headings must increase sequentially (h2 → h3 → h4). Add the missing intermediate level or reduce this heading's depth. See: ${RULE_DOCS.CSH001}`
             });
             prevDepth = depth;
         }
@@ -271,25 +279,51 @@ const RequiredSectionsRule = {
             const text = getHeadingText(token);
             if (!isValidHeading(text)) onError({
                 lineNumber: token.startLine,
-                detail: `Unknown section "${text}". Valid sections: ${allHeadings().join(", ")}`
+                detail: `Unknown section "${text}". Valid h2 headings are: ${allHeadings().join(", ")}. Heading comparison is case-insensitive. See: ${RULE_DOCS.CSH002}`
             });
         }
     }
 };
+const UncategorizedContentRule = {
+    names: [
+        "changeset-uncategorized-content",
+        "CSH004"
+    ],
+    description: "All content must be placed under a category heading (## heading)",
+    tags: [
+        "changeset"
+    ],
+    parser: "micromark",
+    function: function(params, onError) {
+        const tokens = params.parsers.micromark.tokens;
+        for (const token of tokens){
+            if ("atxHeading" === token.type && 2 === getHeadingLevel(token)) break;
+            if ("lineEnding" !== token.type && "lineEndingBlank" !== token.type && "htmlFlow" !== token.type) {
+                if ("atxHeading" !== token.type) onError({
+                    lineNumber: token.startLine,
+                    detail: `Content must be placed under a category heading (## heading). Move this content under an appropriate section like "## Features" or "## Bug Fixes". If it doesn't fit an existing category, use "## Other". See: ${RULE_DOCS.CSH004}`
+                });
+            }
+        }
+    }
+};
 const SilkChangesetsRules = [
     HeadingHierarchyRule,
     RequiredSectionsRule,
-    ContentStructureRule
+    ContentStructureRule,
+    UncategorizedContentRule
 ];
 const markdownlint = SilkChangesetsRules;
 exports.ContentStructureRule = __webpack_exports__.ContentStructureRule;
 exports.HeadingHierarchyRule = __webpack_exports__.HeadingHierarchyRule;
 exports.RequiredSectionsRule = __webpack_exports__.RequiredSectionsRule;
+exports.UncategorizedContentRule = __webpack_exports__.UncategorizedContentRule;
 exports["default"] = __webpack_exports__["default"];
 for(var __rspack_i in __webpack_exports__)if (-1 === [
     "ContentStructureRule",
     "HeadingHierarchyRule",
     "RequiredSectionsRule",
+    "UncategorizedContentRule",
     "default"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {

package/cjs/markdownlint.d.cts

@@ -8,6 +8,7 @@
  * - `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
  *
  * @packageDocumentation
  */
@@ -58,4 +59,12 @@ export declare const RequiredSectionsRule: Rule;
 declare const SilkChangesetsRules: Rule[];
 export default SilkChangesetsRules;
 
+/**
+ * markdownlint rule: changeset-uncategorized-content (CSH004)
+ *
+ * Detects content that appears before the first h2 heading in a changeset file.
+ * All content must be placed under a categorized section (## heading).
+ */
+export declare const UncategorizedContentRule: Rule;
+
 export { }

package/cjs/remark.cjs

@@ -24,6 +24,7 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    UncategorizedContentRule: ()=>UncategorizedContentRule,
     SilkChangesetTransformPreset: ()=>SilkChangesetTransformPreset,
     NormalizeFormatPlugin: ()=>NormalizeFormatPlugin,
     IssueLinkRefsPlugin: ()=>IssueLinkRefsPlugin,
@@ -473,25 +474,32 @@ const ReorderSectionsPlugin = ()=>(tree)=>{
         }
     };
 const external_unified_lint_rule_namespaceObject = require("unified-lint-rule");
+const DOCS_BASE = "https://github.com/savvy-web/changesets/blob/main/docs/rules";
+const RULE_DOCS = {
+    CSH001: `${DOCS_BASE}/CSH001.md`,
+    CSH002: `${DOCS_BASE}/CSH002.md`,
+    CSH003: `${DOCS_BASE}/CSH003.md`,
+    CSH004: `${DOCS_BASE}/CSH004.md`
+};
 const ContentStructureRule = (0, external_unified_lint_rule_namespaceObject.lintRule)("remark-lint:changeset-content-structure", (tree, file)=>{
     (0, external_unist_util_visit_namespaceObject.visit)(tree, "heading", (node, index, parent)=>{
         if (2 !== node.depth || null == parent || null == index) return;
         const next = parent.children[index + 1];
-        if (!next || "heading" === next.type && 2 === next.depth) file.message("Empty section: heading has no content before the next section or end of file", node);
+        if (!next || "heading" === next.type && 2 === next.depth) file.message(`Empty section: heading has no content before the next section or end of file. Add a list of changes (e.g., "- Added feature X") under this heading, or remove the empty heading. See: ${RULE_DOCS.CSH003}`, node);
     });
     (0, external_unist_util_visit_namespaceObject.visit)(tree, "code", (node)=>{
-        if (!node.lang) file.message("Code block is missing a language identifier", node);
+        if (!node.lang) file.message(`Code block is missing a language identifier. Add a language after the opening fence (e.g., \`\`\`ts, \`\`\`json, \`\`\`bash). See: ${RULE_DOCS.CSH003}`, node);
     });
     (0, external_unist_util_visit_namespaceObject.visit)(tree, "listItem", (node)=>{
         const text = (0, external_mdast_util_to_string_namespaceObject.toString)(node).trim();
-        if (!text) file.message("Empty list item", node);
+        if (!text) file.message(`Empty list item. Each list item must contain descriptive text (e.g., "- Fixed login timeout issue"). See: ${RULE_DOCS.CSH003}`, node);
     });
 });
 const HeadingHierarchyRule = (0, external_unified_lint_rule_namespaceObject.lintRule)("remark-lint:changeset-heading-hierarchy", (tree, file)=>{
     let prevDepth = 0;
     (0, external_unist_util_visit_namespaceObject.visit)(tree, "heading", (node)=>{
-        if (1 === node.depth) return void file.message("h1 headings are not allowed in changeset files", node);
-        if (prevDepth > 0 && node.depth > prevDepth + 1) file.message(`Heading level skipped: expected h${prevDepth + 1} or lower, found h${node.depth}`, node);
+        if (1 === node.depth) return void file.message(`h1 headings are not allowed in changeset files. Use h2 (##) for top-level sections like "## Features" or "## Bug Fixes". h1 is reserved for the version title generated by the changelog formatter. See: ${RULE_DOCS.CSH001}`, node);
+        if (prevDepth > 0 && node.depth > prevDepth + 1) file.message(`Heading level skipped: expected h${prevDepth + 1} or lower, found h${node.depth}. Headings must increase sequentially (h2 → h3 → h4). Add the missing intermediate level or reduce this heading's depth. See: ${RULE_DOCS.CSH001}`, node);
         prevDepth = node.depth;
     });
 });
@@ -499,13 +507,27 @@ const RequiredSectionsRule = (0, external_unified_lint_rule_namespaceObject.lint
     (0, external_unist_util_visit_namespaceObject.visit)(tree, "heading", (node)=>{
         if (2 !== node.depth) return;
         const text = (0, external_mdast_util_to_string_namespaceObject.toString)(node);
-        if (!isValidHeading(text)) file.message(`Unknown section "${text}". Valid sections: ${allHeadings().join(", ")}`, node);
+        if (!isValidHeading(text)) file.message(`Unknown section "${text}". Valid h2 headings are: ${allHeadings().join(", ")}. Heading comparison is case-insensitive. See: ${RULE_DOCS.CSH002}`, node);
     });
 });
+const IGNORED_TYPES = new Set([
+    "html"
+]);
+function isContentNode(node) {
+    if ("heading" === node.type) return false;
+    return !IGNORED_TYPES.has(node.type);
+}
+const UncategorizedContentRule = (0, external_unified_lint_rule_namespaceObject.lintRule)("remark-lint:changeset-uncategorized-content", (tree, file)=>{
+    for (const node of tree.children){
+        if ("heading" === node.type && 2 === node.depth) break;
+        if (isContentNode(node)) file.message(`Content must be placed under a category heading (## heading). Move this content under an appropriate section like "## Features" or "## Bug Fixes". If it doesn't fit an existing category, use "## Other". See: ${RULE_DOCS.CSH004}`, node);
+    }
+});
 const SilkChangesetPreset = [
     HeadingHierarchyRule,
     RequiredSectionsRule,
-    ContentStructureRule
+    ContentStructureRule,
+    UncategorizedContentRule
 ];
 const SilkChangesetTransformPreset = [
     MergeSectionsPlugin,
@@ -526,6 +548,7 @@ exports.ReorderSectionsPlugin = __webpack_exports__.ReorderSectionsPlugin;
 exports.RequiredSectionsRule = __webpack_exports__.RequiredSectionsRule;
 exports.SilkChangesetPreset = __webpack_exports__.SilkChangesetPreset;
 exports.SilkChangesetTransformPreset = __webpack_exports__.SilkChangesetTransformPreset;
+exports.UncategorizedContentRule = __webpack_exports__.UncategorizedContentRule;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
     "ContentStructureRule",
     "ContributorFootnotesPlugin",
@@ -537,7 +560,8 @@ for(var __rspack_i in __webpack_exports__)if (-1 === [
     "ReorderSectionsPlugin",
     "RequiredSectionsRule",
     "SilkChangesetPreset",
-    "SilkChangesetTransformPreset"
+    "SilkChangesetTransformPreset",
+    "UncategorizedContentRule"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/cjs/remark.d.cts

@@ -71,7 +71,7 @@ export declare const RequiredSectionsRule: Plugin_2<Root, unknown>;
  *
  * @public
  */
-export declare const SilkChangesetPreset: readonly [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>];
 
 /**
  * Ordered array of all transform plugins in the correct execution order.
@@ -89,4 +89,6 @@ export declare const SilkChangesetPreset: readonly [Plugin_2<Root, unknown>, Plu
  */
 export declare const SilkChangesetTransformPreset: readonly [Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>];
 
+export declare const UncategorizedContentRule: Plugin_2<Root, unknown>;
+
 export { }

package/esm/160.js

@@ -143,7 +143,7 @@ function isValidUrl(value) {
     }
 }
 const UsernameSchema = Schema.String.pipe(Schema.pattern(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/, {
-    message: ()=>"Invalid GitHub username format"
+    message: ()=>'Invalid GitHub username format. Usernames must contain only alphanumeric characters and hyphens, and cannot start or end with a hyphen. Example: "octocat" or "my-user-123"'
 }));
 const IssueNumberSchema = PositiveInteger.annotations({
     title: "IssueNumber",
@@ -154,7 +154,7 @@ const UrlOrMarkdownLinkSchema = Schema.String.pipe(Schema.filter((value)=>{
     const match = MARKDOWN_LINK_PATTERN.exec(value);
     return match?.[2] ? isValidUrl(match[2]) : false;
 }, {
-    message: ()=>"Invalid URL or markdown link format"
+    message: ()=>'Value must be a valid URL or a markdown link. Expected a plain URL (e.g., "https://github.com/owner/repo/pull/42") or a markdown link (e.g., "[#42](https://github.com/owner/repo/pull/42)")'
 }));
 const GitHubInfoSchema = Schema.Struct({
     user: Schema.optional(UsernameSchema),

package/esm/260.js

@@ -0,0 +1,8 @@
+const DOCS_BASE = "https://github.com/savvy-web/changesets/blob/main/docs/rules";
+const RULE_DOCS = {
+    CSH001: `${DOCS_BASE}/CSH001.md`,
+    CSH002: `${DOCS_BASE}/CSH002.md`,
+    CSH003: `${DOCS_BASE}/CSH003.md`,
+    CSH004: `${DOCS_BASE}/CSH004.md`
+};
+export { RULE_DOCS };

package/esm/273.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { unified, remark_gfm, remark_stringify, remark_parse } from "./795.js";
-import { MergeSectionsPlugin, DeduplicateItemsPlugin, IssueLinkRefsPlugin, ContentStructureRule, HeadingHierarchyRule, NormalizeFormatPlugin, ReorderSectionsPlugin, ContributorFootnotesPlugin, RequiredSectionsRule } from "./234.js";
+import { UncategorizedContentRule, MergeSectionsPlugin, DeduplicateItemsPlugin, IssueLinkRefsPlugin, ContentStructureRule, HeadingHierarchyRule, NormalizeFormatPlugin, ReorderSectionsPlugin, ContributorFootnotesPlugin, RequiredSectionsRule } from "./622.js";
 function stripFrontmatter(content) {
     return content.replace(/^---\n[\s\S]*?\n---\n?/, "");
 }
@@ -12,7 +12,7 @@ class ChangesetLinter {
     }
     static validateContent(content, filePath = "<input>") {
         const body = stripFrontmatter(content);
-        const processor = unified().use(remark_parse).use(remark_stringify).use(HeadingHierarchyRule).use(RequiredSectionsRule).use(ContentStructureRule);
+        const processor = unified().use(remark_parse).use(remark_stringify).use(HeadingHierarchyRule).use(RequiredSectionsRule).use(ContentStructureRule).use(UncategorizedContentRule);
         const file = processor.processSync(body);
         return file.messages.map((msg)=>({
                 file: filePath,

package/esm/{234.js → 622.js}

@@ -1,26 +1,27 @@
 import { lintRule } from "unified-lint-rule";
 import { SKIP, visit } from "unist-util-visit";
 import { external_mdast_util_to_string_toString } from "./689.js";
+import { RULE_DOCS } from "./260.js";
 import { isValidHeading, fromHeading, allHeadings } from "./60.js";
 const ContentStructureRule = lintRule("remark-lint:changeset-content-structure", (tree, file)=>{
     visit(tree, "heading", (node, index, parent)=>{
         if (2 !== node.depth || null == parent || null == index) return;
         const next = parent.children[index + 1];
-        if (!next || "heading" === next.type && 2 === next.depth) file.message("Empty section: heading has no content before the next section or end of file", node);
+        if (!next || "heading" === next.type && 2 === next.depth) file.message(`Empty section: heading has no content before the next section or end of file. Add a list of changes (e.g., "- Added feature X") under this heading, or remove the empty heading. See: ${RULE_DOCS.CSH003}`, node);
     });
     visit(tree, "code", (node)=>{
-        if (!node.lang) file.message("Code block is missing a language identifier", node);
+        if (!node.lang) file.message(`Code block is missing a language identifier. Add a language after the opening fence (e.g., \`\`\`ts, \`\`\`json, \`\`\`bash). See: ${RULE_DOCS.CSH003}`, node);
     });
     visit(tree, "listItem", (node)=>{
         const text = external_mdast_util_to_string_toString(node).trim();
-        if (!text) file.message("Empty list item", node);
+        if (!text) file.message(`Empty list item. Each list item must contain descriptive text (e.g., "- Fixed login timeout issue"). See: ${RULE_DOCS.CSH003}`, node);
     });
 });
 const HeadingHierarchyRule = lintRule("remark-lint:changeset-heading-hierarchy", (tree, file)=>{
     let prevDepth = 0;
     visit(tree, "heading", (node)=>{
-        if (1 === node.depth) return void file.message("h1 headings are not allowed in changeset files", node);
-        if (prevDepth > 0 && node.depth > prevDepth + 1) file.message(`Heading level skipped: expected h${prevDepth + 1} or lower, found h${node.depth}`, node);
+        if (1 === node.depth) return void file.message(`h1 headings are not allowed in changeset files. Use h2 (##) for top-level sections like "## Features" or "## Bug Fixes". h1 is reserved for the version title generated by the changelog formatter. See: ${RULE_DOCS.CSH001}`, node);
+        if (prevDepth > 0 && node.depth > prevDepth + 1) file.message(`Heading level skipped: expected h${prevDepth + 1} or lower, found h${node.depth}. Headings must increase sequentially (h2 → h3 → h4). Add the missing intermediate level or reduce this heading's depth. See: ${RULE_DOCS.CSH001}`, node);
         prevDepth = node.depth;
     });
 });
@@ -28,9 +29,22 @@ const RequiredSectionsRule = lintRule("remark-lint:changeset-required-sections",
     visit(tree, "heading", (node)=>{
         if (2 !== node.depth) return;
         const text = external_mdast_util_to_string_toString(node);
-        if (!isValidHeading(text)) file.message(`Unknown section "${text}". Valid sections: ${allHeadings().join(", ")}`, node);
+        if (!isValidHeading(text)) file.message(`Unknown section "${text}". Valid h2 headings are: ${allHeadings().join(", ")}. Heading comparison is case-insensitive. See: ${RULE_DOCS.CSH002}`, node);
     });
 });
+const IGNORED_TYPES = new Set([
+    "html"
+]);
+function isContentNode(node) {
+    if ("heading" === node.type) return false;
+    return !IGNORED_TYPES.has(node.type);
+}
+const UncategorizedContentRule = lintRule("remark-lint:changeset-uncategorized-content", (tree, file)=>{
+    for (const node of tree.children){
+        if ("heading" === node.type && 2 === node.depth) break;
+        if (isContentNode(node)) file.message(`Content must be placed under a category heading (## heading). Move this content under an appropriate section like "## Features" or "## Bug Fixes". If it doesn't fit an existing category, use "## Other". See: ${RULE_DOCS.CSH004}`, node);
+    }
+});
 function getVersionBlocks(tree) {
     const blocks = [];
     for(let i = 0; i < tree.children.length; i++){
@@ -334,4 +348,4 @@ const ReorderSectionsPlugin = ()=>(tree)=>{
             tree.children.splice(block.startIndex, blockLength, ...newChildren);
         }
     };
-export { ContentStructureRule, ContributorFootnotesPlugin, DeduplicateItemsPlugin, HeadingHierarchyRule, IssueLinkRefsPlugin, MergeSectionsPlugin, NormalizeFormatPlugin, ReorderSectionsPlugin, RequiredSectionsRule };
+export { ContentStructureRule, ContributorFootnotesPlugin, DeduplicateItemsPlugin, HeadingHierarchyRule, IssueLinkRefsPlugin, MergeSectionsPlugin, NormalizeFormatPlugin, ReorderSectionsPlugin, RequiredSectionsRule, UncategorizedContentRule };

package/esm/bin/savvy-changesets.js

@@ -2,8 +2,8 @@
 import { Args, Command, Options } from "@effect/cli";
 import { NodeContext, NodeRuntime } from "@effect/platform-node";
 import { execSync } from "node:child_process";
+import { applyEdits, modify, parse } from "jsonc-parser";
 import { findProjectRoot, getWorkspaceInfos } from "workspace-tools";
-import { parse } from "jsonc-parser";
 import { globSync } from "tinyglobby";
 import { readFileSync, ChangelogTransformer, ChangesetLinter, resolve, existsSync, relative, mkdirSync, writeFileSync, join } from "../273.js";
 import { VersionFilesSchema, Schema, VersionFileError, Data, Effect } from "../795.js";
@@ -48,7 +48,8 @@ const MARKDOWNLINT_CONFIG_PATHS = [
 const RULE_NAMES = [
     "changeset-heading-hierarchy",
     "changeset-required-sections",
-    "changeset-content-structure"
+    "changeset-content-structure",
+    "changeset-uncategorized-content"
 ];
 const DEFAULT_CONFIG = {
     $schema: "https://unpkg.com/@changesets/config@3.1.1/schema.json",
@@ -91,9 +92,10 @@ function detectGitHubRepo(cwd) {
     } catch  {}
     return null;
 }
-function stripJsoncComments(text) {
-    return text.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
-}
+const JSONC_FORMAT = {
+    tabSize: 1,
+    insertSpaces: false
+};
 function resolveWorkspaceRoot(cwd) {
     return findProjectRoot(cwd) ?? cwd;
 }
@@ -155,13 +157,38 @@ function handleBaseMarkdownlint(root) {
             const foundPath = findMarkdownlintConfig(root);
             if (!foundPath) return `Warning: no markdownlint config found (checked ${MARKDOWNLINT_CONFIG_PATHS.join(", ")})`;
             const fullPath = join(root, foundPath);
-            const raw = readFileSync(fullPath, "utf-8");
-            const parsed = JSON.parse(stripJsoncComments(raw));
-            if (!Array.isArray(parsed.customRules)) parsed.customRules = [];
-            if (!parsed.customRules.includes(CUSTOM_RULES_ENTRY)) parsed.customRules.push(CUSTOM_RULES_ENTRY);
-            if ("object" != typeof parsed.config || null === parsed.config) parsed.config = {};
-            for (const rule of RULE_NAMES)if (!(rule in parsed.config)) parsed.config[rule] = false;
-            writeFileSync(fullPath, `${JSON.stringify(parsed, null, "\t")}\n`);
+            let text = readFileSync(fullPath, "utf-8");
+            const parsed = parse(text);
+            if (!Array.isArray(parsed.customRules) || !parsed.customRules.includes(CUSTOM_RULES_ENTRY)) {
+                const edits = modify(text, [
+                    "customRules",
+                    -1
+                ], CUSTOM_RULES_ENTRY, {
+                    formattingOptions: JSONC_FORMAT,
+                    isArrayInsertion: true
+                });
+                text = applyEdits(text, edits);
+            }
+            const currentConfig = parse(text).config;
+            if ("object" != typeof currentConfig || null === currentConfig) {
+                const edits = modify(text, [
+                    "config"
+                ], {}, {
+                    formattingOptions: JSONC_FORMAT
+                });
+                text = applyEdits(text, edits);
+            }
+            const config = parse(text).config;
+            for (const rule of RULE_NAMES)if (!(rule in config)) {
+                const edits = modify(text, [
+                    "config",
+                    rule
+                ], false, {
+                    formattingOptions: JSONC_FORMAT
+                });
+                text = applyEdits(text, edits);
+            }
+            writeFileSync(fullPath, text);
             return `Updated ${foundPath}`;
         },
         catch: (error)=>new InitError({
@@ -247,7 +274,7 @@ function checkBaseMarkdownlint(root) {
     ];
     try {
         const raw = readFileSync(join(root, foundPath), "utf-8");
-        const parsed = JSON.parse(stripJsoncComments(raw));
+        const parsed = parse(raw);
         const issues = [];
         if (!Array.isArray(parsed.customRules) || !parsed.customRules.includes(CUSTOM_RULES_ENTRY)) issues.push({
             file: foundPath,
@@ -758,7 +785,7 @@ const rootCommand = Command.make("savvy-changesets").pipe(Command.withSubcommand
 ]));
 const cli = Command.run(rootCommand, {
     name: "savvy-changesets",
-    version: "0.2.1"
+    version: "0.4.0"
 });
 function runCli() {
     const main = Effect.suspend(()=>cli(process.argv)).pipe(Effect.provide(NodeContext.layer));

package/esm/index.d.ts

@@ -256,9 +256,9 @@ export declare interface Changeset extends Schema.Schema.Type<typeof ChangesetSc
 /**
  * Static class for linting changeset files.
  *
- * Runs the three remark-lint rules (heading-hierarchy, required-sections,
- * content-structure) against changeset markdown and returns structured
- * diagnostic messages.
+ * Runs the four remark-lint rules (heading-hierarchy, required-sections,
+ * content-structure, uncategorized-content) against changeset markdown
+ * and returns structured diagnostic messages.
  *
  * @example
  * ```typescript

package/esm/index.js

@@ -48,13 +48,13 @@ const SectionCategorySchema = Schema.Struct({
     description: Schema.String
 });
 const CommitHashSchema = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{7,}$/, {
-    message: ()=>"Commit hash must be at least 7 hexadecimal characters"
+    message: ()=>'Commit hash must be 7 or more lowercase hexadecimal characters (0-9, a-f). Example: "a1b2c3d" or a full 40-character SHA like "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2". Uppercase letters are not allowed'
 }));
 const VersionTypeSchema = Schema.Literal("major", "minor", "patch", "none");
 const ChangesetSummarySchema = Schema.String.pipe(Schema.minLength(1, {
-    message: ()=>"Changeset summary cannot be empty"
+    message: ()=>'Changeset summary cannot be empty. Provide a 1-1000 character description of the change (e.g., "Fix authentication timeout in login flow")'
 }), Schema.maxLength(1000, {
-    message: ()=>"Changeset summary is too long"
+    message: ()=>"Changeset summary exceeds the 1000 character limit. Shorten the summary to at most 1000 characters — use the changeset body for additional details"
 }));
 const ChangesetSchema = Schema.Struct({
     summary: ChangesetSummarySchema,

package/esm/markdownlint.d.ts

@@ -8,6 +8,7 @@
  * - `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
  *
  * @packageDocumentation
  */
@@ -58,4 +59,12 @@ export declare const RequiredSectionsRule: Rule;
 declare const SilkChangesetsRules: Rule[];
 export default SilkChangesetsRules;
 
+/**
+ * markdownlint rule: changeset-uncategorized-content (CSH004)
+ *
+ * Detects content that appears before the first h2 heading in a changeset file.
+ * All content must be placed under a categorized section (## heading).
+ */
+export declare const UncategorizedContentRule: Rule;
+
 export { }

package/esm/markdownlint.js

@@ -1,3 +1,4 @@
+import { RULE_DOCS } from "./260.js";
 import { isValidHeading, allHeadings } from "./60.js";
 function getHeadingLevel(heading) {
     const sequence = heading.children.find((c)=>"atxHeadingSequence" === c.type);
@@ -33,7 +34,7 @@ const ContentStructureRule = {
             const nextIdx = i + 1 < h2Indices.length ? h2Indices[i + 1] : tokens.length;
             if (!hasContentBetween(tokens, currentIdx, nextIdx)) onError({
                 lineNumber: tokens[currentIdx].startLine,
-                detail: "Empty section: heading has no content before the next section or end of file"
+                detail: `Empty section: heading has no content before the next section or end of file. Add a list of changes (e.g., "- Added feature X") under this heading, or remove the empty heading. See: ${RULE_DOCS.CSH003}`
             });
         }
         for (const token of tokens){
@@ -42,7 +43,7 @@ const ContentStructureRule = {
             const hasInfo = openingFence?.children.some((c)=>"codeFencedFenceInfo" === c.type) ?? false;
             if (!hasInfo) onError({
                 lineNumber: token.startLine,
-                detail: "Code block is missing a language identifier"
+                detail: `Code block is missing a language identifier. Add a language after the opening fence (e.g., \`\`\`ts, \`\`\`json, \`\`\`bash). See: ${RULE_DOCS.CSH003}`
             });
         }
         for (const token of tokens){
@@ -60,7 +61,7 @@ const ContentStructureRule = {
                 }
                 if (!hasContent) onError({
                     lineNumber: children[i].startLine,
-                    detail: "Empty list item"
+                    detail: `Empty list item. Each list item must contain descriptive text (e.g., "- Fixed login timeout issue"). See: ${RULE_DOCS.CSH003}`
                 });
             }
         }
@@ -84,13 +85,13 @@ const HeadingHierarchyRule = {
             if (1 === depth) {
                 onError({
                     lineNumber: token.startLine,
-                    detail: "h1 headings are not allowed in changeset files"
+                    detail: `h1 headings are not allowed in changeset files. Use h2 (##) for top-level sections like "## Features" or "## Bug Fixes". h1 is reserved for the version title generated by the changelog formatter. See: ${RULE_DOCS.CSH001}`
                 });
                 continue;
             }
             if (prevDepth > 0 && depth > prevDepth + 1) onError({
                 lineNumber: token.startLine,
-                detail: `Heading level skipped: expected h${prevDepth + 1} or lower, found h${depth}`
+                detail: `Heading level skipped: expected h${prevDepth + 1} or lower, found h${depth}. Headings must increase sequentially (h2 → h3 → h4). Add the missing intermediate level or reduce this heading's depth. See: ${RULE_DOCS.CSH001}`
             });
             prevDepth = depth;
         }
@@ -113,16 +114,40 @@ const RequiredSectionsRule = {
             const text = getHeadingText(token);
             if (!isValidHeading(text)) onError({
                 lineNumber: token.startLine,
-                detail: `Unknown section "${text}". Valid sections: ${allHeadings().join(", ")}`
+                detail: `Unknown section "${text}". Valid h2 headings are: ${allHeadings().join(", ")}. Heading comparison is case-insensitive. See: ${RULE_DOCS.CSH002}`
             });
         }
     }
 };
+const UncategorizedContentRule = {
+    names: [
+        "changeset-uncategorized-content",
+        "CSH004"
+    ],
+    description: "All content must be placed under a category heading (## heading)",
+    tags: [
+        "changeset"
+    ],
+    parser: "micromark",
+    function: function(params, onError) {
+        const tokens = params.parsers.micromark.tokens;
+        for (const token of tokens){
+            if ("atxHeading" === token.type && 2 === getHeadingLevel(token)) break;
+            if ("lineEnding" !== token.type && "lineEndingBlank" !== token.type && "htmlFlow" !== token.type) {
+                if ("atxHeading" !== token.type) onError({
+                    lineNumber: token.startLine,
+                    detail: `Content must be placed under a category heading (## heading). Move this content under an appropriate section like "## Features" or "## Bug Fixes". If it doesn't fit an existing category, use "## Other". See: ${RULE_DOCS.CSH004}`
+                });
+            }
+        }
+    }
+};
 const SilkChangesetsRules = [
     HeadingHierarchyRule,
     RequiredSectionsRule,
-    ContentStructureRule
+    ContentStructureRule,
+    UncategorizedContentRule
 ];
 const markdownlint = SilkChangesetsRules;
 export default markdownlint;
-export { ContentStructureRule, HeadingHierarchyRule, RequiredSectionsRule };
+export { ContentStructureRule, HeadingHierarchyRule, RequiredSectionsRule, UncategorizedContentRule };

package/esm/remark.d.ts

@@ -71,7 +71,7 @@ export declare const RequiredSectionsRule: Plugin_2<Root, unknown>;
  *
  * @public
  */
-export declare const SilkChangesetPreset: readonly [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>];
 
 /**
  * Ordered array of all transform plugins in the correct execution order.
@@ -89,4 +89,6 @@ export declare const SilkChangesetPreset: readonly [Plugin_2<Root, unknown>, Plu
  */
 export declare const SilkChangesetTransformPreset: readonly [Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>, Plugin<[], Root>];
 
+export declare const UncategorizedContentRule: Plugin_2<Root, unknown>;
+
 export { }

package/esm/remark.js

@@ -1,8 +1,9 @@
-import { NormalizeFormatPlugin, DeduplicateItemsPlugin, MergeSectionsPlugin, ContentStructureRule, IssueLinkRefsPlugin, ReorderSectionsPlugin, HeadingHierarchyRule, ContributorFootnotesPlugin, RequiredSectionsRule } from "./234.js";
+import { UncategorizedContentRule, NormalizeFormatPlugin, DeduplicateItemsPlugin, MergeSectionsPlugin, ContentStructureRule, IssueLinkRefsPlugin, ReorderSectionsPlugin, HeadingHierarchyRule, ContributorFootnotesPlugin, RequiredSectionsRule } from "./622.js";
 const SilkChangesetPreset = [
     HeadingHierarchyRule,
     RequiredSectionsRule,
-    ContentStructureRule
+    ContentStructureRule,
+    UncategorizedContentRule
 ];
 const SilkChangesetTransformPreset = [
     MergeSectionsPlugin,
@@ -12,5 +13,5 @@ const SilkChangesetTransformPreset = [
     IssueLinkRefsPlugin,
     NormalizeFormatPlugin
 ];
-export { ContentStructureRule, ContributorFootnotesPlugin, DeduplicateItemsPlugin, HeadingHierarchyRule, IssueLinkRefsPlugin, MergeSectionsPlugin, NormalizeFormatPlugin, ReorderSectionsPlugin, RequiredSectionsRule } from "./234.js";
+export { ContentStructureRule, ContributorFootnotesPlugin, DeduplicateItemsPlugin, HeadingHierarchyRule, IssueLinkRefsPlugin, MergeSectionsPlugin, NormalizeFormatPlugin, ReorderSectionsPlugin, RequiredSectionsRule, UncategorizedContentRule } from "./622.js";
 export { SilkChangesetPreset, SilkChangesetTransformPreset };

package/package.json

@@ -1,98 +1,98 @@
 {
-	"name": "@savvy-web/changesets",
-	"version": "0.2.1",
-	"private": false,
-	"description": "Custom changelog formatter and markdown processing pipeline for the Silk Suite. Provides structured changeset sections, remark-based validation and transformation, and an Effect CLI.",
-	"keywords": [
-		"changesets",
-		"changelog",
-		"release-notes",
-		"remark",
-		"markdown",
-		"effect",
-		"silk-suite"
-	],
-	"homepage": "https://github.com/savvy-web/changesets#readme",
-	"bugs": {
-		"url": "https://github.com/savvy-web/changesets/issues"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/savvy-web/changesets.git"
-	},
-	"license": "MIT",
-	"author": {
-		"name": "C. Spencer Beggs",
-		"email": "spencer@savvyweb.systems",
-		"url": "https://savvyweb.systems"
-	},
-	"type": "module",
-	"exports": {
-		".": {
-			"types": "./esm/index.d.ts",
-			"import": "./esm/index.js",
-			"require": "./cjs/index.cjs"
-		},
-		"./changelog": {
-			"types": "./esm/changelog.d.ts",
-			"import": "./esm/changelog.js",
-			"require": "./cjs/changelog.cjs"
-		},
-		"./markdownlint": {
-			"types": "./esm/markdownlint.d.ts",
-			"import": "./esm/markdownlint.js",
-			"require": "./cjs/markdownlint.cjs"
-		},
-		"./remark": {
-			"types": "./esm/remark.d.ts",
-			"import": "./esm/remark.js",
-			"require": "./cjs/remark.cjs"
-		}
-	},
-	"bin": {
-		"savvy-changesets": "./esm/bin/savvy-changesets.js"
-	},
-	"dependencies": {
-		"@changesets/get-github-info": "^0.7.0",
-		"@effect/cli": "^0.73.2",
-		"@effect/platform": "^0.94.5",
-		"@effect/platform-node": "^0.104.1",
-		"effect": "^3.19.19",
-		"jsonc-parser": "^3.3.1",
-		"mdast-util-heading-range": "^4.0.0",
-		"mdast-util-to-string": "^4.0.0",
-		"remark-gfm": "^4.0.1",
-		"remark-parse": "^11.0.0",
-		"remark-stringify": "^11.0.0",
-		"tinyglobby": "^0.2.15",
-		"unified": "^11.0.5",
-		"unified-lint-rule": "^3.0.1",
-		"unist-util-visit": "^5.1.0",
-		"workspace-tools": "^0.41.0"
-	},
-	"peerDependencies": {
-		"@changesets/cli": "^2.29.8"
-	},
-	"peerDependenciesMeta": {
-		"@changesets/cli": {
-			"optional": false
-		}
-	},
-	"engines": {
-		"node": ">=24.0.0"
-	},
-	"scripts": {
-		"postinstall": "savvy-changesets init --check"
-	},
-	"files": [
-		"!changesets.api.json",
-		"!tsconfig.json",
-		"!tsdoc.json",
-		"LICENSE",
-		"README.md",
-		"cjs",
-		"esm",
-		"package.json",
-		"tsdoc-metadata.json"
-	]
-}
+  "name": "@savvy-web/changesets",
+  "version": "0.4.0",
+  "private": false,
+  "description": "Custom changelog formatter and markdown processing pipeline for the Silk Suite. Provides structured changeset sections, remark-based validation and transformation, and an Effect CLI.",
+  "keywords": [
+    "changesets",
+    "changelog",
+    "release-notes",
+    "remark",
+    "markdown",
+    "effect",
+    "silk-suite"
+  ],
+  "homepage": "https://github.com/savvy-web/changesets#readme",
+  "bugs": {
+    "url": "https://github.com/savvy-web/changesets/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/savvy-web/changesets.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "C. Spencer Beggs",
+    "email": "spencer@savvyweb.systems",
+    "url": "https://savvyweb.systems"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./esm/index.d.ts",
+      "import": "./esm/index.js",
+      "require": "./cjs/index.cjs"
+    },
+    "./changelog": {
+      "types": "./esm/changelog.d.ts",
+      "import": "./esm/changelog.js",
+      "require": "./cjs/changelog.cjs"
+    },
+    "./markdownlint": {
+      "types": "./esm/markdownlint.d.ts",
+      "import": "./esm/markdownlint.js",
+      "require": "./cjs/markdownlint.cjs"
+    },
+    "./remark": {
+      "types": "./esm/remark.d.ts",
+      "import": "./esm/remark.js",
+      "require": "./cjs/remark.cjs"
+    }
+  },
+  "bin": {
+    "savvy-changesets": "./esm/bin/savvy-changesets.js"
+  },
+  "dependencies": {
+    "@changesets/get-github-info": "^0.8.0",
+    "@effect/cli": "^0.73.2",
+    "@effect/platform": "^0.94.5",
+    "@effect/platform-node": "^0.104.1",
+    "effect": "^3.19.19",
+    "jsonc-parser": "^3.3.1",
+    "mdast-util-heading-range": "^4.0.0",
+    "mdast-util-to-string": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "tinyglobby": "^0.2.15",
+    "unified": "^11.0.5",
+    "unified-lint-rule": "^3.0.1",
+    "unist-util-visit": "^5.1.0",
+    "workspace-tools": "^0.41.0"
+  },
+  "peerDependencies": {
+    "@changesets/cli": "^2.30.0"
+  },
+  "peerDependenciesMeta": {
+    "@changesets/cli": {
+      "optional": false
+    }
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "postinstall": "savvy-changesets init --check"
+  },
+  "files": [
+    "!changesets.api.json",
+    "!tsconfig.json",
+    "!tsdoc.json",
+    "LICENSE",
+    "README.md",
+    "cjs",
+    "esm",
+    "package.json",
+    "tsdoc-metadata.json"
+  ]
+}