@savvy-web/silk-effects 0.6.0 → 1.0.0

package/changesets/services/config-inspector.js

@@ -0,0 +1,390 @@
+import { ConfigurationError } from "../errors.js";
+import { ChangesetOptionsSchema } from "../schemas/options.js";
+import { ChangesetConfigReader } from "../../services/ChangesetConfigReader.js";
+import { Context, Effect, Layer, Schema } from "effect";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { globSync } from "tinyglobby";
+import { WorkspaceDiscovery } from "workspaces-effect";
+
+//#region src/changesets/services/config-inspector.ts
+/**
+* `ConfigInspector` service — surface the project's `.changeset/config.json`
+* in a structured, validated form that agents and tooling can consume.
+*
+* @remarks
+* The inspector handles three responsibilities that the schemas alone cannot:
+*
+* 1. **Legacy normalization.** Configs from 0.8.x still use the flat
+*    top-level `versionFiles[]` array. When that field is populated, the
+*    inspector emits a one-line deprecation warning to stderr (naming the
+*    config path and the required edit) and folds each legacy entry into
+*    the equivalent `packages[entry.package].versionFiles` shape for
+*    downstream consumers. Removed in 1.0.0.
+* 2. **Resolution against the workspace.** Each `packages` key must resolve
+*    to a known workspace package via `WorkspaceDiscovery`. Unknown keys
+*    surface as a {@link ConfigurationError}. The inspector returns the
+*    package's absolute workspace directory alongside the resolved scope.
+* 3. **Overlap detection.** Cross-package validation rules that the schemas
+*    cannot enforce:
+*    - `additionalScopes` of two different packages must not overlap.
+*    - `additionalScopes` of one package must not shadow another package's
+*      workspace directory.
+*    - Two `versionFiles` entries (within or across packages) must not
+*      resolve to the same `(file, $.path)` tuple.
+*
+* Validation is performed eagerly on the first {@link ConfigInspectorShape.inspect}
+* call. The resolved state is cached internally per `cwd` so subsequent
+* {@link ConfigInspectorShape.classify} calls reuse it.
+*
+* @see {@link ConfigInspector} for the Effect service tag
+* @see {@link ConfigInspectorLive} for the production layer
+*
+* @packageDocumentation
+*/
+const _tag = Context.Tag("ConfigInspector");
+/**
+* Base class for {@link ConfigInspector}.
+*
+* @privateRemarks
+* Effect's `Context.Tag` creates an anonymous base class that api-extractor
+* cannot follow without an explicit export. Do not delete.
+*
+* @internal
+*/
+const ConfigInspectorBase = _tag();
+/**
+* Effect service tag for {@link ConfigInspectorShape}.
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import { ConfigInspector, ConfigInspectorLive } from "@savvy-web/changesets";
+*
+* const program = Effect.gen(function* () {
+*   const inspector = yield* ConfigInspector;
+*   const config = yield* inspector.inspect(process.cwd());
+*   return config.packages.map((p) => p.name);
+* });
+*
+* Effect.runPromise(program.pipe(Effect.provide(ConfigInspectorLive)));
+* ```
+*
+* @public
+*/
+var ConfigInspector = class extends ConfigInspectorBase {};
+/**
+* Pull the changelog formatter ID and its options object out of the raw
+* `.changeset/config.json` shape (where `changelog` may be a tuple, a string,
+* or absent).
+*/
+function extractChangelogOptions(config) {
+	const { changelog } = config;
+	if (Array.isArray(changelog)) return {
+		changelogId: typeof changelog[0] === "string" ? changelog[0] : null,
+		options: changelog[1] ?? {}
+	};
+	if (typeof changelog === "string") return {
+		changelogId: changelog,
+		options: {}
+	};
+	return {
+		changelogId: null,
+		options: {}
+	};
+}
+/**
+* Normalize the deprecated top-level `versionFiles[]` array into the
+* equivalent `packages[entry.package].versionFiles` shape. Mutates a fresh
+* copy of the options; never the input.
+*
+* Returns the normalized options and a flag indicating whether normalization
+* happened (so the caller can emit a deprecation warning once per inspect).
+*/
+function normalizeLegacyOptions(options, configPath) {
+	const legacy = options.versionFiles;
+	if (!Array.isArray(legacy) || legacy.length === 0) return {
+		normalized: options,
+		legacyUsed: false
+	};
+	console.warn(`[changesets] DEPRECATION: ${configPath} uses the top-level \`versionFiles\` array. Migrate to \`changelog[1].packages[<name>].versionFiles\`. Removed in 1.0.0.`);
+	const existing = options.packages ?? {};
+	const next = {};
+	for (const [k, v] of Object.entries(existing)) next[k] = { ...v };
+	for (const entry of legacy) {
+		const ownerName = typeof entry.package === "string" ? entry.package : void 0;
+		if (!ownerName) throw new ConfigurationError({
+			field: "versionFiles",
+			reason: `Legacy versionFiles entry { glob: ${JSON.stringify(entry.glob)} } in ${configPath} has no \`package\` field. Path-based owner inference is removed during the 0.9.0 migration — add an explicit \`package\` field, or migrate the entry to \`packages[<name>].versionFiles\`.`
+		});
+		if (!next[ownerName]) next[ownerName] = {};
+		const slot = next[ownerName];
+		const arr = Array.isArray(slot.versionFiles) ? slot.versionFiles.slice() : [];
+		const cleaned = { glob: entry.glob };
+		if (Array.isArray(entry.paths)) cleaned.paths = entry.paths;
+		arr.push(cleaned);
+		slot.versionFiles = arr;
+	}
+	const normalized = {
+		...options,
+		packages: next
+	};
+	delete normalized.versionFiles;
+	return {
+		normalized,
+		legacyUsed: true
+	};
+}
+/**
+* Materialize a glob against `cwd` and return the matched file paths as
+* repo-relative strings. Honors negation patterns and ignores `node_modules`.
+*/
+function materializeGlob(glob, cwd) {
+	return globSync(glob, {
+		cwd,
+		ignore: ["**/node_modules/**"],
+		dot: true
+	});
+}
+/**
+* Determine whether `child` is the same directory as `parent` or sits inside
+* it. Both paths must be absolute.
+*/
+function isInside(parent, child) {
+	const rel = relative(parent, child);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+* Build per-package resolved scopes by intersecting the (possibly normalized)
+* options with workspace info.
+*/
+function buildResolvedScopes(params) {
+	const { options, workspaces, projectDir, configPath } = params;
+	const packages = options.packages ?? {};
+	const workspacesByName = new Map(workspaces.map((w) => [w.name, w]));
+	const scopes = [];
+	for (const [pkgName, scope] of Object.entries(packages)) {
+		const ws = workspacesByName.get(pkgName);
+		if (!ws) throw new ConfigurationError({
+			field: `packages["${pkgName}"]`,
+			reason: `Unknown package "${pkgName}" in ${configPath}. Known workspace packages: ${workspaces.map((w) => w.name).join(", ") || "(none)"}.`
+		});
+		const additionalScopes = scope.additionalScopes ?? [];
+		const additionalScopeFiles = additionalScopes.flatMap((g) => materializeGlob(g, projectDir));
+		const resolvedVersionFiles = (scope.versionFiles ?? []).map((entry) => ({
+			glob: entry.glob,
+			paths: entry.paths ?? ["$.version"],
+			matchedFiles: materializeGlob(entry.glob, projectDir).map((rel) => join(projectDir, rel))
+		}));
+		scopes.push({
+			name: pkgName,
+			workspaceDir: ws.path,
+			version: ws.version,
+			additionalScopes,
+			additionalScopeFiles: additionalScopeFiles.map((rel) => join(projectDir, rel)),
+			versionFiles: resolvedVersionFiles
+		});
+	}
+	return scopes;
+}
+/**
+* Cross-package validation: no overlap in `additionalScopes`, no shadowing
+* of another workspace package's directory (regardless of whether that
+* package is itself declared in `config.packages`), and no duplicate
+* `(file, JSONPath)` tuples in `versionFiles`.
+*/
+function checkConflicts(scopes, allWorkspaces, projectDir, configPath) {
+	const scopeOwner = /* @__PURE__ */ new Map();
+	for (const s of scopes) for (const f of s.additionalScopeFiles) {
+		const prev = scopeOwner.get(f);
+		if (prev && prev !== s.name) throw new ConfigurationError({
+			field: `packages["${s.name}"].additionalScopes`,
+			reason: `Overlap in ${configPath}: file ${JSON.stringify(f)} is matched by both "${prev}" and "${s.name}". additionalScopes must not overlap between packages.`
+		});
+		scopeOwner.set(f, s.name);
+	}
+	for (const s of scopes) for (const f of s.additionalScopeFiles) for (const ws of allWorkspaces) {
+		if (ws.name === s.name) continue;
+		if (ws.path === projectDir) continue;
+		if (isInside(ws.path, f)) throw new ConfigurationError({
+			field: `packages["${s.name}"].additionalScopes`,
+			reason: `Shadowing in ${configPath}: "${s.name}" claims ${JSON.stringify(f)} via additionalScopes, but that path is inside "${ws.name}"'s workspace directory (${ws.path}). A package's additionalScopes must not include another package's workspace files.`
+		});
+	}
+	const seen = /* @__PURE__ */ new Map();
+	for (const s of scopes) for (const vf of s.versionFiles) for (const file of vf.matchedFiles) for (const path of vf.paths) {
+		const key = `${file}::${path}`;
+		const prev = seen.get(key);
+		if (prev && (prev.pkg !== s.name || prev.glob !== vf.glob)) throw new ConfigurationError({
+			field: `packages["${s.name}"].versionFiles`,
+			reason: `Conflict in ${configPath}: target (${JSON.stringify(file)}, ${path}) is claimed by both "${prev.pkg}" (glob ${JSON.stringify(prev.glob)}) and "${s.name}" (glob ${JSON.stringify(vf.glob)}). Two versionFiles entries must not resolve to the same (file, JSONPath) tuple.`
+		});
+		seen.set(key, {
+			pkg: s.name,
+			glob: vf.glob
+		});
+	}
+}
+/**
+* Build a `ConfigurationError` from a Schema `ParseError`. Captures the
+* original message verbatim so the user sees exactly what the schema
+* complained about.
+*/
+function configErrorFromParseError(parseError, configPath) {
+	return new ConfigurationError({
+		field: "options",
+		reason: `Invalid options in ${configPath}: ${String(parseError)}`
+	});
+}
+/**
+* Build a {@link ConfigInspectorShape} that closes over already-resolved
+* service implementations. This keeps the public `inspect`/`classify`
+* signatures requirement-free (`R = never`) while still allowing the
+* implementation to use `ChangesetConfigReader` and `WorkspaceDiscovery`.
+*
+* Each shape carries a private cache keyed by absolute project dir so
+* repeat `inspect`/`classify` calls reuse the materialized state.
+*/
+function makeShape(reader, discovery) {
+	const cache = /* @__PURE__ */ new Map();
+	const inspect = (cwd) => Effect.gen(function* () {
+		const projectDir = resolve(cwd);
+		const cached = cache.get(projectDir);
+		if (cached) return cached;
+		const config = yield* reader.read(projectDir).pipe(Effect.mapError((err) => new ConfigurationError({
+			field: "configFile",
+			reason: err.message
+		})));
+		const configPath = join(projectDir, ".changeset", "config.json");
+		const { changelogId, options: rawOptions } = extractChangelogOptions(config);
+		const optionsRecord = typeof rawOptions === "object" && rawOptions !== null ? rawOptions : {};
+		if (Array.isArray(optionsRecord.versionFiles) && typeof optionsRecord.packages === "object" && optionsRecord.packages !== null) return yield* Effect.fail(new ConfigurationError({
+			field: "options",
+			reason: `Configuration in ${configPath} declares both \`packages\` and the deprecated top-level \`versionFiles\` array. Migrate the legacy entries into \`packages[<name>].versionFiles\` and remove the top-level field.`
+		}));
+		let normalized;
+		let legacyUsed;
+		try {
+			const result = normalizeLegacyOptions(optionsRecord, configPath);
+			normalized = result.normalized;
+			legacyUsed = result.legacyUsed;
+		} catch (e) {
+			if (e instanceof ConfigurationError) return yield* Effect.fail(e);
+			throw e;
+		}
+		const decodedOptions = yield* Schema.decodeUnknown(ChangesetOptionsSchema)(normalized).pipe(Effect.mapError((parseError) => configErrorFromParseError(parseError, configPath)));
+		const workspaces = (yield* discovery.listPackages(projectDir).pipe(Effect.mapError((err) => new ConfigurationError({
+			field: "workspace",
+			reason: `Workspace discovery failed for ${projectDir}: ${err.message}`
+		})))).map((w) => ({
+			name: w.name,
+			path: w.path,
+			version: w.version
+		}));
+		let scopes;
+		try {
+			scopes = buildResolvedScopes({
+				options: decodedOptions,
+				workspaces,
+				projectDir,
+				configPath
+			});
+			checkConflicts(scopes, workspaces, projectDir, configPath);
+		} catch (e) {
+			if (e instanceof ConfigurationError) return yield* Effect.fail(e);
+			throw e;
+		}
+		const inspected = {
+			configPath,
+			projectDir,
+			changelog: changelogId,
+			baseBranch: config.baseBranch ?? "main",
+			access: config.access ?? "restricted",
+			ignore: config.ignore ?? [],
+			packages: scopes,
+			legacyVersionFilesUsed: legacyUsed
+		};
+		cache.set(projectDir, inspected);
+		return inspected;
+	});
+	const classify = (cwd, paths) => Effect.gen(function* () {
+		const inspected = yield* inspect(cwd);
+		return paths.map((p) => classifyOne(inspected, p));
+	});
+	return {
+		inspect,
+		classify
+	};
+}
+/**
+* Classify a single path against an inspected config.
+*/
+function classifyOne(inspected, path) {
+	const abs = resolve(inspected.projectDir, path);
+	let bestWorkspace = null;
+	for (const s of inspected.packages) if (isInside(s.workspaceDir, abs)) {
+		const depth = s.workspaceDir.length;
+		if (!bestWorkspace || depth > bestWorkspace.depth) bestWorkspace = {
+			pkg: s.name,
+			depth
+		};
+	}
+	if (bestWorkspace) return {
+		path,
+		package: bestWorkspace.pkg,
+		reason: "workspace"
+	};
+	for (const s of inspected.packages) if (s.additionalScopeFiles.includes(abs)) {
+		const glob = s.additionalScopes.find((g) => materializeGlob(g, inspected.projectDir).map((rel) => join(inspected.projectDir, rel)).includes(abs));
+		return {
+			path,
+			package: s.name,
+			reason: {
+				kind: "additionalScope",
+				glob: glob ?? s.additionalScopes[0] ?? ""
+			}
+		};
+	}
+	for (const s of inspected.packages) for (const vf of s.versionFiles) if (vf.matchedFiles.includes(abs)) return {
+		path,
+		package: s.name,
+		reason: {
+			kind: "versionFile",
+			glob: vf.glob
+		}
+	};
+	return {
+		path,
+		package: null,
+		reason: null
+	};
+}
+/**
+* Live layer for {@link ConfigInspector}.
+*
+* Requires {@link ChangesetConfigReader} and {@link WorkspaceDiscovery}
+* in the environment.
+*
+* @public
+*/
+const ConfigInspectorLive = Layer.effect(ConfigInspector, Effect.gen(function* () {
+	return makeShape(yield* ChangesetConfigReader, yield* WorkspaceDiscovery);
+}));
+/**
+* Test factory — build a {@link ConfigInspector} that returns a fixed
+* {@link InspectedConfig} without touching the filesystem.
+*
+* Tests that need to exercise the inspect/classify logic against real files
+* should compose `ConfigInspectorLive` with test layers for
+* `ChangesetConfigReader` and `WorkspaceDiscovery` instead.
+*
+* @public
+*/
+function makeConfigInspectorTest(fixed) {
+	return Layer.succeed(ConfigInspector, {
+		inspect: () => Effect.succeed(fixed),
+		classify: (_cwd, paths) => Effect.succeed(paths.map((p) => classifyOne(fixed, p)))
+	});
+}
+
+//#endregion
+export { ConfigInspector, ConfigInspectorBase, ConfigInspectorLive, makeConfigInspectorTest };

package/changesets/services/github.js

@@ -0,0 +1,178 @@
+import { GitHubApiError } from "../errors.js";
+import { getGitHubInfo } from "../vendor/github-info.js";
+import { Context, Effect, Layer } from "effect";
+
+//#region src/changesets/services/github.ts
+/**
+* GitHub service for fetching commit metadata.
+*
+* Defines the {@link GitHubService} Effect service tag, the
+* {@link GitHubLive | production layer} backed by `\@changesets/get-github-info`,
+* and the {@link makeGitHubTest} helper for constructing deterministic test
+* layers.
+*
+* @remarks
+* The GitHub service is consumed by the changelog formatters to resolve
+* commit hashes into pull-request numbers, author usernames, and link URLs.
+* In production, {@link GitHubLive} calls the GitHub REST API via the
+* vendored `getGitHubInfo` wrapper. In tests, {@link makeGitHubTest}
+* returns canned responses from a `Map` keyed by commit hash.
+*
+* @see {@link GitHubService} for the Effect service tag
+* @see {@link GitHubServiceShape} for the service interface
+* @see {@link GitHubLive} for the production layer
+* @see {@link makeGitHubTest} for constructing test layers
+*/
+const _tag = Context.Tag("GitHubService");
+/**
+* Base class for GitHubService.
+*
+* @privateRemarks
+* This export is required for api-extractor documentation generation.
+* Effect's Context.Tag creates an anonymous base class that must be
+* explicitly exported to avoid "forgotten export" warnings. Do not delete.
+*
+* @internal
+*/
+const GitHubServiceBase = _tag();
+/**
+* Effect service tag for GitHub API operations.
+*
+* Provides dependency-injected access to GitHub commit metadata lookups.
+* Use `yield* GitHubService` inside an `Effect.gen` block to obtain the
+* service instance.
+*
+* @remarks
+* This tag follows the standard Effect `Context.Tag` pattern. Two layers
+* are provided out of the box:
+*
+* - {@link GitHubLive} — production layer backed by the GitHub REST API
+* - {@link makeGitHubTest} — factory for deterministic test layers
+*
+* @example
+* ```typescript
+* import { Effect, Layer } from "effect";
+* import { GitHubService, GitHubLive } from "\@savvy-web/changesets";
+*
+* const program = Effect.gen(function* () {
+*   const github = yield* GitHubService;
+*   const info = yield* github.getInfo({
+*     commit: "abc1234567890",
+*     repo: "savvy-web/changesets",
+*   });
+*   console.log(info.user, info.pull, info.links);
+* });
+*
+* // Provide the live layer and run
+* Effect.runPromise(program.pipe(Effect.provide(GitHubLive)));
+* ```
+*
+* @example Creating a test layer with canned responses
+* ```typescript
+* import { Effect } from "effect";
+* import type { GitHubCommitInfo } from "\@savvy-web/changesets";
+* import { GitHubService, makeGitHubTest } from "\@savvy-web/changesets";
+*
+* const testResponses = new Map<string, GitHubCommitInfo>([
+*   ["abc1234", { user: "octocat", pull: 42, links: { pull: "#42", user: "\@octocat" } }],
+* ]);
+*
+* const TestLayer = makeGitHubTest(testResponses);
+*
+* const program = Effect.gen(function* () {
+*   const github = yield* GitHubService;
+*   return yield* github.getInfo({ commit: "abc1234", repo: "owner/repo" });
+* });
+*
+* Effect.runPromise(program.pipe(Effect.provide(TestLayer)));
+* ```
+*
+* @see {@link GitHubServiceShape} for the service interface
+* @see {@link GitHubLive} for the production layer
+* @see {@link makeGitHubTest} for creating test layers
+* @see {@link GitHubServiceBase} for the api-extractor base class
+*
+* @public
+*/
+var GitHubService = class extends GitHubServiceBase {};
+/**
+* Production layer for {@link GitHubService}.
+*
+* Delegates to `\@changesets/get-github-info` to fetch commit metadata
+* from the GitHub REST API. Requires a `GITHUB_TOKEN` environment variable
+* to be set for authenticated requests.
+*
+* @remarks
+* This layer is used by the `\@savvy-web/changesets/changelog` entry point
+* to resolve commit hashes into PR numbers and author attribution. It is
+* composed with {@link MarkdownLive} in the changelog formatter's
+* `MainLayer`.
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import { GitHubService, GitHubLive } from "\@savvy-web/changesets";
+*
+* const program = Effect.gen(function* () {
+*   const github = yield* GitHubService;
+*   return yield* github.getInfo({ commit: "abc1234", repo: "owner/repo" });
+* });
+*
+* Effect.runPromise(program.pipe(Effect.provide(GitHubLive)));
+* ```
+*
+* @public
+*/
+const GitHubLive = Layer.succeed(GitHubService, { getInfo: getGitHubInfo });
+/**
+* Create a test layer for {@link GitHubService} with pre-configured responses.
+*
+* Returns a `Layer` that resolves commit hashes from the provided `Map`.
+* Lookups for commits not present in the map fail with a
+* {@link GitHubApiError}.
+*
+* @remarks
+* This helper is the recommended way to test code that depends on
+* `GitHubService` without making real API calls. Provide the layer
+* via `Effect.provide` in your test setup.
+*
+* @param responses - A `Map` of full commit hash to {@link GitHubCommitInfo} objects
+* @returns A `Layer` providing the {@link GitHubService} with deterministic responses
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import type { GitHubCommitInfo } from "\@savvy-web/changesets";
+* import { GitHubService, makeGitHubTest } from "\@savvy-web/changesets";
+*
+* const responses = new Map<string, GitHubCommitInfo>([
+*   ["abc1234", { user: "octocat", pull: 42, links: { pull: "#42", user: "\@octocat" } }],
+* ]);
+*
+* const TestGitHub = makeGitHubTest(responses);
+*
+* const program = Effect.gen(function* () {
+*   const github = yield* GitHubService;
+*   return yield* github.getInfo({ commit: "abc1234", repo: "owner/repo" });
+* });
+*
+* // In a Vitest test:
+* const result = await Effect.runPromise(program.pipe(Effect.provide(TestGitHub)));
+* // result.user === "octocat"
+* ```
+*
+* @public
+*/
+function makeGitHubTest(responses) {
+	return Layer.succeed(GitHubService, { getInfo: (params) => {
+		const info = responses.get(params.commit);
+		if (info) return Effect.succeed(info);
+		return Effect.fail(new GitHubApiError({
+			operation: "getInfo",
+			reason: `No mock response for commit ${params.commit}`
+		}));
+	} });
+}
+
+//#endregion
+export { GitHubLive, GitHubService, GitHubServiceBase, makeGitHubTest };

package/changesets/services/markdown.js

@@ -0,0 +1,106 @@
+import { parseMarkdown, stringifyMarkdown } from "../utils/remark-pipeline.js";
+import { Context, Effect, Layer } from "effect";
+
+//#region src/changesets/services/markdown.ts
+/**
+* Markdown service for parsing and stringifying mdast trees.
+*
+* Defines the {@link MarkdownService} Effect service tag and the
+* {@link MarkdownLive | production layer} backed by the remark/unified
+* pipeline. This service provides a pure, side-effect-free interface to
+* markdown parsing and stringification used throughout the changelog
+* formatter and remark transform pipeline.
+*
+* @remarks
+* The service wraps the `remark-pipeline` utility functions (`parseMarkdown`
+* and `stringifyMarkdown`) behind an Effect interface. The `parse` operation
+* returns an mdast `Root` node; the `stringify` operation serializes an
+* mdast `Root` back to a markdown string. Both operations are synchronous
+* under the hood but are lifted into `Effect.sync` for composability.
+*
+* @see {@link MarkdownService} for the Effect service tag
+* @see {@link MarkdownServiceShape} for the service interface
+* @see {@link MarkdownLive} for the production layer
+*/
+const _tag = Context.Tag("MarkdownService");
+/**
+* Base class for MarkdownService.
+*
+* @privateRemarks
+* This export is required for api-extractor documentation generation.
+* Effect's Context.Tag creates an anonymous base class that must be
+* explicitly exported to avoid "forgotten export" warnings. Do not delete.
+*
+* @internal
+*/
+const MarkdownServiceBase = _tag();
+/**
+* Effect service tag for markdown parsing and stringification.
+*
+* Provides dependency-injected access to markdown parse/stringify operations.
+* Use `yield* MarkdownService` inside an `Effect.gen` block to obtain the
+* service instance.
+*
+* @remarks
+* This tag follows the standard Effect `Context.Tag` pattern. The
+* {@link MarkdownLive} layer provides the default implementation backed by
+* the remark/unified pipeline. For testing, you can supply a custom layer
+* via `Layer.succeed(MarkdownService, { parse: ..., stringify: ... })`.
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import { MarkdownService, MarkdownLive } from "\@savvy-web/changesets";
+*
+* const program = Effect.gen(function* () {
+*   const md = yield* MarkdownService;
+*   const tree = yield* md.parse("# Hello\n\nWorld");
+*   const output = yield* md.stringify(tree);
+*   console.log(output); // "# Hello\n\nWorld\n"
+* });
+*
+* Effect.runPromise(program.pipe(Effect.provide(MarkdownLive)));
+* ```
+*
+* @see {@link MarkdownServiceShape} for the service interface
+* @see {@link MarkdownLive} for the production layer
+* @see {@link MarkdownServiceBase} for the api-extractor base class
+*
+* @public
+*/
+var MarkdownService = class extends MarkdownServiceBase {};
+/**
+* Production layer for {@link MarkdownService}.
+*
+* Wraps the remark-pipeline utility functions (`parseMarkdown` and
+* `stringifyMarkdown`) in `Effect.sync` for use in Effect programs.
+* Both operations are synchronous and infallible.
+*
+* @remarks
+* This layer is composed with {@link GitHubLive} in the
+* `\@savvy-web/changesets/changelog` entry point to form the `MainLayer`
+* that powers the Changesets API integration.
+*
+* @example
+* ```typescript
+* import { Effect, Layer } from "effect";
+* import { MarkdownService, MarkdownLive } from "\@savvy-web/changesets";
+*
+* const program = Effect.gen(function* () {
+*   const md = yield* MarkdownService;
+*   const tree = yield* md.parse("**bold** text");
+*   return yield* md.stringify(tree);
+* });
+*
+* Effect.runPromise(program.pipe(Effect.provide(MarkdownLive)));
+* ```
+*
+* @public
+*/
+const MarkdownLive = Layer.succeed(MarkdownService, {
+	parse: (content) => Effect.sync(() => parseMarkdown(content)),
+	stringify: (tree) => Effect.sync(() => stringifyMarkdown(tree))
+});
+
+//#endregion
+export { MarkdownLive, MarkdownService, MarkdownServiceBase };