@savvy-web/changesets 0.3.0 → 0.4.0

package/README.md

@@ -14,11 +14,12 @@ Custom changelog formatter and markdown processing pipeline for the Silk Suite.
 - **GitHub integration** -- Automatic PR links, commit references, and contributor attribution
 - **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
@@ -64,6 +65,7 @@ Added a new authentication system with OAuth2 support.
 - [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
 

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,7 +863,7 @@ 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([
@@ -869,7 +876,7 @@ var __webpack_exports__ = {};
     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)", node);
+            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) {
@@ -1228,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/markdownlint.cjs

@@ -30,6 +30,13 @@ __webpack_require__.d(__webpack_exports__, {
     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;
@@ -64,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){
@@ -73,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){
@@ -91,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}`
                 });
             }
         }
@@ -115,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;
         }
@@ -272,7 +279,7 @@ 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}`
             });
         }
     }
@@ -294,7 +301,7 @@ const UncategorizedContentRule = {
             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)"
+                    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}`
                 });
             }
         }

package/cjs/remark.cjs

@@ -474,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;
     });
 });
@@ -500,7 +507,7 @@ 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([
@@ -513,7 +520,7 @@ function isContentNode(node) {
 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)", node);
+        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 = [

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/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,7 +29,7 @@ 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([
@@ -41,7 +42,7 @@ function isContentNode(node) {
 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)", node);
+        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) {

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";
@@ -92,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;
 }
@@ -156,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({
@@ -248,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,
@@ -759,7 +785,7 @@ const rootCommand = Command.make("savvy-changesets").pipe(Command.withSubcommand
 ]));
 const cli = Command.run(rootCommand, {
     name: "savvy-changesets",
-    version: "0.3.0"
+    version: "0.4.0"
 });
 function runCli() {
     const main = Effect.suspend(()=>cli(process.argv)).pipe(Effect.provide(NodeContext.layer));

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.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,7 +114,7 @@ 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}`
             });
         }
     }
@@ -135,7 +136,7 @@ const UncategorizedContentRule = {
             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)"
+                    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}`
                 });
             }
         }

package/package.json

@@ -1,98 +1,98 @@
 {
-	"name": "@savvy-web/changesets",
-	"version": "0.3.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.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"
+  ]
+}