@savvy-web/silk-effects 0.6.0 → 1.0.0

package/changesets/changelog/formatting.js

@@ -0,0 +1,119 @@
+import { extractUrlFromMarkdown } from "../utils/markdown-link.js";
+
+//#region src/changesets/changelog/formatting.ts
+/**
+* Issue reference categories and their display labels.
+*
+* Used by {@link formatChangelogEntry} to render issue links grouped
+* by their relationship to the change (Closes, Fixes, Refs).
+*
+* @internal
+*/
+const ISSUE_CATEGORIES = [
+	{
+		key: "closes",
+		label: "Closes"
+	},
+	{
+		key: "fixes",
+		label: "Fixes"
+	},
+	{
+		key: "refs",
+		label: "Refs"
+	}
+];
+/**
+* Format a changelog entry into a markdown string with GitHub links.
+*
+* Produces a commit-link prefix (shortened to 7 characters) followed by the
+* summary text and any issue references, each rendered as GitHub links.
+*
+* @remarks
+* The output does **not** include a leading `- ` list marker — the caller
+* is responsible for wrapping the result in a markdown list item. Issue
+* references are appended on a new paragraph (double newline) when present,
+* grouped by category: "Closes", "Fixes", "Refs".
+*
+* Output format examples:
+*
+* With commit: `[short-hash](commit-url) Summary text`
+*
+* With issues: `Summary text` followed by `Closes: [#1](issue-url)`
+*
+* With both: `[short-hash](commit-url) Summary text` followed by `Fixes: [#2](issue-url)`
+*
+* @param entry - The changelog entry containing commit, summary, and issue data
+* @param options - Must include `repo` in `owner/repo` format for link generation
+* @returns Formatted markdown string (without leading `- `)
+*
+* @internal
+*/
+function formatChangelogEntry(entry, options) {
+	const parts = [];
+	if (entry.commit) {
+		const shortHash = entry.commit.substring(0, 7);
+		parts.push(`[\`${shortHash}\`](https://github.com/${options.repo}/commit/${entry.commit})`);
+	}
+	parts.push(entry.summary.trim());
+	const issueLinks = [];
+	for (const { key, label } of ISSUE_CATEGORIES) {
+		const numbers = entry.issues[key];
+		if (numbers.length > 0) {
+			const links = numbers.map((num) => `[#${num}](https://github.com/${options.repo}/issues/${num})`);
+			issueLinks.push(`${label}: ${links.join(", ")}`);
+		}
+	}
+	if (issueLinks.length > 0) parts.push(`\n\n${issueLinks.join(". ")}`);
+	return parts.join(" ");
+}
+/**
+* Format pull-request reference and user attribution for a changelog entry.
+*
+* Appends a PR link and/or a "Thanks \@user!" attribution suffix to a
+* changelog line. The output includes a leading space when non-empty, so it
+* can be directly concatenated after the main entry text.
+*
+* @remarks
+* The `links` parameter may contain either plain URLs or markdown-formatted
+* links (e.g., `[#42](https://...)`). This function handles both formats
+* via {@link extractUrlFromMarkdown}, which strips the markdown link syntax
+* and extracts the raw URL.
+*
+* Output format examples:
+*
+* PR only: `[#42](pr-url)`
+*
+* PR without link: `(#42)`
+*
+* User only: `Thanks user!`
+*
+* Both: `[#42](pr-url) Thanks [user](profile-url)!`
+*
+* Neither: empty string
+*
+* @param pr - Pull request number (omit if no PR is associated)
+* @param user - GitHub username of the contributor (omit if unknown)
+* @param links - Optional pre-formatted links for the PR and user from the GitHub API
+* @returns Formatted attribution string (with leading space) or empty string
+*
+* @internal
+*/
+function formatPRAndUserAttribution(pr, user, links) {
+	let prReference = "";
+	if (pr) if (links?.pull) {
+		const pullUrl = extractUrlFromMarkdown(links.pull);
+		prReference = ` [#${String(pr)}](${pullUrl})`;
+	} else prReference = ` (#${String(pr)})`;
+	if (user) {
+		if (links?.user) {
+			const userUrl = extractUrlFromMarkdown(links.user);
+			return `${prReference} Thanks [@${user}](${userUrl})!`;
+		}
+		return `${prReference} Thanks @${user}!`;
+	}
+	return prReference;
+}
+
+//#endregion
+export { formatChangelogEntry, formatPRAndUserAttribution };

package/changesets/changelog/getDependencyReleaseLine.js

@@ -0,0 +1,114 @@
+import { GitHubService } from "../services/github.js";
+import { serializeDependencyTableToMarkdown } from "../utils/dependency-table.js";
+import { Effect } from "effect";
+
+//#region src/changesets/changelog/getDependencyReleaseLine.ts
+/**
+* Core formatter: getDependencyReleaseLine.
+*
+* Formats dependency update entries as a structured markdown table showing
+* each updated dependency's name, type, action, and version range.
+*
+* @remarks
+* This formatter is the companion to {@link getReleaseLine}. While
+* `getReleaseLine` handles individual changeset entries, this module
+* handles the "Updated dependencies" section that Changesets appends
+* when a package's dependencies are bumped as part of a release.
+*
+* The output is a GFM (GitHub Flavored Markdown) table with columns:
+* `Dependency`, `Type`, `Action`, `From`, `To`. The dependency type
+* is inferred from the consuming package's `package.json` fields
+* (`dependencies`, `devDependencies`, `peerDependencies`,
+* `optionalDependencies`) via the {@link inferDependencyType} helper.
+*
+* ### Dependency type inference
+*
+* The {@link FIELD_MAP} constant defines the precedence order for
+* inferring the dependency type. The first matching field wins:
+*
+* 1. `dependencies` maps to `"dependency"`
+* 2. `devDependencies` maps to `"devDependency"`
+* 3. `peerDependencies` maps to `"peerDependency"`
+* 4. `optionalDependencies` maps to `"optionalDependency"`
+*
+* If the dependency is not found in any field, it defaults to `"dependency"`.
+*
+* @see {@link getReleaseLine} for the companion individual changeset formatter
+* @see {@link serializeDependencyTableToMarkdown} for the table serialization utility
+*
+* @internal
+*/
+/**
+* Field-to-type mapping for inferring dependency type from `package.json`.
+*
+* Maps `package.json` dependency fields to their corresponding
+* `DependencyTableType` values. The order defines precedence when a
+* dependency name appears in multiple fields (first match wins).
+*
+* @internal
+*/
+const FIELD_MAP = [
+	["dependencies", "dependency"],
+	["devDependencies", "devDependency"],
+	["peerDependencies", "peerDependency"],
+	["optionalDependencies", "optionalDependency"]
+];
+/**
+* Infer the dependency table type from a package's `package.json`.
+*
+* Inspects the consuming package's `package.json` to determine which
+* dependency field contains the given dependency name. Returns the
+* corresponding `DependencyTableType` value, or `"dependency"` as a
+* fallback when the dependency is not found in any standard field.
+*
+* @param dep - The dependency update with its associated `packageJson`
+* @returns The inferred dependency type for display in the table
+*
+* @internal
+*/
+function inferDependencyType(dep) {
+	const pkg = dep.packageJson;
+	for (const [field, type] of FIELD_MAP) {
+		const section = pkg[field];
+		if (typeof section === "object" && section !== null && dep.name in section) return type;
+	}
+	return "dependency";
+}
+/**
+* Format dependency release lines as a structured markdown table.
+*
+* This is the core Effect program that implements the `getDependencyReleaseLine`
+* contract from the Changesets API. It requires {@link GitHubService} in its
+* environment (currently unused but kept for API contract stability).
+*
+* @remarks
+* The function maps each `ModCompWithPackage` entry to a `DependencyTableRow`,
+* inferring the dependency type from the consuming package's `package.json`,
+* then delegates to `serializeDependencyTableToMarkdown` for GFM table
+* rendering. Returns an empty string when no dependencies were updated.
+*
+* The `_changesets` and `_options` parameters are part of the Changesets API
+* contract but are not used in the table format. They are retained for
+* interface compatibility.
+*
+* @param _changesets - Changesets that caused the dependency updates (unused in table format)
+* @param dependenciesUpdated - The list of dependencies that were updated, including old/new versions
+* @param _options - Validated configuration options (unused in table format)
+* @returns An `Effect` that resolves to a formatted markdown table string, or empty string if no dependencies were updated
+*/
+function getDependencyReleaseLine(_changesets, dependenciesUpdated, _options) {
+	return Effect.gen(function* () {
+		if (dependenciesUpdated.length === 0) return "";
+		yield* GitHubService;
+		return serializeDependencyTableToMarkdown(dependenciesUpdated.map((dep) => ({
+			dependency: dep.name,
+			type: inferDependencyType(dep),
+			action: "updated",
+			from: dep.oldVersion,
+			to: dep.newVersion
+		})));
+	});
+}
+
+//#endregion
+export { getDependencyReleaseLine };

package/changesets/changelog/getReleaseLine.js

@@ -0,0 +1,122 @@
+import { resolveCommitType } from "../categories/index.js";
+import { GitHubService } from "../services/github.js";
+import { GitHubInfoSchema } from "../schemas/github.js";
+import { parseCommitMessage } from "../utils/commit-parser.js";
+import { parseIssueReferences } from "../utils/issue-refs.js";
+import { logWarning } from "../utils/logger.js";
+import { parseChangesetSections } from "../utils/section-parser.js";
+import { formatChangelogEntry, formatPRAndUserAttribution } from "./formatting.js";
+import { Effect, Schema } from "effect";
+
+//#region src/changesets/changelog/getReleaseLine.ts
+/**
+* Core formatter: getReleaseLine.
+*
+* Formats a single changeset into a changelog entry. This is the primary
+* formatting function in the changelog pipeline, responsible for transforming
+* a `NewChangesetWithCommit` into structured markdown output.
+*
+* @remarks
+* The formatter supports two distinct input modes:
+*
+* 1. **Section-aware changesets** — When the changeset summary contains h2
+*    headings (e.g., `## Features`, `## Bug Fixes`), each section is rendered
+*    as an h3 heading with commit-linked list items beneath it. This mode
+*    produces multi-line output suitable for rich changelogs.
+*
+* 2. **Flat-text changesets** — When the summary is plain text without section
+*    headings, the formatter falls back to backward-compatible single-line
+*    output. The conventional commit type is resolved via `resolveCommitType`
+*    to determine the changelog category.
+*
+* In both modes, the formatter:
+* - Fetches GitHub metadata (PR number, author) via {@link GitHubService}
+* - Generates shortened commit hash links (`[abc1234](...)`)
+* - Extracts and renders issue references (Closes, Fixes, Refs)
+* - Appends PR and user attribution when available
+*
+* @see {@link formatChangelogEntry} for the low-level entry formatting
+* @see {@link formatPRAndUserAttribution} for attribution suffix generation
+* @see {@link getDependencyReleaseLine} for the companion dependency formatter
+*
+* @internal
+*/
+/**
+* Format a single changeset into a markdown release line.
+*
+* This is the core Effect program that implements the `getReleaseLine` contract
+* from the Changesets API. It requires {@link GitHubService} in its environment
+* for resolving commit metadata.
+*
+* @remarks
+* The formatting pipeline proceeds in seven steps:
+*
+* 1. **Fetch GitHub info** — If the changeset has a commit hash, query
+*    the {@link GitHubService} for PR number, author, and links. Failures
+*    are caught and logged as warnings (attribution is simply omitted).
+* 2. **Parse sections** — Attempt to split the summary into h2-delimited
+*    sections using `parseChangesetSections`.
+* 3. **Parse conventional commit** — Extract the commit type, scope, and
+*    breaking flag from the first line of the summary.
+* 4. **Extract issue references** — Parse the body for `Closes #N`,
+*    `Fixes #N`, and `Refs #N` patterns.
+* 5. **Build attribution** — Format PR link and user credit from GitHub info.
+* 6. **Section-aware output** — If sections were found, render each as an
+*    h3 heading with commit-linked list items.
+* 7. **Flat-text fallback** — Otherwise, produce a single `- entry` line
+*    with the resolved category heading.
+*
+* @param changeset - The changeset to format, including commit hash and summary text
+* @param versionType - The semantic version bump type (`major`, `minor`, or `patch`),
+*   used as fallback when no conventional commit type is detected
+* @param options - Validated configuration options (must include `repo` in `owner/repo` format)
+* @returns An `Effect` that resolves to a formatted markdown string
+*/
+function getReleaseLine(changeset, versionType, options) {
+	return Effect.gen(function* () {
+		let commitInfo = null;
+		if (changeset.commit) commitInfo = yield* (yield* GitHubService).getInfo({
+			commit: changeset.commit,
+			repo: options.repo
+		}).pipe(Effect.flatMap((raw) => Schema.decodeUnknown(GitHubInfoSchema)(raw).pipe(Effect.map(() => raw), Effect.catchAll(() => Effect.succeed(raw)))), Effect.catchAll((error) => {
+			logWarning("Could not fetch GitHub info for commit:", changeset.commit ?? "", String(error));
+			return Effect.succeed(null);
+		}));
+		const parsed = parseChangesetSections(changeset.summary);
+		const firstLine = changeset.summary.split("\n")[0];
+		const commitMsg = parseCommitMessage(firstLine);
+		const issueRefs = parseIssueReferences(changeset.summary.split("\n").slice(1).join("\n"));
+		const attribution = commitInfo ? formatPRAndUserAttribution(commitInfo.pull ?? void 0, commitInfo.user ?? void 0, commitInfo.links) : "";
+		if (parsed.sections.length > 0) {
+			const lines = [];
+			if (parsed.preamble) {
+				lines.push(parsed.preamble);
+				lines.push("");
+			}
+			for (const section of parsed.sections) {
+				lines.push(`### ${section.category.heading}`);
+				lines.push("");
+				const commitPrefix = changeset.commit ? `[\`${changeset.commit.substring(0, 7)}\`](https://github.com/${options.repo}/commit/${changeset.commit}) ` : "";
+				if (section.content) {
+					const contentLines = section.content.split("\n");
+					const firstContentLine = contentLines[0];
+					if (firstContentLine.startsWith("- ") || firstContentLine.startsWith("* ")) {
+						lines.push(`${firstContentLine.substring(0, 2)}${commitPrefix}${firstContentLine.substring(2)}`);
+						lines.push(...contentLines.slice(1));
+					} else lines.push(`- ${commitPrefix}${section.content}`);
+				}
+				lines.push("");
+			}
+			return `${lines.join("\n").trimEnd()}${attribution}`;
+		}
+		return `- ${formatChangelogEntry({
+			type: resolveCommitType(commitMsg.type ?? versionType, commitMsg.scope, commitMsg.breaking).heading,
+			summary: changeset.summary,
+			issues: issueRefs,
+			...changeset.commit ? { commit: changeset.commit } : {}
+		}, { repo: options.repo })}${attribution}`;
+	});
+}
+
+//#endregion
+export { getReleaseLine };

package/changesets/changelog/index.js

@@ -0,0 +1,99 @@
+import { validateChangesetOptions } from "../schemas/options.js";
+import { GitHubLive } from "../services/github.js";
+import { MarkdownLive } from "../services/markdown.js";
+import { getDependencyReleaseLine } from "./getDependencyReleaseLine.js";
+import { getReleaseLine } from "./getReleaseLine.js";
+import { Effect, Layer } from "effect";
+
+//#region src/changesets/changelog/index.ts
+/**
+* Changesets API changelog formatter — `\@savvy-web/changesets/changelog`
+*
+* This module is the default export consumed by the Changesets CLI via the
+* `changelog` field in `.changeset/config.json`. It implements the
+* `ChangelogFunctions` interface from `\@changesets/types`, wiring the
+* Effect-based formatting pipeline into the async API that Changesets expects.
+*
+* @remarks
+* The module composes two Effect programs — {@link getReleaseLine} and
+* {@link getDependencyReleaseLine} — and runs each through
+* `Effect.runPromise` with a merged layer of {@link GitHubLive} (for commit
+* metadata) and {@link MarkdownLive} (for mdast parsing). Options are
+* validated at the boundary via `validateChangesetOptions` before being
+* passed to the formatters.
+*
+* ### Configuration
+*
+* Add the following to your `.changeset/config.json`:
+*
+* ```json
+* {
+*   "changelog": ["\@savvy-web/changesets/changelog", { "repo": "savvy-web/package-name" }]
+* }
+* ```
+*
+* The `repo` option is **required** and must be in `owner/repo` format.
+*
+* ### Pipeline
+*
+* 1. **Options validation** — the raw `options` object from the Changesets
+*    config is decoded through `ChangesetOptionsSchema`.
+* 2. **Release line formatting** — each changeset is formatted by
+*    `getReleaseLine`, which resolves GitHub metadata, parses sections,
+*    and produces structured markdown with commit links and attribution.
+* 3. **Dependency table formatting** — bulk dependency updates are
+*    formatted by `getDependencyReleaseLine` into a markdown table.
+*
+* @example Configuring in `.changeset/config.json`
+* ```json
+* {
+*   "$schema": "https://unpkg.com/\@changesets/config\@3.1.1/schema.json",
+*   "changelog": ["\@savvy-web/changesets/changelog", { "repo": "savvy-web/my-package" }],
+*   "commit": false,
+*   "access": "public"
+* }
+* ```
+*
+* @see {@link getReleaseLine} in `./getReleaseLine.ts` for individual changeset formatting
+* @see {@link getDependencyReleaseLine} in `./getDependencyReleaseLine.ts` for dependency table formatting
+*
+* @packageDocumentation
+*/
+/**
+* Combined layer providing all services needed by the formatters.
+*
+* Merges {@link GitHubLive} and {@link MarkdownLive} into a single layer
+* that satisfies the environment requirements of both `getReleaseLine`
+* (which needs `GitHubService` and `MarkdownService`) and
+* `getDependencyReleaseLine` (which needs `GitHubService`).
+*
+* @internal
+*/
+const MainLayer = Layer.mergeAll(GitHubLive, MarkdownLive);
+/**
+* Changesets API `ChangelogFunctions` implementation.
+*
+* This object satisfies the `ChangelogFunctions` contract from
+* `\@changesets/types`. Each method validates options, runs the
+* corresponding Effect program with the merged service layer, and
+* returns a `Promise<string>`.
+*
+* @internal
+*/
+const changelogFunctions = {
+	getReleaseLine: async (changeset, versionType, options) => {
+		const program = Effect.gen(function* () {
+			return yield* getReleaseLine(changeset, versionType, yield* validateChangesetOptions(options));
+		});
+		return Effect.runPromise(program.pipe(Effect.provide(MainLayer)));
+	},
+	getDependencyReleaseLine: async (changesets, dependenciesUpdated, options) => {
+		const program = Effect.gen(function* () {
+			return yield* getDependencyReleaseLine(changesets, dependenciesUpdated, yield* validateChangesetOptions(options));
+		});
+		return Effect.runPromise(program.pipe(Effect.provide(MainLayer)));
+	}
+};
+
+//#endregion
+export { changelogFunctions as default };

package/changesets/constants.js

@@ -0,0 +1,43 @@
+//#region src/changesets/constants.ts
+/**
+* Constants for changeset lint rule documentation URLs.
+*
+* @remarks
+* Each lint rule in the \@savvy-web/changesets remark-lint plugin has a
+* corresponding documentation page hosted on GitHub. These URLs are
+* referenced in lint diagnostic messages to help users understand and
+* resolve validation errors.
+*
+* Rule codes follow the `CSH` prefix convention:
+* - `CSH001` -- Changeset heading validation
+* - `CSH002` -- Changeset summary validation
+* - `CSH003` -- Dependency table structure validation
+* - `CSH004` -- Changeset body content validation
+* - `CSH005` -- Frontmatter validation
+*
+* @internal
+* @packageDocumentation
+*/
+/** Base URL for rule documentation on GitHub. */
+const DOCS_BASE = "https://github.com/savvy-web/changesets/blob/main/docs/rules";
+/**
+* Documentation URLs for each changeset lint rule.
+*
+* @remarks
+* Keyed by rule code (`CSH001`--`CSH005`). Each value is a full URL
+* pointing to the rule's documentation page on GitHub. Used by the
+* remark-lint plugins to attach documentation links to diagnostic
+* messages.
+*
+* @internal
+*/
+const RULE_DOCS = {
+	CSH001: `${DOCS_BASE}/CSH001.md`,
+	CSH002: `${DOCS_BASE}/CSH002.md`,
+	CSH003: `${DOCS_BASE}/CSH003.md`,
+	CSH004: `${DOCS_BASE}/CSH004.md`,
+	CSH005: `${DOCS_BASE}/CSH005.md`
+};
+
+//#endregion
+export { RULE_DOCS };