@savvy-web/silk-effects 0.6.1 → 1.0.0

package/changesets/services/workspace-snapshot.js

@@ -0,0 +1,182 @@
+import { GitError } from "../errors.js";
+import { Context, Effect, Layer } from "effect";
+import { execFileSync } from "node:child_process";
+
+//#region src/changesets/services/workspace-snapshot.ts
+/**
+* Read workspace package snapshots at arbitrary git refs.
+*
+* @remarks
+* `WorkspaceDiscovery` reads the **current** workspace state. To compute
+* dependency diffs between two points in time, we also need to read
+* `pnpm-workspace.yaml` and each `package.json` as they existed at a
+* specific commit. This service shells out to `git show <ref>:<path>`
+* for each file, returns a plain-object snapshot per workspace package,
+* and caches per `(cwd, ref)` pair.
+*
+* The snapshot intentionally returns plain objects rather than
+* `WorkspacePackage` instances — `WorkspacePackage` is a `Schema.Class`
+* tightly coupled to the live filesystem, and snapshot consumers only
+* need the declared dependency records to compute a diff.
+*
+* @see {@link WorkspaceSnapshotReader} for the service tag
+* @see {@link WorkspaceSnapshotReaderLive} for the production layer
+*
+* @packageDocumentation
+*/
+const _tag = Context.Tag("WorkspaceSnapshotReader");
+/**
+* @internal
+*/
+const WorkspaceSnapshotReaderBase = _tag();
+/**
+* Effect service tag for {@link WorkspaceSnapshotReaderShape}.
+*
+* @public
+*/
+var WorkspaceSnapshotReader = class extends WorkspaceSnapshotReaderBase {};
+function runGitShow(cwd, ref, path) {
+	return Effect.try({
+		try: () => execFileSync("git", ["show", `${ref}:${path}`], {
+			cwd,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		}),
+		catch: (error) => {
+			const stderr = error.stderr;
+			const text = typeof stderr === "string" ? stderr : stderr?.toString() ?? "";
+			if (/exists on disk, but not in|does not exist|unknown revision|bad object/.test(text)) return new GitError({
+				command: `git show ${ref}:${path}`,
+				cwd,
+				reason: "PATH_NOT_AT_REF"
+			});
+			return new GitError({
+				command: `git show ${ref}:${path}`,
+				cwd,
+				reason: text.trim() || (error.message ?? String(error))
+			});
+		}
+	}).pipe(Effect.catchTag("GitError", (err) => err.reason === "PATH_NOT_AT_REF" ? Effect.succeed(null) : Effect.fail(err)));
+}
+/**
+* Parse a minimal `pnpm-workspace.yaml` (`packages:` list only). Tolerant
+* of comments and varied indentation; rejects on missing `packages:` key.
+*/
+function parseWorkspaceGlobs(yamlText) {
+	const lines = yamlText.split(/\r?\n/);
+	const globs = [];
+	let inPackagesBlock = false;
+	for (const line of lines) {
+		if (/^\s*#/.test(line)) continue;
+		if (/^\s*packages\s*:\s*$/.test(line)) {
+			inPackagesBlock = true;
+			continue;
+		}
+		if (inPackagesBlock) {
+			const match = line.match(/^\s+-\s+["']?(.+?)["']?\s*$/);
+			if (match) {
+				globs.push(match[1]);
+				continue;
+			}
+			if (line.length > 0 && !line.startsWith(" ") && !line.startsWith("	")) inPackagesBlock = false;
+		}
+	}
+	return globs;
+}
+function toSnapshot(pkg, relativePath) {
+	if (!pkg.name) return null;
+	return {
+		name: pkg.name,
+		relativePath,
+		version: pkg.version ?? "0.0.0",
+		dependencies: pkg.dependencies ?? {},
+		devDependencies: pkg.devDependencies ?? {},
+		peerDependencies: pkg.peerDependencies ?? {},
+		optionalDependencies: pkg.optionalDependencies ?? {}
+	};
+}
+/**
+* Expand a workspace glob like `packages/*` or `apps/web` against the
+* directories present at the given git ref. We can't `globSync` here
+* (the directories may not be on disk at this ref); instead we use
+* `git ls-tree` to enumerate paths.
+*/
+function expandGlobAtRef(cwd, ref, glob) {
+	return Effect.gen(function* () {
+		const cleanGlob = glob.replace(/\/\*\*$/, "/*");
+		if (!cleanGlob.includes("*") && !cleanGlob.includes("?")) return [cleanGlob];
+		const prefix = cleanGlob.includes("/") ? cleanGlob.slice(0, cleanGlob.lastIndexOf("/") + 1) : "";
+		const entries = (yield* Effect.try({
+			try: () => execFileSync("git", [
+				"ls-tree",
+				"--name-only",
+				ref,
+				prefix
+			], {
+				cwd,
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			}),
+			catch: (error) => {
+				const stderr = error.stderr;
+				const text = typeof stderr === "string" ? stderr : stderr?.toString() ?? "";
+				return new GitError({
+					command: `git ls-tree ${ref} ${prefix}`,
+					cwd,
+					reason: text.trim() || (error.message ?? String(error))
+				});
+			}
+		})).split(/\r?\n/).map((s) => s.trim()).filter((s) => s.length > 0);
+		const regex = new RegExp(`^${cleanGlob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")}$`);
+		return entries.filter((e) => regex.test(e));
+	});
+}
+function makeShape() {
+	const cache = /* @__PURE__ */ new Map();
+	const snapshotAt = (cwd, ref) => Effect.gen(function* () {
+		const cacheKey = `${cwd}::${ref}`;
+		const cached = cache.get(cacheKey);
+		if (cached) return cached;
+		const wsYaml = yield* runGitShow(cwd, ref, "pnpm-workspace.yaml");
+		const globs = wsYaml ? parseWorkspaceGlobs(wsYaml) : [];
+		const dirs = [];
+		for (const glob of globs) {
+			const expanded = yield* expandGlobAtRef(cwd, ref, glob);
+			for (const d of expanded) if (!dirs.includes(d)) dirs.push(d);
+		}
+		if (!dirs.includes(".")) dirs.unshift(".");
+		const snapshots = [];
+		for (const dir of dirs) {
+			const pkgText = yield* runGitShow(cwd, ref, dir === "." ? "package.json" : `${dir}/package.json`);
+			if (!pkgText) continue;
+			let parsed;
+			try {
+				parsed = JSON.parse(pkgText);
+			} catch {
+				continue;
+			}
+			const snap = toSnapshot(parsed, dir);
+			if (snap) snapshots.push(snap);
+		}
+		cache.set(cacheKey, snapshots);
+		return snapshots;
+	});
+	return { snapshotAt };
+}
+/**
+* Production layer for {@link WorkspaceSnapshotReader}.
+*
+* @public
+*/
+const WorkspaceSnapshotReaderLive = Layer.succeed(WorkspaceSnapshotReader, makeShape());
+
+//#endregion
+export { WorkspaceSnapshotReader, WorkspaceSnapshotReaderBase, WorkspaceSnapshotReaderLive };

package/changesets/utils/commit-parser.js

@@ -0,0 +1,80 @@
+//#region src/changesets/utils/commit-parser.ts
+/**
+* Conventional commit message parsing.
+*
+* Implements a parser for the
+* {@link https://www.conventionalcommits.org/ | Conventional Commits}
+* specification, extracting type, scope, breaking-change indicator,
+* description, and body from commit messages.
+*
+* @remarks
+* The parser uses a single regex pass for the first line, then splits
+* remaining lines to extract the body. Non-conventional messages are
+* returned with only the `description` field populated (set to the
+* full message text).
+*
+* @see {@link Changelog} for the public API that consumes parsed commits
+*
+* @internal
+*/
+/**
+* Matches conventional commit format: `type(scope)!: description`.
+*
+* Capture groups:
+* - `[1]` — commit type (e.g., `feat`, `fix`)
+* - `[2]` — optional scope (e.g., `api`, `ui`)
+* - `[3]` — optional `!` breaking-change indicator
+* - `[4]` — description text after the colon
+*
+* @internal
+*/
+const CONVENTIONAL_COMMIT_PATTERN = /^(\w+)(?:\(([^)]+)\))?(!)?\s*:\s*(.+)/;
+/**
+* Parse a commit message following the Conventional Commits specification.
+*
+* Supports the full format: `type(scope)!: description\n\nbody`
+*
+* @remarks
+* The algorithm first attempts to match the first line against the
+* conventional commit pattern. If matched, the type, optional scope,
+* optional breaking indicator, and description are extracted. The body
+* is everything after the first line, trimmed. If the message does not
+* match, a fallback result with only the `description` set to the raw
+* message is returned.
+*
+* @param message - The commit message to parse
+* @returns Parsed components; only `description` is guaranteed present
+*
+* @example
+* ```typescript
+* import { parseCommitMessage } from "../utils/commit-parser.js";
+*
+* const result = parseCommitMessage("feat(api)!: add v2 routes\n\nBREAKING CHANGE: v1 removed");
+* // result.type === "feat"
+* // result.scope === "api"
+* // result.breaking === true
+* // result.description === "add v2 routes"
+* // result.body === "BREAKING CHANGE: v1 removed"
+* ```
+*
+* @internal
+*/
+function parseCommitMessage(message) {
+	const match = CONVENTIONAL_COMMIT_PATTERN.exec(message);
+	if (match) {
+		const [, type, scope, bang, description] = match;
+		const body = message.split("\n").slice(1).join("\n").trim();
+		const result = {
+			type,
+			description: description.trim()
+		};
+		if (scope) result.scope = scope;
+		if (bang === "!") result.breaking = true;
+		if (body) result.body = body;
+		return result;
+	}
+	return { description: message };
+}
+
+//#endregion
+export { parseCommitMessage };

package/changesets/utils/dep-diff.js

@@ -0,0 +1,77 @@
+import { sortDependencyRows } from "./dependency-table.js";
+
+//#region src/changesets/utils/dep-diff.ts
+const EM_DASH = "—";
+const DEP_TYPE_MAP = [
+	["dependencies", "dependency"],
+	["devDependencies", "devDependency"],
+	["peerDependencies", "peerDependency"],
+	["optionalDependencies", "optionalDependency"]
+];
+function diffOneRecord(before, after, type) {
+	const rows = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const [name, beforeVersion] of Object.entries(before)) {
+		seen.add(name);
+		const afterVersion = after[name];
+		if (afterVersion === void 0) rows.push({
+			dependency: name,
+			type,
+			action: "removed",
+			from: beforeVersion,
+			to: EM_DASH
+		});
+		else if (afterVersion !== beforeVersion) rows.push({
+			dependency: name,
+			type,
+			action: "updated",
+			from: beforeVersion,
+			to: afterVersion
+		});
+	}
+	for (const [name, afterVersion] of Object.entries(after)) {
+		if (seen.has(name)) continue;
+		rows.push({
+			dependency: name,
+			type,
+			action: "added",
+			from: EM_DASH,
+			to: afterVersion
+		});
+	}
+	return rows;
+}
+/**
+* Diff two workspace snapshots and return per-package dependency-table rows.
+*
+* @param before - Snapshot at the older ref (typically the merge base). Pass
+*   `null` for workspace packages that did not exist at the older ref — every
+*   declared dep is then reported as `"added"`.
+* @param after - Snapshot at the newer ref (typically the working tree).
+* @returns One {@link WorkspaceDependencyDiff} entry per workspace package
+*   that has at least one row. Packages with no changes are omitted.
+*
+* @public
+*/
+function computeWorkspaceDependencyDiffs(beforeSnapshots, afterSnapshots) {
+	const beforeByName = new Map(beforeSnapshots.map((s) => [s.name, s]));
+	const result = [];
+	for (const after of afterSnapshots) {
+		const before = beforeByName.get(after.name);
+		const rows = [];
+		for (const [field, type] of DEP_TYPE_MAP) {
+			const beforeRecord = before?.[field] ?? {};
+			const afterRecord = after[field];
+			rows.push(...diffOneRecord(beforeRecord, afterRecord, type));
+		}
+		if (rows.length > 0) result.push({
+			package: after.name,
+			relativePath: after.relativePath,
+			rows: sortDependencyRows(rows)
+		});
+	}
+	return result;
+}
+
+//#endregion
+export { computeWorkspaceDependencyDiffs };

package/changesets/utils/dependency-table.js

@@ -0,0 +1,347 @@
+import { DependencyTableRowSchema } from "../schemas/dependency-table.js";
+import { Schema } from "effect";
+import remarkGfm from "remark-gfm";
+import remarkStringify from "remark-stringify";
+import { unified } from "unified";
+import { toString } from "mdast-util-to-string";
+
+//#region src/changesets/utils/dependency-table.ts
+/**
+* Dependency table utilities for parsing, serializing, collapsing, and sorting
+* dependency table rows between MDAST table nodes and typed representations.
+*
+* @remarks
+* This module provides the low-level functional primitives that the
+* {@link DependencyTable} class wraps with a stateful, fluent API.
+* It operates on arrays of `DependencyTableRow` objects and MDAST `Table`
+* nodes, converting between the two representations.
+*
+* The collapse algorithm merges rows sharing the same `dependency + type`
+* key, applying semantic rules (e.g., added then removed = net zero).
+* Sorting follows a stable order: removed, updated, added, then
+* alphabetically by type and dependency name.
+*
+* @see {@link DependencyTable} for the public class-based API
+*
+* @internal
+*/
+/**
+* Ordered column headers for dependency tables.
+*
+* Defines the canonical header row: `Dependency | Type | Action | From | To`.
+*
+* @internal
+*/
+const COLUMN_HEADERS = [
+	"Dependency",
+	"Type",
+	"Action",
+	"From",
+	"To"
+];
+/**
+* Property keys on {@link DependencyTableRow} corresponding to each column
+* in {@link COLUMN_HEADERS}.
+*
+* Used to map between positional table cells and typed object fields.
+*
+* @internal
+*/
+const COLUMN_KEYS = [
+	"dependency",
+	"type",
+	"action",
+	"from",
+	"to"
+];
+/** Schema decoder for validating raw cell values into a typed row. */
+const decode = Schema.decodeUnknownSync(DependencyTableRowSchema);
+/**
+* Parse an MDAST table node into validated dependency table rows.
+*
+* @remarks
+* Validates the header row against {@link COLUMN_HEADERS} (case-insensitive),
+* then decodes each data row through the `DependencyTableRowSchema` for
+* type-safe validation of action values, version strings, and dependency types.
+*
+* @param table - An MDAST `Table` node (from remark-gfm)
+* @returns Array of validated `DependencyTableRow` objects
+* @throws If the table has fewer than 2 rows (header + at least one data row)
+* @throws If the header columns do not match the expected column names
+* @throws If any data row fails schema validation
+*
+* @example
+* ```typescript
+* import { parseDependencyTable } from "../utils/dependency-table.js";
+* import { parseMarkdown } from "../utils/remark-pipeline.js";
+* import type { Table } from "mdast";
+*
+* const tree = parseMarkdown("| Dependency | Type | Action | From | To |\n| --- | --- | --- | --- | --- |\n| foo | dependency | added | — | 1.0.0 |");
+* const table = tree.children.find((n) => n.type === "table") as Table;
+* const rows = parseDependencyTable(table);
+* // rows[0].dependency === "foo"
+* ```
+*
+* @internal
+*/
+function parseDependencyTable(table) {
+	const rows = table.children;
+	if (rows.length < 2) throw new Error("Dependency table must have at least one data row");
+	const headers = rows[0].children.map((cell) => toString(cell).trim().toLowerCase());
+	const expected = COLUMN_HEADERS.map((h) => h.toLowerCase());
+	if (headers.length !== expected.length || !headers.every((h, i) => h === expected[i])) throw new Error(`Table must have columns: ${COLUMN_HEADERS.join(", ")}. Got: ${headers.join(", ")}`);
+	const result = [];
+	for (let i = 1; i < rows.length; i++) {
+		const cells = rows[i].children;
+		const raw = {};
+		for (let c = 0; c < COLUMN_KEYS.length; c++) raw[COLUMN_KEYS[c]] = toString(cells[c]).trim();
+		result.push(decode(raw));
+	}
+	return result;
+}
+/**
+* Create a table cell with a text node.
+*
+* @param text - The cell text content
+* @returns An MDAST `TableCell` node
+*
+* @internal
+*/
+function makeCell(text) {
+	return {
+		type: "tableCell",
+		children: [{
+			type: "text",
+			value: text
+		}]
+	};
+}
+/**
+* Create a table row from an array of cell texts.
+*
+* @param texts - Array of cell text values
+* @returns An MDAST `TableRow` node
+*
+* @internal
+*/
+function makeRow(texts) {
+	return {
+		type: "tableRow",
+		children: texts.map(makeCell)
+	};
+}
+/**
+* Serialize dependency table rows into an MDAST `Table` node.
+*
+* @remarks
+* Creates a well-formed GFM table with the canonical header row
+* ({@link COLUMN_HEADERS}) followed by one data row per entry.
+* The inverse of {@link parseDependencyTable}.
+*
+* @param rows - Array of `DependencyTableRow` objects
+* @returns An MDAST `Table` node ready for insertion into an AST
+*
+* @example
+* ```typescript
+* import { serializeDependencyTable } from "../utils/dependency-table.js";
+* import type { DependencyTableRow } from "../schemas/dependency-table.js";
+*
+* const rows: DependencyTableRow[] = [
+*   { dependency: "effect", type: "dependency", action: "updated", from: "3.18.0", to: "3.19.0" },
+* ];
+* const table = serializeDependencyTable(rows);
+* // table.type === "table"
+* // table.children.length === 2 (header + 1 data row)
+* ```
+*
+* @internal
+*/
+function serializeDependencyTable(rows) {
+	return {
+		type: "table",
+		children: [makeRow([...COLUMN_HEADERS]), ...rows.map((row) => makeRow(COLUMN_KEYS.map((key) => row[key])))]
+	};
+}
+/**
+* Serialize dependency table rows to a markdown table string.
+*
+* @remarks
+* Combines {@link serializeDependencyTable} with unified/remark-gfm/remark-stringify
+* to produce a ready-to-use GFM markdown table string. The result is trimmed
+* of leading/trailing whitespace.
+*
+* @param rows - Array of `DependencyTableRow` objects
+* @returns Markdown table string (GFM format)
+*
+* @example
+* ```typescript
+* import { serializeDependencyTableToMarkdown } from "../utils/dependency-table.js";
+* import type { DependencyTableRow } from "../schemas/dependency-table.js";
+*
+* const rows: DependencyTableRow[] = [
+*   { dependency: "effect", type: "dependency", action: "updated", from: "3.18.0", to: "3.19.0" },
+* ];
+* const md = serializeDependencyTableToMarkdown(rows);
+* // "| Dependency | Type | Action | From | To |\n| --- | --- | ..."
+* ```
+*
+* @internal
+*/
+function serializeDependencyTableToMarkdown(rows) {
+	const tree = {
+		type: "root",
+		children: [serializeDependencyTable(rows)]
+	};
+	return unified().use(remarkGfm).use(remarkStringify).stringify(tree).trim();
+}
+/**
+* Sort priority for dependency actions: removed first, then updated, then added.
+*
+* @remarks
+* Used by {@link sortDependencyRows} for primary sort ordering. The numeric
+* values define the sort position (lower = earlier in the sorted output).
+*
+* @internal
+*/
+const ACTION_ORDER = {
+	removed: 0,
+	updated: 1,
+	added: 2
+};
+/**
+* Collapse dependency table rows with the same `dependency + type` key.
+*
+* @remarks
+* When multiple changelog entries affect the same dependency, this function
+* merges them into a single row using semantic collapse rules. Rows are
+* grouped by a composite key of `dependency\0type` (null-byte separated).
+*
+* The collapse rules applied by {@link collapseTwo} are:
+*
+* | First action | Second action | Result |
+* |---|---|---|
+* | `updated` | `updated` | `updated` (earliest `from`, latest `to`) |
+* | `added` | `updated` | `added` (final `to`) |
+* | `added` | `removed` | dropped (net zero change) |
+* | `updated` | `removed` | `removed` (original `from`) |
+* | `removed` | `added` | `updated` (original `from`, new `to`) |
+* | other | other | keep later entry |
+*
+* @param rows - Array of `DependencyTableRow` objects (in chronological order)
+* @returns Collapsed array with at most one row per `dependency + type` pair
+*
+* @example
+* ```typescript
+* import { collapseDependencyRows } from "../utils/dependency-table.js";
+* import type { DependencyTableRow } from "../schemas/dependency-table.js";
+*
+* const rows: DependencyTableRow[] = [
+*   { dependency: "effect", type: "dependency", action: "updated", from: "3.17.0", to: "3.18.0" },
+*   { dependency: "effect", type: "dependency", action: "updated", from: "3.18.0", to: "3.19.0" },
+* ];
+* const collapsed = collapseDependencyRows(rows);
+* // collapsed[0].from === "3.17.0", collapsed[0].to === "3.19.0"
+* ```
+*
+* @see {@link DependencyTable} for the public API that wraps this function
+*
+* @internal
+*/
+function collapseDependencyRows(rows) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const key = `${row.dependency}\0${row.type}`;
+		const existing = groups.get(key);
+		if (!existing) {
+			groups.set(key, { ...row });
+			continue;
+		}
+		const merged = collapseTwo(existing, row);
+		if (merged === null) groups.delete(key);
+		else groups.set(key, merged);
+	}
+	return [...groups.values()];
+}
+/**
+* Collapse two rows sharing the same `dependency + type` key into one,
+* or return `null` if they cancel out (net zero).
+*
+* @remarks
+* This is the core merge function called by {@link collapseDependencyRows}.
+* It applies the semantic collapse rules based on the action pair.
+* See {@link collapseDependencyRows} for the full rule table.
+*
+* @param first - The earlier (existing) row
+* @param second - The later (incoming) row
+* @returns The merged row, or `null` to drop the entry entirely
+*
+* @internal
+*/
+function collapseTwo(first, second) {
+	const a = first.action;
+	const b = second.action;
+	if (a === "updated" && b === "updated") return {
+		...first,
+		to: second.to
+	};
+	if (a === "added" && b === "updated") return {
+		...first,
+		to: second.to
+	};
+	if (a === "added" && b === "removed") return null;
+	if (a === "updated" && b === "removed") return {
+		...first,
+		action: "removed",
+		to: "—"
+	};
+	if (a === "removed" && b === "added") return {
+		...first,
+		action: "updated",
+		to: second.to
+	};
+	return { ...second };
+}
+/**
+* Sort dependency table rows into canonical display order.
+*
+* @remarks
+* Applies a three-level stable sort:
+* 1. **Action** — `removed` first, then `updated`, then `added`
+*    (per {@link ACTION_ORDER})
+* 2. **Type** — alphabetically (e.g., `config` before `dependency`)
+* 3. **Dependency name** — alphabetically within each action+type group
+*
+* Returns a new array; the input is not mutated.
+*
+* @param rows - Array of `DependencyTableRow` objects
+* @returns New sorted array
+*
+* @example
+* ```typescript
+* import { sortDependencyRows } from "../utils/dependency-table.js";
+* import type { DependencyTableRow } from "../schemas/dependency-table.js";
+*
+* const rows: DependencyTableRow[] = [
+*   { dependency: "zod", type: "dependency", action: "added", from: "\u2014", to: "3.0.0" },
+*   { dependency: "effect", type: "dependency", action: "removed", from: "3.19.0", to: "\u2014" },
+* ];
+* const sorted = sortDependencyRows(rows);
+* // sorted[0].dependency === "effect" (removed comes first)
+* ```
+*
+* @see {@link DependencyTable} for the public API that wraps this function
+*
+* @internal
+*/
+function sortDependencyRows(rows) {
+	return [...rows].sort((a, b) => {
+		const actionDiff = (ACTION_ORDER[a.action] ?? 99) - (ACTION_ORDER[b.action] ?? 99);
+		if (actionDiff !== 0) return actionDiff;
+		const typeDiff = a.type.localeCompare(b.type);
+		if (typeDiff !== 0) return typeDiff;
+		return a.dependency.localeCompare(b.dependency);
+	});
+}
+
+//#endregion
+export { collapseDependencyRows, parseDependencyTable, serializeDependencyTable, serializeDependencyTableToMarkdown, sortDependencyRows };