@savvy-web/silk-effects 0.6.1 → 1.0.0

package/changesets/api/linter.js

@@ -0,0 +1,168 @@
+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 { stripFrontmatter } from "../utils/strip-frontmatter.js";
+import remarkParse from "remark-parse";
+import remarkStringify from "remark-stringify";
+import { unified } from "unified";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/changesets/api/linter.ts
+/**
+* Class-based API wrapper for changeset linting.
+*
+* Provides a static class interface that runs all remark-lint rules
+* against changeset markdown files and returns structured diagnostics.
+*
+* @internal
+*/
+/**
+* Static class for linting changeset markdown files.
+*
+* Runs the four remark-lint rules (heading-hierarchy, required-sections,
+* content-structure, uncategorized-content) against changeset markdown
+* and returns structured {@link LintMessage} diagnostics.
+*
+* @remarks
+* This class implements the pre-validation layer of the three-layer
+* pipeline. It validates that changeset markdown conforms to the
+* expected structure before the changelog formatter processes it.
+*
+* YAML frontmatter (the `---` delimited block at the top of changeset
+* files containing package bump declarations) is automatically stripped
+* before validation, since frontmatter is managed by Changesets itself
+* and is not part of the markdown structure being validated.
+*
+* The class provides three granularity levels:
+*
+* - {@link ChangesetLinter.validateContent} -- validate a markdown string directly
+* - {@link ChangesetLinter.validateFile} -- validate a single file by path
+* - {@link ChangesetLinter.validate} -- validate all changeset files in a directory
+*
+* @example Validate a single file and report errors
+* ```typescript
+* import { ChangesetLinter } from "\@savvy-web/changesets";
+* import type { LintMessage } from "\@savvy-web/changesets";
+*
+* const messages: LintMessage[] = ChangesetLinter.validateFile(
+*   ".changeset/brave-pandas-learn.md",
+* );
+*
+* if (messages.length > 0) {
+*   for (const msg of messages) {
+*     console.error(`${msg.file}:${msg.line}:${msg.column} [${msg.rule}] ${msg.message}`);
+*   }
+*   process.exitCode = 1;
+* }
+* ```
+*
+* @example Validate all changesets in a directory
+* ```typescript
+* import { ChangesetLinter } from "\@savvy-web/changesets";
+* import type { LintMessage } from "\@savvy-web/changesets";
+*
+* const allMessages: LintMessage[] = ChangesetLinter.validate(".changeset");
+*
+* const errorsByFile = new Map<string, LintMessage[]>();
+* for (const msg of allMessages) {
+*   const existing = errorsByFile.get(msg.file) ?? [];
+*   existing.push(msg);
+*   errorsByFile.set(msg.file, existing);
+* }
+*
+* for (const [file, msgs] of errorsByFile) {
+*   console.error(`${file}: ${msgs.length} issue(s)`);
+* }
+* ```
+*
+* @example Validate markdown content directly (useful in tests)
+* ```typescript
+* import { ChangesetLinter } from "\@savvy-web/changesets";
+* import type { LintMessage } from "\@savvy-web/changesets";
+*
+* const content = [
+*   "---",
+*   '"\@savvy-web/core": patch',
+*   "---",
+*   "",
+*   "## Bug Fixes",
+*   "",
+*   "Fixed an edge case in token validation.",
+* ].join("\n");
+*
+* const messages: LintMessage[] = ChangesetLinter.validateContent(content);
+* // messages.length === 0 (valid changeset)
+* ```
+*
+* @see {@link LintMessage} for the diagnostic message shape
+* @see {@link Categories} for the valid section headings checked by the rules
+*
+* @public
+*/
+var ChangesetLinter = class ChangesetLinter {
+	/* v8 ignore next -- private constructor prevents direct instantiation */
+	constructor() {}
+	/**
+	* Validate a single changeset file by path.
+	*
+	* @remarks
+	* Reads the file synchronously, strips YAML frontmatter, and runs all
+	* four lint rules. The file path is preserved in each returned
+	* {@link LintMessage} for error reporting.
+	*
+	* @param filePath - Absolute or relative path to the changeset `.md` file
+	* @returns Array of {@link LintMessage} diagnostics (empty if the file is valid)
+	*/
+	static validateFile(filePath) {
+		const raw = readFileSync(filePath, "utf-8");
+		return ChangesetLinter.validateContent(raw, filePath);
+	}
+	/**
+	* Validate a markdown string directly.
+	*
+	* @remarks
+	* Strips YAML frontmatter (if present) and runs all four lint rules
+	* against the remaining content. This method is useful for validating
+	* changeset content that is already in memory, such as in test suites
+	* or editor integrations.
+	*
+	* @param content - Raw markdown content (may include YAML frontmatter)
+	* @param filePath - File path for error reporting; defaults to `"<input>"`
+	*   when validating in-memory content
+	* @returns Array of {@link LintMessage} diagnostics (empty if the content is valid)
+	*/
+	static validateContent(content, filePath = "<input>") {
+		const body = stripFrontmatter(content);
+		return unified().use(remarkParse).use(remarkStringify).use(HeadingHierarchyRule).use(RequiredSectionsRule).use(ContentStructureRule).use(UncategorizedContentRule).processSync(body).messages.map((msg) => ({
+			file: filePath,
+			/* v8 ignore next 3 -- ruleId/line/column fallbacks; remark-lint always provides these */
+			rule: msg.ruleId ?? msg.source ?? "unknown",
+			line: msg.line ?? 1,
+			column: msg.column ?? 1,
+			message: msg.message
+		}));
+	}
+	/**
+	* Validate all changeset `.md` files in a directory.
+	*
+	* @remarks
+	* Scans the directory for `*.md` files (excluding `README.md`) and runs
+	* {@link ChangesetLinter.validateFile} on each. Results are aggregated
+	* into a single array. The directory is read synchronously.
+	*
+	* This is the method used by the Effect CLI's `lint` and `check`
+	* subcommands to validate the `.changeset/` directory.
+	*
+	* @param dir - Path to the directory containing changeset files
+	*   (typically `.changeset/`)
+	* @returns Aggregated array of {@link LintMessage} diagnostics from all files
+	*/
+	static validate(dir) {
+		return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").flatMap((filename) => ChangesetLinter.validateFile(join(dir, filename)));
+	}
+};
+
+//#endregion
+export { ChangesetLinter };

package/changesets/api/transformer.js

@@ -0,0 +1,140 @@
+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 remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkStringify from "remark-stringify";
+import { unified } from "unified";
+import { readFileSync, writeFileSync } from "node:fs";
+
+//#region src/changesets/api/transformer.ts
+/**
+* Class-based API wrapper for changelog transformation.
+*
+* Provides a static class interface that runs all remark transform
+* plugins against CHANGELOG markdown content as the post-processing
+* layer of the three-layer pipeline.
+*
+* @internal
+*/
+/**
+* Static class for post-processing CHANGELOG.md files.
+*
+* Implements the third layer of the three-layer pipeline by running
+* six remark transform plugins in a fixed order to clean up, normalize,
+* and enhance changelog output produced by the formatter layer.
+*
+* @remarks
+* The six plugins run in this order:
+*
+* 1. **MergeSectionsPlugin** -- merges duplicate section headings (e.g., two
+*    "Features" sections from separate changesets are combined into one)
+* 2. **ReorderSectionsPlugin** -- reorders sections by category priority
+*    (Breaking Changes first, Other last) using the {@link Categories} priority values
+* 3. **DeduplicateItemsPlugin** -- removes duplicate list items within a section
+* 4. **ContributorFootnotesPlugin** -- converts inline contributor mentions
+*    into footnote references for cleaner formatting
+* 5. **IssueLinkRefsPlugin** -- converts inline issue/PR links into markdown
+*    reference-style links collected at the bottom of the document
+* 6. **NormalizeFormatPlugin** -- applies consistent formatting (spacing,
+*    trailing newlines, heading levels)
+*
+* The transformer operates on the full CHANGELOG.md content (all versions),
+* not just the latest release block. It is idempotent -- running it multiple
+* times produces the same output.
+*
+* @example Transform changelog content in memory
+* ```typescript
+* import { ChangelogTransformer } from "\@savvy-web/changesets";
+*
+* const rawChangelog = [
+*   "# Changelog",
+*   "",
+*   "## 1.2.0",
+*   "",
+*   "### Features",
+*   "",
+*   "- Added new auth endpoint",
+*   "",
+*   "### Features",
+*   "",
+*   "- Added rate limiting",
+* ].join("\n");
+*
+* const cleaned: string = ChangelogTransformer.transformContent(rawChangelog);
+* // Duplicate "Features" sections are merged into one
+* ```
+*
+* @example Transform a CHANGELOG.md file in-place
+* ```typescript
+* import { ChangelogTransformer } from "\@savvy-web/changesets";
+*
+* // Reads, transforms, and writes back to the same path
+* ChangelogTransformer.transformFile("CHANGELOG.md");
+* ```
+*
+* @example Check for changes without writing (dry-run pattern)
+* ```typescript
+* import { readFileSync } from "node:fs";
+* import { ChangelogTransformer } from "\@savvy-web/changesets";
+*
+* const original: string = readFileSync("CHANGELOG.md", "utf-8");
+* const transformed: string = ChangelogTransformer.transformContent(original);
+*
+* if (original !== transformed) {
+*   console.error("CHANGELOG.md needs transformation");
+*   process.exitCode = 1;
+* }
+* ```
+*
+* @see {@link Categories} for the priority order used by ReorderSectionsPlugin
+* @see {@link ChangesetLinter} for the pre-validation layer (layer 1)
+* @see {@link Changelog} for the formatter layer (layer 2)
+*
+* @public
+*/
+var ChangelogTransformer = class ChangelogTransformer {
+	/* v8 ignore next -- private constructor prevents direct instantiation */
+	constructor() {}
+	/**
+	* Transform CHANGELOG markdown content by running all six transform plugins.
+	*
+	* @remarks
+	* The input is parsed with `remark-parse` and `remark-gfm` (for table
+	* support), processed through all six plugins in order, and stringified
+	* back to markdown. The operation is synchronous and idempotent.
+	*
+	* @param content - Raw CHANGELOG markdown string (may contain multiple
+	*   version blocks, GFM tables, footnotes, and reference links)
+	* @returns The transformed markdown string with sections merged, reordered,
+	*   deduplicated, and normalized
+	*/
+	static transformContent(content) {
+		const file = unified().use(remarkParse).use(remarkGfm).use(MergeSectionsPlugin).use(ReorderSectionsPlugin).use(DeduplicateItemsPlugin).use(ContributorFootnotesPlugin).use(IssueLinkRefsPlugin).use(NormalizeFormatPlugin).use(remarkStringify).processSync(content);
+		return String(file);
+	}
+	/**
+	* Transform a CHANGELOG file in-place.
+	*
+	* @remarks
+	* Reads the file synchronously, runs all transform plugins via
+	* {@link ChangelogTransformer.transformContent}, and writes the result
+	* back to the same path. The file is overwritten atomically (single
+	* `writeFileSync` call).
+	*
+	* This is the method used by the Effect CLI's `transform` subcommand
+	* when invoked without the `--dry-run` or `--check` flags.
+	*
+	* @param filePath - Absolute or relative path to the CHANGELOG.md file
+	*/
+	static transformFile(filePath) {
+		const content = readFileSync(filePath, "utf-8");
+		writeFileSync(filePath, ChangelogTransformer.transformContent(content), "utf-8");
+	}
+};
+
+//#endregion
+export { ChangelogTransformer };

package/changesets/categories/index.js

@@ -0,0 +1,299 @@
+//#region src/changesets/categories/index.ts
+/**
+* Breaking changes -- backward-incompatible changes.
+*
+* @remarks
+* Priority 1 (highest). This category has no associated commit types;
+* it is resolved by the `!` suffix on any conventional commit type
+* (e.g., `feat!:`, `fix!:`). Use {@link resolveCommitType} with
+* `breaking: true` to map to this category.
+*
+* @internal
+*/
+const BREAKING_CHANGES = {
+	heading: "Breaking Changes",
+	priority: 1,
+	commitTypes: [],
+	description: "Backward-incompatible changes"
+};
+/**
+* Features -- new functionality.
+*
+* @remarks
+* Priority 2. Maps from the `feat` conventional commit type.
+*
+* @internal
+*/
+const FEATURES = {
+	heading: "Features",
+	priority: 2,
+	commitTypes: ["feat"],
+	description: "New functionality"
+};
+/**
+* Bug Fixes -- bug corrections.
+*
+* @remarks
+* Priority 3. Maps from the `fix` conventional commit type.
+*
+* @internal
+*/
+const BUG_FIXES = {
+	heading: "Bug Fixes",
+	priority: 3,
+	commitTypes: ["fix"],
+	description: "Bug corrections"
+};
+/**
+* Performance -- performance improvements.
+*
+* @remarks
+* Priority 4. Maps from the `perf` conventional commit type.
+*
+* @internal
+*/
+const PERFORMANCE = {
+	heading: "Performance",
+	priority: 4,
+	commitTypes: ["perf"],
+	description: "Performance improvements"
+};
+/**
+* Documentation -- documentation changes.
+*
+* @remarks
+* Priority 5. Maps from the `docs` conventional commit type.
+*
+* @internal
+*/
+const DOCUMENTATION = {
+	heading: "Documentation",
+	priority: 5,
+	commitTypes: ["docs"],
+	description: "Documentation changes"
+};
+/**
+* Refactoring -- code restructuring without behavior change.
+*
+* @remarks
+* Priority 6. Maps from the `refactor` conventional commit type.
+*
+* @internal
+*/
+const REFACTORING = {
+	heading: "Refactoring",
+	priority: 6,
+	commitTypes: ["refactor"],
+	description: "Code restructuring"
+};
+/**
+* Tests -- test additions or modifications.
+*
+* @remarks
+* Priority 7. Maps from the `test` conventional commit type.
+*
+* @internal
+*/
+const TESTS = {
+	heading: "Tests",
+	priority: 7,
+	commitTypes: ["test"],
+	description: "Test additions or modifications"
+};
+/**
+* Build System -- build configuration changes.
+*
+* @remarks
+* Priority 8. Maps from the `build` conventional commit type.
+*
+* @internal
+*/
+const BUILD_SYSTEM = {
+	heading: "Build System",
+	priority: 8,
+	commitTypes: ["build"],
+	description: "Build configuration changes"
+};
+/**
+* CI -- continuous integration changes.
+*
+* @remarks
+* Priority 9. Maps from the `ci` conventional commit type.
+*
+* @internal
+*/
+const CI = {
+	heading: "CI",
+	priority: 9,
+	commitTypes: ["ci"],
+	description: "Continuous integration changes"
+};
+/**
+* Dependencies -- dependency updates.
+*
+* @remarks
+* Priority 10. Maps from the `deps` conventional commit type and also
+* from `chore(deps)` via the {@link resolveCommitType} function.
+*
+* @internal
+*/
+const DEPENDENCIES = {
+	heading: "Dependencies",
+	priority: 10,
+	commitTypes: ["deps"],
+	description: "Dependency updates"
+};
+/**
+* Maintenance -- general maintenance tasks.
+*
+* @remarks
+* Priority 11. Maps from the `chore` and `style` conventional commit types.
+* Note that `chore(deps)` is redirected to {@link DEPENDENCIES} by
+* {@link resolveCommitType}.
+*
+* @internal
+*/
+const MAINTENANCE = {
+	heading: "Maintenance",
+	priority: 11,
+	commitTypes: ["chore", "style"],
+	description: "General maintenance"
+};
+/**
+* Reverts -- reverted changes.
+*
+* @remarks
+* Priority 12. Maps from the `revert` conventional commit type.
+*
+* @internal
+*/
+const REVERTS = {
+	heading: "Reverts",
+	priority: 12,
+	commitTypes: ["revert"],
+	description: "Reverted changes"
+};
+/**
+* Other -- uncategorized changes.
+*
+* @remarks
+* Priority 13 (lowest). This category has no associated commit types;
+* it serves as the fallback for any commit type not recognized by the
+* category system. Resolved by {@link resolveCommitType} when no other
+* category matches.
+*
+* @internal
+*/
+const OTHER = {
+	heading: "Other",
+	priority: 13,
+	commitTypes: [],
+	description: "Uncategorized changes"
+};
+/**
+* All 13 categories ordered by priority (ascending).
+*
+* @remarks
+* This array provides the canonical ordering for section headings in
+* CHANGELOG output. Breaking Changes appear first, Other appears last.
+* The array is frozen (`as const`) to prevent accidental mutation.
+*
+* @internal
+*/
+const CATEGORIES = [
+	BREAKING_CHANGES,
+	FEATURES,
+	BUG_FIXES,
+	PERFORMANCE,
+	DOCUMENTATION,
+	REFACTORING,
+	TESTS,
+	BUILD_SYSTEM,
+	CI,
+	DEPENDENCIES,
+	MAINTENANCE,
+	REVERTS,
+	OTHER
+];
+/**
+* Set of all valid section heading strings (case-insensitive lookup).
+* Used by Layer 1 (remark-lint) to validate changeset headings.
+*/
+const headingToCategory = new Map(CATEGORIES.map((cat) => [cat.heading.toLowerCase(), cat]));
+/**
+* Map from commit type string to its category.
+* Handles standard commit types. For `chore(deps)` and breaking `!` suffix,
+* use {@link resolveCommitType} instead.
+*/
+const commitTypeToCategory = /* @__PURE__ */ new Map();
+for (const cat of CATEGORIES) for (const commitType of cat.commitTypes) commitTypeToCategory.set(commitType, cat);
+/**
+* Resolve a conventional commit type (with optional scope and `!` suffix) to a category.
+*
+* @remarks
+* This function implements the full commit-type-to-category mapping logic,
+* including special cases:
+* - Any commit with `breaking: true` maps to {@link BREAKING_CHANGES}
+* - `chore` with scope `deps` maps to {@link DEPENDENCIES} (not Maintenance)
+* - Unrecognized types fall through to {@link OTHER}
+*
+* @param type - The commit type (e.g., `"feat"`, `"fix"`, `"chore"`)
+* @param scope - Optional scope (e.g., `"deps"` in `chore(deps):`)
+* @param breaking - Whether the commit has a `!` suffix indicating a breaking change
+* @returns The resolved section category
+*
+* @internal
+*/
+function resolveCommitType(type, scope, breaking) {
+	if (breaking) return BREAKING_CHANGES;
+	if (type === "chore" && scope === "deps") return DEPENDENCIES;
+	return commitTypeToCategory.get(type) ?? OTHER;
+}
+/**
+* Look up a category by its section heading text.
+*
+* @remarks
+* Comparison is case-insensitive: `"features"`, `"Features"`, and
+* `"FEATURES"` all match the Features category.
+*
+* @param heading - The heading text (e.g., `"Features"`, `"Bug Fixes"`)
+* @returns The matching category, or `undefined` if not recognized
+*
+* @internal
+*/
+function fromHeading(heading) {
+	return headingToCategory.get(heading.toLowerCase());
+}
+/**
+* Check whether a heading string matches a known category.
+*
+* @remarks
+* Comparison is case-insensitive. Useful for validating that a markdown
+* heading in a changeset file corresponds to a recognized section.
+*
+* @param heading - The heading text to check
+* @returns `true` if the heading matches a known category
+*
+* @internal
+*/
+function isValidHeading(heading) {
+	return headingToCategory.has(heading.toLowerCase());
+}
+/**
+* Get all valid section heading strings.
+*
+* @remarks
+* Returns the headings in priority order, matching the order of {@link CATEGORIES}.
+* Useful for generating help text or validation error messages that list
+* accepted headings.
+*
+* @returns Array of heading strings (e.g., `["Breaking Changes", "Features", ...]`)
+*
+* @internal
+*/
+function allHeadings() {
+	return CATEGORIES.map((cat) => cat.heading);
+}
+
+//#endregion
+export { BREAKING_CHANGES, BUG_FIXES, BUILD_SYSTEM, CATEGORIES, CI, DEPENDENCIES, DOCUMENTATION, FEATURES, MAINTENANCE, OTHER, PERFORMANCE, REFACTORING, REVERTS, TESTS, allHeadings, fromHeading, isValidHeading, resolveCommitType };

package/changesets/categories/types.js

@@ -0,0 +1,66 @@
+import { Schema } from "effect";
+
+//#region src/changesets/categories/types.ts
+/**
+* Section category schema and type definitions.
+*
+* @remarks
+* Section categories define how changes are grouped and ordered in release
+* notes and CHANGELOGs. Each category maps conventional commit types to a
+* display heading with a priority for ordering. Categories are used across
+* all three processing layers: remark-lint pre-validation (Layer 1),
+* changelog formatting (Layer 2), and remark-transform post-processing
+* (Layer 3).
+*
+* @see {@link CATEGORIES} for the predefined list of 13 section categories
+* @see {@link resolveCommitType} for mapping commit types to categories
+* @see {@link https://effect.website/docs/schema/introduction | Effect Schema documentation}
+*
+* @packageDocumentation
+*/
+/**
+* Schema for a section category that defines how changes are grouped in release notes.
+*
+* @remarks
+* A section category has four fields:
+* - `heading` -- the display heading used in CHANGELOG output (e.g., `"Features"`, `"Bug Fixes"`)
+* - `priority` -- an integer controlling display order (lower = higher priority)
+* - `commitTypes` -- conventional commit type prefixes that map to this category (e.g., `["feat"]`)
+* - `description` -- a brief human-readable description for documentation
+*
+* Categories with an empty `commitTypes` array are resolved through other means:
+* `BREAKING_CHANGES` is resolved via the `!` suffix on any commit type, and
+* `OTHER` is the fallback for unrecognized types.
+*
+* @example
+* ```typescript
+* import { Schema } from "effect";
+* import { SectionCategorySchema } from "@savvy-web/changesets";
+* import type { SectionCategory } from "@savvy-web/changesets";
+*
+* const category: SectionCategory = Schema.decodeUnknownSync(SectionCategorySchema)({
+* 	heading: "Features",
+* 	priority: 2,
+* 	commitTypes: ["feat"],
+* 	description: "New functionality",
+* });
+* ```
+*
+* @see {@link SectionCategory} for the inferred TypeScript type
+* @see {@link CATEGORIES} for all predefined categories
+*
+* @public
+*/
+const SectionCategorySchema = Schema.Struct({
+	/** Display heading used in CHANGELOG output. */
+	heading: Schema.String,
+	/** Priority for ordering (lower = higher priority). */
+	priority: Schema.Number,
+	/** Conventional commit types that map to this category. */
+	commitTypes: Schema.Array(Schema.String),
+	/** Brief description for documentation. */
+	description: Schema.String
+});
+
+//#endregion
+export { SectionCategorySchema };