@savvy-web/silk-effects 0.6.0 → 1.0.0

package/changesets/errors.js

@@ -0,0 +1,305 @@
+import { Data } from "effect";
+
+//#region src/changesets/errors.ts
+/**
+* Tagged errors for \@savvy-web/changesets.
+*
+* @remarks
+* All errors in this module extend Effect's `Data.TaggedError`, enabling
+* type-safe error handling via `Effect.catchTag`. Each error class carries
+* structured metadata (not just a string message) so that callers can
+* programmatically inspect failure details.
+*
+* The `*Base` exports are anonymous base classes generated by
+* `Data.TaggedError()`. They are exported solely for api-extractor
+* compatibility and should not be used directly.
+*
+* @see {@link https://effect.website/docs/data-types/data#taggerror | Effect TaggedError documentation}
+*
+* @packageDocumentation
+*/
+/**
+* Base class for {@link ChangesetValidationError}.
+*
+* @privateRemarks
+* This export is required for api-extractor documentation generation.
+* Effect's Data.TaggedError creates an anonymous base class that must be
+* explicitly exported to avoid "forgotten export" warnings. Do not delete.
+*
+* @internal
+*/
+const ChangesetValidationErrorBase = Data.TaggedError("ChangesetValidationError");
+/**
+* Changeset file validation failure.
+*
+* @remarks
+* Raised when a changeset markdown file fails structural validation
+* (e.g., missing summary, invalid heading, malformed dependency table).
+* Carries an array of structured issues, each with a JSON-path pointing
+* to the problematic field and a human-readable message.
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import { ChangesetValidationError } from "@savvy-web/changesets";
+*
+* declare const program: Effect.Effect<void, ChangesetValidationError>;
+*
+* const handled = program.pipe(
+* 	Effect.catchTag("ChangesetValidationError", (err) => {
+* 		for (const issue of err.issues) {
+* 			console.error(`${issue.path}: ${issue.message}`);
+* 		}
+* 		return Effect.void;
+* 	}),
+* );
+* ```
+*
+* @see {@link ChangesetSchema} for the schema that drives validation
+*
+* @public
+*/
+var ChangesetValidationError = class extends ChangesetValidationErrorBase {
+	get message() {
+		return `${this.file ? `${this.file}: ` : ""}Changeset validation failed:\n${this.issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n")}`;
+	}
+};
+/**
+* Base class for {@link GitHubApiError}.
+*
+* @privateRemarks
+* This export is required for api-extractor documentation generation.
+* Effect's Data.TaggedError creates an anonymous base class that must be
+* explicitly exported to avoid "forgotten export" warnings. Do not delete.
+*
+* @internal
+*/
+const GitHubApiErrorBase = Data.TaggedError("GitHubApiError");
+/**
+* GitHub API request failure.
+*
+* @remarks
+* Raised when a call to the GitHub API (via `\@changesets/get-github-info`)
+* fails due to network issues, authentication errors, rate limiting, or
+* server errors. Use the {@link GitHubApiError.isRetryable | isRetryable}
+* property to determine whether a retry strategy should be applied.
+* Rate-limited responses (403/429) and server errors (5xx) are considered
+* retryable.
+*
+* @example
+* ```typescript
+* import { Effect, Schedule } from "effect";
+* import { GitHubApiError } from "@savvy-web/changesets";
+*
+* declare const program: Effect.Effect<void, GitHubApiError>;
+*
+* const withRetry = program.pipe(
+* 	Effect.catchTag("GitHubApiError", (err) => {
+* 		if (err.isRetryable) {
+* 			return Effect.retry(program, Schedule.exponential("1 second"));
+* 		}
+* 		return Effect.fail(err);
+* 	}),
+* );
+* ```
+*
+* @see {@link GitHubService} for the Effect service that may produce this error
+*
+* @public
+*/
+var GitHubApiError = class extends GitHubApiErrorBase {
+	get message() {
+		const status = this.statusCode ? ` (${this.statusCode})` : "";
+		return `GitHub API error during ${this.operation}${status}: ${this.reason}`;
+	}
+	/** Whether this error is a rate-limit response (403 or 429). */
+	get isRateLimited() {
+		return this.statusCode === 403 || this.statusCode === 429;
+	}
+	/** Whether this error is eligible for retry (server errors or rate limits). */
+	get isRetryable() {
+		return this.statusCode !== void 0 && (this.statusCode >= 500 || this.isRateLimited);
+	}
+};
+/**
+* Base class for {@link MarkdownParseError}.
+*
+* @privateRemarks
+* This export is required for api-extractor documentation generation.
+* Effect's Data.TaggedError creates an anonymous base class that must be
+* explicitly exported to avoid "forgotten export" warnings. Do not delete.
+*
+* @internal
+*/
+const MarkdownParseErrorBase = Data.TaggedError("MarkdownParseError");
+/**
+* Markdown parsing failure.
+*
+* @remarks
+* Raised when a markdown file cannot be parsed into an AST by the unified/remark
+* pipeline. Carries optional source file location information (line, column)
+* for diagnostic display.
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import { MarkdownParseError } from "@savvy-web/changesets";
+*
+* declare const program: Effect.Effect<string, MarkdownParseError>;
+*
+* const handled = program.pipe(
+* 	Effect.catchTag("MarkdownParseError", (err) => {
+* 		console.error(err.message);
+* 		return Effect.succeed("");
+* 	}),
+* );
+* ```
+*
+* @see {@link MarkdownService} for the Effect service that may produce this error
+*
+* @public
+*/
+var MarkdownParseError = class extends MarkdownParseErrorBase {
+	get message() {
+		const loc = this.line ? `:${this.line}${this.column ? `:${this.column}` : ""}` : "";
+		return `${this.source ? `${this.source}${loc}: ` : ""}Markdown parse error: ${this.reason}`;
+	}
+};
+/**
+* Base class for {@link ConfigurationError}.
+*
+* @privateRemarks
+* This export is required for api-extractor documentation generation.
+* Effect's Data.TaggedError creates an anonymous base class that must be
+* explicitly exported to avoid "forgotten export" warnings. Do not delete.
+*
+* @internal
+*/
+const ConfigurationErrorBase = Data.TaggedError("ConfigurationError");
+/**
+* Invalid or missing configuration.
+*
+* @remarks
+* Raised when the changeset configuration (typically from `.changeset/config.json`)
+* is missing required fields, has invalid values, or cannot be parsed. The `field`
+* property identifies which configuration field is problematic, and `reason`
+* provides an actionable message.
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import { ConfigurationError, validateChangesetOptions } from "@savvy-web/changesets";
+*
+* const program = validateChangesetOptions({ repo: "invalid" }).pipe(
+* 	Effect.catchTag("ConfigurationError", (err) => {
+* 		console.error(`Field "${err.field}": ${err.reason}`);
+* 		return Effect.fail(err);
+* 	}),
+* );
+* ```
+*
+* @see {@link ChangesetOptionsSchema} for the expected configuration shape
+* @see {@link validateChangesetOptions} for the validation function that produces this error
+*
+* @public
+*/
+var ConfigurationError = class extends ConfigurationErrorBase {
+	get message() {
+		return `Configuration error (${this.field}): ${this.reason}`;
+	}
+};
+/**
+* Base class for {@link VersionFileError}.
+*
+* @privateRemarks
+* This export is required for api-extractor documentation generation.
+* Effect's Data.TaggedError creates an anonymous base class that must be
+* explicitly exported to avoid "forgotten export" warnings. Do not delete.
+*
+* @internal
+*/
+const VersionFileErrorBase = Data.TaggedError("VersionFileError");
+/**
+* Version file update failure.
+*
+* @remarks
+* Raised when a JSON file targeted by the `versionFiles` configuration option
+* cannot be read, parsed, or updated at the specified JSONPath. Common causes
+* include missing files, invalid JSON, or JSONPath expressions that do not
+* match any field in the target file.
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import { VersionFileError } from "@savvy-web/changesets";
+*
+* declare const program: Effect.Effect<void, VersionFileError>;
+*
+* const handled = program.pipe(
+* 	Effect.catchTag("VersionFileError", (err) => {
+* 		console.error(`Failed to update ${err.filePath}: ${err.reason}`);
+* 		if (err.jsonPath) {
+* 			console.error(`  at JSONPath: ${err.jsonPath}`);
+* 		}
+* 		return Effect.void;
+* 	}),
+* );
+* ```
+*
+* @see {@link VersionFilesSchema} for the configuration that drives version file updates
+* @see {@link JsonPathSchema} for JSONPath expression validation
+*
+* @public
+*/
+var VersionFileError = class extends VersionFileErrorBase {
+	get message() {
+		const path = this.jsonPath ? ` at ${this.jsonPath}` : "";
+		return `Version file error (${this.filePath}${path}): ${this.reason}`;
+	}
+};
+/**
+* Base class for {@link GitError}.
+*
+* @privateRemarks
+* Effect's `Data.TaggedError` creates an anonymous base class that
+* api-extractor cannot follow without an explicit export.
+*
+* @internal
+*/
+const GitErrorBase = Data.TaggedError("GitError");
+/**
+* Git command failure.
+*
+* @remarks
+* Raised by services that shell out to `git` — `BranchAnalyzer` is the
+* canonical consumer. Captures the failing command, the working directory
+* it was invoked in, and the underlying reason (often the captured stderr
+* from the child process) so callers can produce actionable diagnostics.
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import { GitError } from "@savvy-web/changesets";
+*
+* declare const program: Effect.Effect<void, GitError>;
+*
+* const handled = program.pipe(
+*   Effect.catchTag("GitError", (err) =>
+*     Effect.logError(`git failed in ${err.cwd}: ${err.command}\n${err.reason}`)
+*   ),
+* );
+* ```
+*
+* @see {@link BranchAnalyzer} which produces these errors when computing
+*   merge bases or running `git diff`
+*
+* @public
+*/
+var GitError = class extends GitErrorBase {
+	get message() {
+		return `git command failed in ${this.cwd}: ${this.command}\n${this.reason}`;
+	}
+};
+
+//#endregion
+export { ChangesetValidationError, ChangesetValidationErrorBase, ConfigurationError, ConfigurationErrorBase, GitError, GitErrorBase, GitHubApiError, GitHubApiErrorBase, MarkdownParseError, MarkdownParseErrorBase, VersionFileError, VersionFileErrorBase };

package/changesets/index.js

@@ -0,0 +1,146 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { Categories } from "./api/categories.js";
+import { ChangesetValidationError, ChangesetValidationErrorBase, ConfigurationError, ConfigurationErrorBase, GitError, GitErrorBase, GitHubApiError, GitHubApiErrorBase, MarkdownParseError, MarkdownParseErrorBase, VersionFileError, VersionFileErrorBase } from "./errors.js";
+import { JsonPathSchema, LegacyVersionFileConfigSchema, LegacyVersionFilesSchema, VersionFileConfigSchema, VersionFilesSchema } from "./schemas/version-files.js";
+import { GlobSchema, PackageScopeSchema, PackagesRecordSchema } from "./schemas/package-scope.js";
+import { ChangesetOptionsSchema, RepoSchema } from "./schemas/options.js";
+import { GitHubLive, GitHubService, GitHubServiceBase, makeGitHubTest } from "./services/github.js";
+import { MarkdownLive, MarkdownService, MarkdownServiceBase } from "./services/markdown.js";
+import { NonEmptyString, PositiveInteger } from "./schemas/primitives.js";
+import { DependencyActionSchema, DependencyTableRowSchema, DependencyTableSchema, DependencyTableTypeSchema, VersionOrEmptySchema } from "./schemas/dependency-table.js";
+import { serializeDependencyTableToMarkdown } from "./utils/dependency-table.js";
+import { GitHubInfoSchema, IssueNumberSchema, UrlOrMarkdownLinkSchema, UsernameSchema } from "./schemas/github.js";
+import changelogFunctions from "./changelog/index.js";
+import { Changelog } from "./api/changelog.js";
+import { DependencyTable } from "./api/dependency-table.js";
+import { ContentStructureRule } from "./remark/rules/content-structure.js";
+import { HeadingHierarchyRule } from "./remark/rules/heading-hierarchy.js";
+import { RequiredSectionsRule } from "./remark/rules/required-sections.js";
+import { UncategorizedContentRule } from "./remark/rules/uncategorized-content.js";
+import { ChangesetLinter } from "./api/linter.js";
+import { ContributorFootnotesPlugin } from "./remark/plugins/contributor-footnotes.js";
+import { DeduplicateItemsPlugin } from "./remark/plugins/deduplicate-items.js";
+import { IssueLinkRefsPlugin } from "./remark/plugins/issue-link-refs.js";
+import { MergeSectionsPlugin } from "./remark/plugins/merge-sections.js";
+import { NormalizeFormatPlugin } from "./remark/plugins/normalize-format.js";
+import { ReorderSectionsPlugin } from "./remark/plugins/reorder-sections.js";
+import { ChangelogTransformer } from "./api/transformer.js";
+import { ConfigInspector, ConfigInspectorBase, ConfigInspectorLive, makeConfigInspectorTest } from "./services/config-inspector.js";
+import { BranchAnalyzer, BranchAnalyzerBase, BranchAnalyzerLive, makeBranchAnalyzerTest } from "./services/branch-analyzer.js";
+import { ChangelogService, ChangelogServiceBase } from "./services/changelog.js";
+import { WorkspaceSnapshotReader, WorkspaceSnapshotReaderBase, WorkspaceSnapshotReaderLive } from "./services/workspace-snapshot.js";
+import { SectionCategorySchema } from "./categories/types.js";
+import { CommitHashSchema, VersionTypeSchema } from "./schemas/git.js";
+import { ChangesetSchema, ChangesetSummarySchema, DependencyTypeSchema, DependencyUpdateSchema } from "./schemas/changeset.js";
+import { computeWorkspaceDependencyDiffs } from "./utils/dep-diff.js";
+import { listPublishablePackageNames } from "./utils/publishability.js";
+import { VersionFiles } from "./utils/version-files.js";
+import { gitMergeBase, snapshotFromWorktree } from "./utils/worktree-snapshot.js";
+import { ContentStructureRule as ContentStructureRule$1 } from "./markdownlint/rules/content-structure.js";
+import { DependencyTableFormatRule } from "./markdownlint/rules/dependency-table-format.js";
+import { HeadingHierarchyRule as HeadingHierarchyRule$1 } from "./markdownlint/rules/heading-hierarchy.js";
+import { RequiredSectionsRule as RequiredSectionsRule$1 } from "./markdownlint/rules/required-sections.js";
+import { UncategorizedContentRule as UncategorizedContentRule$1 } from "./markdownlint/rules/uncategorized-content.js";
+import SilkChangesetsRules from "./markdownlint/index.js";
+import { AggregateDependencyTablesPlugin } from "./remark/plugins/aggregate-dependency-tables.js";
+import { DependencyTableFormatRule as DependencyTableFormatRule$1 } from "./remark/rules/dependency-table-format.js";
+import { SilkChangesetPreset, SilkChangesetTransformPreset } from "./remark/presets.js";
+
+//#region src/changesets/index.ts
+var changesets_exports = /* @__PURE__ */ __exportAll({
+	AggregateDependencyTablesPlugin: () => AggregateDependencyTablesPlugin,
+	BranchAnalyzer: () => BranchAnalyzer,
+	BranchAnalyzerBase: () => BranchAnalyzerBase,
+	BranchAnalyzerLive: () => BranchAnalyzerLive,
+	Categories: () => Categories,
+	Changelog: () => Changelog,
+	ChangelogService: () => ChangelogService,
+	ChangelogServiceBase: () => ChangelogServiceBase,
+	ChangelogTransformer: () => ChangelogTransformer,
+	ChangesetLinter: () => ChangesetLinter,
+	ChangesetOptionsSchema: () => ChangesetOptionsSchema,
+	ChangesetSchema: () => ChangesetSchema,
+	ChangesetSummarySchema: () => ChangesetSummarySchema,
+	ChangesetValidationError: () => ChangesetValidationError,
+	ChangesetValidationErrorBase: () => ChangesetValidationErrorBase,
+	CommitHashSchema: () => CommitHashSchema,
+	ConfigInspector: () => ConfigInspector,
+	ConfigInspectorBase: () => ConfigInspectorBase,
+	ConfigInspectorLive: () => ConfigInspectorLive,
+	ConfigurationError: () => ConfigurationError,
+	ConfigurationErrorBase: () => ConfigurationErrorBase,
+	ContentStructureRule: () => ContentStructureRule,
+	ContributorFootnotesPlugin: () => ContributorFootnotesPlugin,
+	DeduplicateItemsPlugin: () => DeduplicateItemsPlugin,
+	DependencyActionSchema: () => DependencyActionSchema,
+	DependencyTable: () => DependencyTable,
+	DependencyTableFormatRule: () => DependencyTableFormatRule$1,
+	DependencyTableRowSchema: () => DependencyTableRowSchema,
+	DependencyTableSchema: () => DependencyTableSchema,
+	DependencyTableTypeSchema: () => DependencyTableTypeSchema,
+	DependencyTypeSchema: () => DependencyTypeSchema,
+	DependencyUpdateSchema: () => DependencyUpdateSchema,
+	GitError: () => GitError,
+	GitErrorBase: () => GitErrorBase,
+	GitHubApiError: () => GitHubApiError,
+	GitHubApiErrorBase: () => GitHubApiErrorBase,
+	GitHubInfoSchema: () => GitHubInfoSchema,
+	GitHubLive: () => GitHubLive,
+	GitHubService: () => GitHubService,
+	GitHubServiceBase: () => GitHubServiceBase,
+	GlobSchema: () => GlobSchema,
+	HeadingHierarchyRule: () => HeadingHierarchyRule,
+	IssueLinkRefsPlugin: () => IssueLinkRefsPlugin,
+	IssueNumberSchema: () => IssueNumberSchema,
+	JsonPathSchema: () => JsonPathSchema,
+	LegacyVersionFileConfigSchema: () => LegacyVersionFileConfigSchema,
+	LegacyVersionFilesSchema: () => LegacyVersionFilesSchema,
+	MarkdownLive: () => MarkdownLive,
+	MarkdownParseError: () => MarkdownParseError,
+	MarkdownParseErrorBase: () => MarkdownParseErrorBase,
+	MarkdownService: () => MarkdownService,
+	MarkdownServiceBase: () => MarkdownServiceBase,
+	MarkdownlintContentStructureRule: () => ContentStructureRule$1,
+	MarkdownlintDependencyTableFormatRule: () => DependencyTableFormatRule,
+	MarkdownlintHeadingHierarchyRule: () => HeadingHierarchyRule$1,
+	MarkdownlintRequiredSectionsRule: () => RequiredSectionsRule$1,
+	MarkdownlintUncategorizedContentRule: () => UncategorizedContentRule$1,
+	MergeSectionsPlugin: () => MergeSectionsPlugin,
+	NonEmptyString: () => NonEmptyString,
+	NormalizeFormatPlugin: () => NormalizeFormatPlugin,
+	PackageScopeSchema: () => PackageScopeSchema,
+	PackagesRecordSchema: () => PackagesRecordSchema,
+	PositiveInteger: () => PositiveInteger,
+	ReorderSectionsPlugin: () => ReorderSectionsPlugin,
+	RepoSchema: () => RepoSchema,
+	RequiredSectionsRule: () => RequiredSectionsRule,
+	SectionCategorySchema: () => SectionCategorySchema,
+	SilkChangesetPreset: () => SilkChangesetPreset,
+	SilkChangesetTransformPreset: () => SilkChangesetTransformPreset,
+	SilkChangesetsRules: () => SilkChangesetsRules,
+	UncategorizedContentRule: () => UncategorizedContentRule,
+	UrlOrMarkdownLinkSchema: () => UrlOrMarkdownLinkSchema,
+	UsernameSchema: () => UsernameSchema,
+	VersionFileConfigSchema: () => VersionFileConfigSchema,
+	VersionFileError: () => VersionFileError,
+	VersionFileErrorBase: () => VersionFileErrorBase,
+	VersionFiles: () => VersionFiles,
+	VersionFilesSchema: () => VersionFilesSchema,
+	VersionOrEmptySchema: () => VersionOrEmptySchema,
+	VersionTypeSchema: () => VersionTypeSchema,
+	WorkspaceSnapshotReader: () => WorkspaceSnapshotReader,
+	WorkspaceSnapshotReaderBase: () => WorkspaceSnapshotReaderBase,
+	WorkspaceSnapshotReaderLive: () => WorkspaceSnapshotReaderLive,
+	changelogFunctions: () => changelogFunctions,
+	computeWorkspaceDependencyDiffs: () => computeWorkspaceDependencyDiffs,
+	gitMergeBase: () => gitMergeBase,
+	listPublishablePackageNames: () => listPublishablePackageNames,
+	makeBranchAnalyzerTest: () => makeBranchAnalyzerTest,
+	makeConfigInspectorTest: () => makeConfigInspectorTest,
+	makeGitHubTest: () => makeGitHubTest,
+	serializeDependencyTableToMarkdown: () => serializeDependencyTableToMarkdown,
+	snapshotFromWorktree: () => snapshotFromWorktree
+});
+
+//#endregion
+export { changesets_exports };

package/changesets/markdownlint/index.js

@@ -0,0 +1,29 @@
+import { ContentStructureRule } from "./rules/content-structure.js";
+import { DependencyTableFormatRule } from "./rules/dependency-table-format.js";
+import { HeadingHierarchyRule } from "./rules/heading-hierarchy.js";
+import { RequiredSectionsRule } from "./rules/required-sections.js";
+import { UncategorizedContentRule } from "./rules/uncategorized-content.js";
+
+//#region src/changesets/markdownlint/index.ts
+/**
+* All changeset rules as an array for markdownlint-cli2 `customRules` config.
+*
+* @example
+* ```json
+* {
+*   "customRules": ["@savvy-web/changesets/markdownlint"]
+* }
+* ```
+*
+* @public
+*/
+const SilkChangesetsRules = [
+	HeadingHierarchyRule,
+	RequiredSectionsRule,
+	ContentStructureRule,
+	UncategorizedContentRule,
+	DependencyTableFormatRule
+];
+
+//#endregion
+export { SilkChangesetsRules as default };

package/changesets/markdownlint/rules/content-structure.js

@@ -0,0 +1,98 @@
+import { RULE_DOCS } from "../../constants.js";
+import { getHeadingLevel } from "./utils.js";
+
+//#region src/changesets/markdownlint/rules/content-structure.ts
+/**
+* Check whether any non-blank tokens exist between two indices in the token stream.
+*
+* @param tokens - The full micromark token array
+* @param currentIdx - Start index (exclusive)
+* @param nextIdx - End index (exclusive)
+* @returns `true` when at least one non-lineEnding token exists in the range
+*
+* @internal
+*/
+function hasContentBetween(tokens, currentIdx, nextIdx) {
+	for (let i = currentIdx + 1; i < nextIdx; i++) {
+		const token = tokens[i];
+		if (token.type !== "lineEnding" && token.type !== "lineEndingBlank") return true;
+	}
+	return false;
+}
+/**
+* markdownlint rule: `changeset-content-structure` (CSH003).
+*
+* Validates content quality inside changeset markdown files by inspecting
+* micromark tokens for three categories of structural problems:
+*
+* 1. **Empty sections** -- an `atxHeading` (h2) followed immediately by another
+*    h2 or the end of the token stream with no intervening content tokens.
+* 2. **Code blocks without a language identifier** -- a `codeFenced` token whose
+*    opening fence child lacks a `codeFencedFenceInfo` token.
+* 3. **Empty list items** -- a `listItemPrefix` token with no subsequent
+*    `content` token before the next prefix or end of list.
+*
+* @remarks
+* This rule mirrors the remark-lint rule `remarkLintContentStructure` but uses
+* markdownlint's micromark token API so it can run inside markdownlint-cli2 and
+* the VS Code markdownlint extension.
+*
+* @example
+* ```json
+* {
+*   "changeset-content-structure": true
+* }
+* ```
+*
+* @see {@link https://github.com/savvy-web/changesets/blob/main/docs/rules/CSH003.md | CSH003 rule documentation}
+* @see `src/remark/rules/content-structure.ts` for the corresponding remark-lint rule
+*
+* @public
+*/
+const ContentStructureRule = {
+	names: ["changeset-content-structure", "CSH003"],
+	description: "Sections must have content, code blocks need languages, list items need text",
+	tags: ["changeset"],
+	parser: "micromark",
+	function: function CSH003(params, onError) {
+		const tokens = params.parsers.micromark.tokens;
+		const h2Indices = [];
+		for (let i = 0; i < tokens.length; i++) if (tokens[i].type === "atxHeading" && getHeadingLevel(tokens[i]) === 2) h2Indices.push(i);
+		for (let i = 0; i < h2Indices.length; i++) {
+			const currentIdx = h2Indices[i];
+			if (!hasContentBetween(tokens, currentIdx, i + 1 < h2Indices.length ? h2Indices[i + 1] : tokens.length)) onError({
+				lineNumber: tokens[currentIdx].startLine,
+				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) {
+			if (token.type !== "codeFenced") continue;
+			if (!(token.children.find((c) => c.type === "codeFencedFence")?.children.some((c) => c.type === "codeFencedFenceInfo") ?? false)) onError({
+				lineNumber: token.startLine,
+				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) {
+			if (token.type !== "listOrdered" && token.type !== "listUnordered") continue;
+			const children = token.children;
+			for (let i = 0; i < children.length; i++) {
+				if (children[i].type !== "listItemPrefix") continue;
+				let hasContent = false;
+				for (let j = i + 1; j < children.length; j++) {
+					if (children[j].type === "listItemPrefix") break;
+					if (children[j].type === "content") {
+						hasContent = true;
+						break;
+					}
+				}
+				if (!hasContent) onError({
+					lineNumber: children[i].startLine,
+					detail: `Empty list item. Each list item must contain descriptive text (e.g., "- Fixed login timeout issue"). See: ${RULE_DOCS.CSH003}`
+				});
+			}
+		}
+	}
+};
+
+//#endregion
+export { ContentStructureRule };