@savvy-web/silk-effects 0.6.0 → 1.0.0

package/changesets/utils/issue-refs.js

@@ -0,0 +1,101 @@
+//#region src/changesets/utils/issue-refs.ts
+/**
+* GitHub issue reference parsing from commit messages.
+*
+* @remarks
+* Extracts categorized issue references (`Closes`, `Fixes`, `Refs`) from
+* commit message bodies. Supports multiple formats including with/without
+* colons, singular/plural keywords, and comma-separated issue lists.
+* Input is truncated to 10,000 characters to prevent ReDoS on adversarial input.
+*
+* @see {@link Changelog} for the public API that consumes issue references
+*
+* @internal
+*/
+/**
+* Matches "closes #123" or "close: #456, #789" patterns (case-insensitive).
+*
+* Capture group `[1]` contains the comma-separated issue number list.
+*
+* @internal
+*/
+const CLOSES_ISSUE_PATTERN = /closes?:?\s*#?(\d+(?:, *#?\d+)*)/i;
+/**
+* Matches "fixes #123" or "fix: #456, #789" patterns (case-insensitive).
+*
+* Capture group `[1]` contains the comma-separated issue number list.
+*
+* @internal
+*/
+const FIXES_ISSUE_PATTERN = /fix(?:es)?:?\s*#?(\d+(?:, *#?\d+)*)/i;
+/**
+* Matches "refs #123" or "ref: #456, #789" patterns (case-insensitive).
+*
+* Capture group `[1]` contains the comma-separated issue number list.
+*
+* @internal
+*/
+const REFS_ISSUE_PATTERN = /refs?:?\s*#?(\d+(?:, *#?\d+)*)/i;
+/**
+* Pattern for splitting comma-separated issue numbers.
+*
+* @internal
+*/
+const ISSUE_NUMBER_SPLIT_PATTERN = /, */;
+/**
+* Extract issue numbers from a regex match against a commit message.
+*
+* @remarks
+* Truncates the input to 10,000 characters before matching to prevent
+* ReDoS on adversarial input. Strips `#` prefixes from matched numbers.
+*
+* @param pattern - The regex pattern to match (must have a capture group for issue numbers)
+* @param message - The commit message body to search
+* @returns Array of issue number strings (without `#` prefix)
+*
+* @internal
+*/
+function extractIssueNumbers(pattern, message) {
+	const safeMessage = message.slice(0, 1e4);
+	const match = pattern.exec(safeMessage);
+	if (!match?.[1]) return [];
+	return match[1].split(ISSUE_NUMBER_SPLIT_PATTERN).map((num) => num.replace("#", "").trim());
+}
+/**
+* Parse a commit message for GitHub issue references.
+*
+* Recognizes `Closes`, `Fixes`, and `Refs` keywords with various formats:
+* - `Closes #123`
+* - `Fixes: #456, #789`
+* - `Refs #101`
+*
+* @remarks
+* Each keyword category is matched independently, so a single commit
+* message can contain references in all three categories. Keywords are
+* case-insensitive and accept both singular and plural forms.
+*
+* @param commitMessage - The commit message body to parse
+* @returns Categorized issue references with numbers as strings (no `#` prefix)
+*
+* @example
+* ```typescript
+* import { parseIssueReferences } from "../utils/issue-refs.js";
+*
+* const refs = parseIssueReferences("feat: add API\n\nCloses #42\nFixes: #17, #23");
+* // refs.closes === ["42"]
+* // refs.fixes === ["17", "23"]
+* // refs.refs === []
+* ```
+*
+* @internal
+*/
+function parseIssueReferences(commitMessage) {
+	return {
+		closes: extractIssueNumbers(CLOSES_ISSUE_PATTERN, commitMessage),
+		fixes: extractIssueNumbers(FIXES_ISSUE_PATTERN, commitMessage),
+		refs: extractIssueNumbers(REFS_ISSUE_PATTERN, commitMessage)
+	};
+}
+
+//#endregion
+export { parseIssueReferences };

package/changesets/utils/jsonpath.js

@@ -0,0 +1,175 @@
+//#region src/changesets/utils/jsonpath.ts
+/**
+* Tokenize a JSONPath string into segments.
+*
+* @remarks
+* Strips the leading `$.` prefix, then splits on `.` boundaries while
+* preserving bracket expressions (`[*]`, `[0]`). Each token is converted
+* to the corresponding {@link Segment} discriminated union variant.
+*
+* @param path - JSONPath string (e.g., `"$.foo[*].bar"`)
+* @returns Array of path segments
+* @throws If the path does not start with `$.`
+* @throws If the path cannot be tokenized after the `$.` prefix
+*
+* @example
+* ```typescript
+* import { parseJsonPath } from "../utils/jsonpath.js";
+*
+* const segments = parseJsonPath("$.packages[*].version");
+* // [
+* //   { type: "property", key: "packages" },
+* //   { type: "wildcard" },
+* //   { type: "property", key: "version" },
+* // ]
+* ```
+*
+* @internal
+*/
+function parseJsonPath(path) {
+	if (!path.startsWith("$.")) throw new Error(`Invalid JSONPath: must start with "$." — got "${path}"`);
+	const segments = [];
+	const raw = path.slice(2);
+	if (raw === "") return segments;
+	const tokens = raw.match(/[^.[\]]+|\[\*\]|\[\d+\]/g);
+	if (!tokens) throw new Error(`Invalid JSONPath: could not parse "${path}"`);
+	for (const token of tokens) if (token === "[*]") segments.push({ type: "wildcard" });
+	else if (token.startsWith("[") && token.endsWith("]")) segments.push({
+		type: "index",
+		index: Number.parseInt(token.slice(1, -1), 10)
+	});
+	else segments.push({
+		type: "property",
+		key: token
+	});
+	return segments;
+}
+/**
+* Collect all values matching a JSONPath expression.
+*
+* @remarks
+* Uses a breadth-first expansion: starting with the root object,
+* each segment fans out the current set of matched nodes. Wildcards
+* expand arrays into their individual elements. Non-object/non-array
+* nodes at any intermediate step are silently skipped.
+*
+* @param obj - The object to query
+* @param path - JSONPath string (e.g., `"$.version"`)
+* @returns Array of all matched values (empty if no matches)
+*
+* @example
+* ```typescript
+* import { jsonPathGet } from "../utils/jsonpath.js";
+*
+* const obj = { packages: [{ version: "1.0.0" }, { version: "2.0.0" }] };
+* const versions = jsonPathGet(obj, "$.packages[*].version");
+* // ["1.0.0", "2.0.0"]
+* ```
+*
+* @internal
+*/
+function jsonPathGet(obj, path) {
+	const segments = parseJsonPath(path);
+	let current = [obj];
+	for (const segment of segments) {
+		const next = [];
+		for (const node of current) {
+			if (node === null || node === void 0 || typeof node !== "object") continue;
+			switch (segment.type) {
+				case "property": {
+					const value = node[segment.key];
+					if (value !== void 0) next.push(value);
+					break;
+				}
+				case "index":
+					if (Array.isArray(node) && segment.index < node.length) next.push(node[segment.index]);
+					break;
+				case "wildcard":
+					if (Array.isArray(node)) next.push(...node);
+					break;
+			}
+		}
+		current = next;
+	}
+	return current;
+}
+/**
+* Mutate all matching locations in an object in-place.
+*
+* @remarks
+* Walks to the parent(s) of the final segment, then sets the value
+* at each matching location. Only updates existing keys/indices;
+* does not create new properties or extend arrays. Returns the count
+* of locations actually updated.
+*
+* @param obj - The object to modify in-place
+* @param path - JSONPath string (e.g., `"$.packages[*].version"`)
+* @param value - The value to set at each matching location
+* @returns The number of locations updated (0 if no matches or empty path)
+*
+* @example
+* ```typescript
+* import { jsonPathSet } from "../utils/jsonpath.js";
+*
+* const obj = { version: "1.0.0" };
+* const count = jsonPathSet(obj, "$.version", "2.0.0");
+* // count === 1, obj.version === "2.0.0"
+* ```
+*
+* @internal
+*/
+function jsonPathSet(obj, path, value) {
+	const segments = parseJsonPath(path);
+	if (segments.length === 0) return 0;
+	const lastSegment = segments[segments.length - 1];
+	const parentSegments = segments.slice(0, -1);
+	let parents = [obj];
+	for (const segment of parentSegments) {
+		const next = [];
+		for (const node of parents) {
+			if (node === null || node === void 0 || typeof node !== "object") continue;
+			switch (segment.type) {
+				case "property": {
+					const child = node[segment.key];
+					if (child !== void 0) next.push(child);
+					break;
+				}
+				case "index":
+					if (Array.isArray(node) && segment.index < node.length) next.push(node[segment.index]);
+					break;
+				case "wildcard":
+					if (Array.isArray(node)) next.push(...node);
+					break;
+			}
+		}
+		parents = next;
+	}
+	let count = 0;
+	for (const parent of parents) {
+		if (parent === null || parent === void 0 || typeof parent !== "object") continue;
+		switch (lastSegment.type) {
+			case "property":
+				if (lastSegment.key in parent) {
+					parent[lastSegment.key] = value;
+					count++;
+				}
+				break;
+			case "index":
+				if (Array.isArray(parent) && lastSegment.index < parent.length) {
+					parent[lastSegment.index] = value;
+					count++;
+				}
+				break;
+			case "wildcard":
+				if (Array.isArray(parent)) for (let i = 0; i < parent.length; i++) {
+					parent[i] = value;
+					count++;
+				}
+				break;
+		}
+	}
+	return count;
+}
+
+//#endregion
+export { jsonPathGet, jsonPathSet };

package/changesets/utils/logger.js

@@ -0,0 +1,50 @@
+//#region src/changesets/utils/logger.ts
+/**
+* Simple logging utility for changelog generation.
+*
+* @remarks
+* Provides environment-aware warning output:
+* - **GitHub Actions**: emits `::warning::` annotations that surface in
+*   the Actions UI
+* - **Local development**: falls back to `console.warn`
+* - **Test environment**: suppressed entirely when `process.env.VITEST`
+*   is set, preventing noisy test output
+*
+* @internal
+*/
+/**
+* Log a warning message.
+*
+* @remarks
+* Detection order:
+* 1. If `process.env.VITEST` is set, the message is silently discarded.
+* 2. If `process.env.GITHUB_ACTIONS === "true"`, the message is emitted
+*    as a `::warning::` annotation.
+* 3. Otherwise, `console.warn` is used.
+*
+* @param message - The warning message
+* @param args - Additional arguments (concatenated with a space in CI mode)
+*
+* @example
+* ```typescript
+* import { logWarning } from "../utils/logger.js";
+*
+* logWarning("Duplicate dependency entry", "effect@3.19.0");
+* // In CI: "::warning::Duplicate dependency entry effect@3.19.0"
+* // Locally: console.warn("Duplicate dependency entry", "effect@3.19.0")
+* ```
+*
+* @internal
+*/
+function logWarning(message, ...args) {
+	/* v8 ignore start — environment-specific */
+	if (typeof process !== "undefined" && process.env.VITEST) return;
+	if (typeof process !== "undefined" && process.env.GITHUB_ACTIONS === "true") {
+		const text = args.length > 0 ? `${message} ${args.join(" ")}` : message;
+		console.warn(`::warning::${text}`);
+	} else console.warn(message, ...args);
+	/* v8 ignore stop */
+}
+
+//#endregion
+export { logWarning };

package/changesets/utils/markdown-link.js

@@ -0,0 +1,57 @@
+//#region src/changesets/utils/markdown-link.ts
+/**
+* Markdown link extraction utilities.
+*
+* @remarks
+* Handles the inconsistency where `\@changesets/get-github-info` sometimes
+* returns markdown-formatted links (e.g., `[#17](https://...)`) instead
+* of plain URLs. Provides a regex pattern and extraction function to
+* normalize these values.
+*
+* @see {@link Changelog} for the public API that uses link extraction
+*   during changelog generation
+*
+* @internal
+*/
+/**
+* Pattern matching markdown link format: `[text](url)`.
+*
+* Capture groups:
+* - `[1]` — link text (e.g., `#17`)
+* - `[2]` — URL (e.g., `https://github.com/owner/repo/pull/17`)
+*
+* @internal
+*/
+const MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/;
+/**
+* Extract a plain URL from a markdown-formatted link.
+*
+* @remarks
+* The `\@changesets/get-github-info` package sometimes returns markdown links
+* like `[#17](https://github.com/owner/repo/pull/17)` instead of plain URLs.
+* This helper extracts the URL portion, or returns the input unchanged if
+* it is already a plain URL.
+*
+* @param linkOrUrl - A markdown link or plain URL string
+* @returns The extracted plain URL
+*
+* @example
+* ```typescript
+* import { extractUrlFromMarkdown } from "../utils/markdown-link.js";
+*
+* extractUrlFromMarkdown("[#17](https://github.com/o/r/pull/17)");
+* // "https://github.com/o/r/pull/17"
+*
+* extractUrlFromMarkdown("https://github.com/o/r/pull/17");
+* // "https://github.com/o/r/pull/17" (returned unchanged)
+* ```
+*
+* @internal
+*/
+function extractUrlFromMarkdown(linkOrUrl) {
+	const match = MARKDOWN_LINK_PATTERN.exec(linkOrUrl);
+	return match ? match[2] : linkOrUrl;
+}
+
+//#endregion
+export { MARKDOWN_LINK_PATTERN, extractUrlFromMarkdown };

package/changesets/utils/publishability.js

@@ -0,0 +1,39 @@
+import { Effect } from "effect";
+import { PublishabilityDetector } from "workspaces-effect";
+
+//#region src/changesets/utils/publishability.ts
+/**
+* Publishability helpers for the changeset CLI commands.
+*
+* @remarks
+* Provides `listPublishablePackageNames`, a convenience wrapper around
+* {@link PublishabilityDetector} that returns a `Set<string>` of
+* publishable package names. Used by the `deps detect` and `deps regen`
+* commands to filter out workspace packages whose dependency changes
+* would never reach a release.
+*
+* @packageDocumentation
+*/
+/**
+* Compute the set of currently-publishable workspace package names.
+*
+* @remarks
+* Uses the currently-active {@link PublishabilityDetector} — wire the
+* {@link SilkPublishabilityDetectorLive} layer to get silk semantics.
+*
+* @param packages - The workspace packages to evaluate
+* @returns An Effect yielding a `Set` of publishable package names
+*
+* @public
+*/
+function listPublishablePackageNames(packages) {
+	return Effect.gen(function* () {
+		const detector = yield* PublishabilityDetector;
+		const names = /* @__PURE__ */ new Set();
+		for (const pkg of packages) if ((yield* detector.detect(pkg, pkg.path)).length > 0) names.add(pkg.name);
+		return names;
+	});
+}
+
+//#endregion
+export { listPublishablePackageNames };

package/changesets/utils/remark-pipeline.js

@@ -0,0 +1,79 @@
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkStringify from "remark-stringify";
+import { unified } from "unified";
+
+//#region src/changesets/utils/remark-pipeline.ts
+/**
+* Create a unified processor configured with remark-parse, remark-gfm,
+* and remark-stringify.
+*
+* @remarks
+* Each call creates a fresh processor instance. The plugin chain is:
+* 1. `remark-parse` — markdown to MDAST
+* 2. `remark-gfm` — GitHub Flavored Markdown extensions (tables, etc.)
+* 3. `remark-stringify` — MDAST back to markdown
+*
+* @privateRemarks
+* Return type is intentionally inferred because the unified `Processor`
+* generic signature is complex and parameterized by the plugin chain.
+*
+* @returns A configured unified processor
+*
+* @internal
+*/
+function createRemarkProcessor() {
+	return unified().use(remarkParse).use(remarkGfm).use(remarkStringify);
+}
+/**
+* Parse a markdown string into an MDAST AST synchronously.
+*
+* @remarks
+* Uses {@link createRemarkProcessor} internally. The returned tree
+* includes GFM extensions (tables, strikethrough, etc.) thanks to
+* the remark-gfm plugin.
+*
+* @param content - Raw markdown string
+* @returns The parsed MDAST root node
+*
+* @example
+* ```typescript
+* import { parseMarkdown } from "../utils/remark-pipeline.js";
+*
+* const tree = parseMarkdown("## Version 1.0.0\n\nInitial release.");
+* // tree.type === "root"
+* // tree.children[0].type === "heading"
+* ```
+*
+* @internal
+*/
+function parseMarkdown(content) {
+	return createRemarkProcessor().parse(content);
+}
+/**
+* Stringify an MDAST AST back to a markdown string synchronously.
+*
+* @remarks
+* Uses {@link createRemarkProcessor} internally. GFM constructs
+* (tables, etc.) are serialized correctly thanks to the remark-gfm plugin.
+*
+* @param tree - The MDAST root node
+* @returns The serialized markdown string
+*
+* @example
+* ```typescript
+* import { parseMarkdown, stringifyMarkdown } from "../utils/remark-pipeline.js";
+*
+* const tree = parseMarkdown("# Hello\n\nWorld.");
+* const md = stringifyMarkdown(tree);
+* // "# Hello\n\nWorld.\n"
+* ```
+*
+* @internal
+*/
+function stringifyMarkdown(tree) {
+	return createRemarkProcessor().stringify(tree);
+}
+
+//#endregion
+export { parseMarkdown, stringifyMarkdown };

package/changesets/utils/section-parser.js

@@ -0,0 +1,94 @@
+import { fromHeading } from "../categories/index.js";
+import { parseMarkdown, stringifyMarkdown } from "./remark-pipeline.js";
+import { toString } from "mdast-util-to-string";
+
+//#region src/changesets/utils/section-parser.ts
+/**
+* Parse a changeset summary into structured sections.
+*
+* @remarks
+* The algorithm works in three steps:
+* 1. Parse the summary markdown into an MDAST tree via {@link parseMarkdown}
+* 2. Scan `tree.children` for h2 (`depth === 2`) headings, recording their
+*    indices
+* 3. For each h2, extract the heading text, resolve it to a
+*    {@link SectionCategory} via `fromHeading()`, and collect all nodes
+*    between this h2 and the next h2 (or end of document) as the section
+*    content
+*
+* If the summary contains h2 (`##`) headings, they are mapped to categories
+* via `fromHeading()`. Content between headings becomes the section content.
+* Content before the first h2 becomes the preamble.
+*
+* If no h2 headings are present, the entire content is returned as the preamble
+* with an empty sections array (backward-compatible flat-text mode).
+*
+* Unknown headings (those not recognized by `fromHeading()`) are silently
+* skipped; validation of heading names is the responsibility of Layer 1
+* (remark-lint).
+*
+* @param summary - The changeset summary markdown
+* @returns Parsed sections and optional preamble
+*
+* @example
+* ```typescript
+* import { parseChangesetSections } from "../utils/section-parser.js";
+*
+* const result = parseChangesetSections("## Features\n\n- New API\n\n## Bug Fixes\n\n- Fixed crash");
+* // result.sections.length === 2
+* // result.sections[0].category === "Features"
+* // result.preamble === undefined
+* ```
+*
+* @internal
+*/
+function parseChangesetSections(summary) {
+	const tree = parseMarkdown(summary);
+	const h2Indices = [];
+	for (let i = 0; i < tree.children.length; i++) {
+		const node = tree.children[i];
+		if (node.type === "heading" && node.depth === 2) h2Indices.push(i);
+	}
+	if (h2Indices.length === 0) return {
+		preamble: summary.trim(),
+		sections: []
+	};
+	const result = { sections: [] };
+	if (h2Indices[0] > 0) result.preamble = stringifyAstSlice(tree.children.slice(0, h2Indices[0]));
+	for (let i = 0; i < h2Indices.length; i++) {
+		const headingIndex = h2Indices[i];
+		const headingNode = tree.children[headingIndex];
+		const headingText = toString(headingNode);
+		const nextIndex = i + 1 < h2Indices.length ? h2Indices[i + 1] : tree.children.length;
+		const content = stringifyAstSlice(tree.children.slice(headingIndex + 1, nextIndex));
+		const category = fromHeading(headingText);
+		if (category) result.sections.push({
+			category,
+			heading: headingText,
+			content
+		});
+	}
+	return result;
+}
+/**
+* Stringify a slice of MDAST nodes back to markdown.
+*
+* @remarks
+* Wraps the nodes in a synthetic root node and delegates to
+* {@link stringifyMarkdown}. Returns an empty string for empty slices.
+*
+* @param nodes - Array of MDAST content nodes
+* @returns Trimmed markdown string, or empty string if no nodes
+*
+* @internal
+*/
+function stringifyAstSlice(nodes) {
+	if (nodes.length === 0) return "";
+	return stringifyMarkdown({
+		type: "root",
+		children: nodes
+	}).trim();
+}
+
+//#endregion
+export { parseChangesetSections };

package/changesets/utils/strip-frontmatter.js

@@ -0,0 +1,46 @@
+//#region src/changesets/utils/strip-frontmatter.ts
+/**
+* Utility for stripping YAML frontmatter from changeset files.
+*
+* @remarks
+* Changeset `.md` files produced by `\@changesets/cli` contain YAML
+* frontmatter (delimited by `---`) specifying which packages are
+* affected and their version bump types. This frontmatter must be
+* removed before remark-lint processing, as remark-parse does not
+* handle YAML frontmatter natively without `remark-frontmatter`.
+*
+* The regex used is non-greedy (`[\s\S]*?`) to match only the first
+* frontmatter block and avoid stripping content after a second `---`
+* delimiter that might appear in the document body.
+*
+* @see {@link ChangesetLinter} for the public API that uses frontmatter
+*   stripping during changeset validation
+*
+* @internal
+*/
+/**
+* Strip leading YAML frontmatter from a markdown string.
+*
+* Removes the `---\n...\n---\n` block at the start of the content.
+* If no frontmatter is present, the content is returned as-is.
+*
+* @param content - Raw markdown string potentially containing frontmatter
+* @returns The markdown content with frontmatter removed
+*
+* @example
+* ```typescript
+* import { stripFrontmatter } from "../utils/strip-frontmatter.js";
+*
+* const raw = "---\n\"pkg\": minor\n---\n\n## Features\n\n- New API";
+* const body = stripFrontmatter(raw);
+* // "\n## Features\n\n- New API"
+* ```
+*
+* @internal
+*/
+function stripFrontmatter(content) {
+	return content.replace(/^---\n[\s\S]*?\n---\n?/, "");
+}
+
+//#endregion
+export { stripFrontmatter };