@savvy-web/silk-effects 0.6.0 → 1.0.0

package/changesets/schemas/version-files.js

@@ -0,0 +1,151 @@
+import { Schema } from "effect";
+
+//#region src/changesets/schemas/version-files.ts
+/**
+* Schemas for `versionFiles` configuration entries.
+*
+* @remarks
+* `versionFiles` lets \@savvy-web/changesets update version fields in
+* arbitrary JSON files (beyond `package.json`) during the
+* `changeset version` command. Each entry specifies a glob pattern to
+* match files and optional JSONPath expressions to locate version fields
+* within those files.
+*
+* Two related schemas live here:
+*
+* - {@link VersionFileConfigSchema} — the **new** per-package entry shape
+*   used inside `packages[*].versionFiles`. It has no `package` field
+*   because the parent record key already names the owning package.
+* - {@link LegacyVersionFileConfigSchema} — the **deprecated** entry shape
+*   used by the top-level `versionFiles[]` array on the changelog options.
+*   It carries an optional `package` field so the owner can be named
+*   inline. Accepted in 0.9.0 with a deprecation warning; removed in
+*   1.0.0.
+*
+* @see {@link ChangesetOptionsSchema} for the consuming options shape
+* @see {@link PackageScopeSchema} for the new per-package container
+* @see {@link https://effect.website/docs/schema/introduction | Effect Schema documentation}
+*
+* @packageDocumentation
+*/
+/**
+* Schema for a JSONPath expression starting with `$.`.
+*
+* @remarks
+* Supports property access (`$.foo.bar`), array wildcard (`$.foo[*].bar`),
+* and array index access (`$.foo[0].bar`). The expression must begin with
+* `$.` followed by at least one property segment.
+*
+* @example
+* ```typescript
+* import { Schema } from "effect";
+* import { JsonPathSchema } from "@savvy-web/changesets";
+*
+* // Succeeds — simple property access
+* Schema.decodeUnknownSync(JsonPathSchema)("$.version");
+*
+* // Succeeds — nested property access
+* Schema.decodeUnknownSync(JsonPathSchema)("$.metadata.version");
+*
+* // Throws ParseError — missing "$." prefix
+* Schema.decodeUnknownSync(JsonPathSchema)("version");
+* ```
+*
+* @see {@link VersionFileConfigSchema} which uses this for the `paths` field
+*
+* @public
+*/
+const JsonPathSchema = Schema.String.pipe(Schema.pattern(/^\$\.[^.]/, { message: () => "JSONPath must start with \"$.\" followed by a property (e.g., \"$.version\", \"$.metadata.version\")" }));
+/**
+* Schema for a single version file configuration entry — **new shape**.
+*
+* @remarks
+* Used inside `packages[*].versionFiles` (i.e., underneath a parent
+* record key that names the owning package). Has no `package` field
+* because the parent key already supplies that information.
+*
+* @example
+* ```typescript
+* import { Schema } from "effect";
+* import { VersionFileConfigSchema } from "@savvy-web/changesets";
+*
+* const entry = Schema.decodeUnknownSync(VersionFileConfigSchema)({
+*   glob: "plugin/.claude-plugin/plugin.json",
+*   paths: ["$.version"],
+* });
+* ```
+*
+* @see {@link VersionFileConfig} for the inferred TypeScript type
+* @see {@link LegacyVersionFileConfigSchema} for the deprecated shape
+*   used by the top-level `versionFiles[]` array
+* @see {@link JsonPathSchema} for JSONPath validation rules
+*
+* @public
+*/
+const VersionFileConfigSchema = Schema.Struct({
+	/** Glob pattern to match JSON files. */
+	glob: Schema.String.pipe(Schema.minLength(1)),
+	/** JSONPath expressions to locate version fields. Defaults to `["$.version"]`. */
+	paths: Schema.optional(Schema.Array(JsonPathSchema))
+});
+/**
+* Schema for an array of new-shape {@link VersionFileConfigSchema} entries.
+*
+* @public
+*/
+const VersionFilesSchema = Schema.Array(VersionFileConfigSchema);
+/**
+* Schema for a single version file configuration entry — **legacy shape**.
+*
+* @remarks
+* DEPRECATED. Used only for parsing the top-level `versionFiles[]` array on
+* the changelog options block. Carries an optional `package` field so the
+* owning package can be named inline (alternatively, the runtime falls back
+* to longest-prefix path matching against workspace package directories).
+*
+* Accepted in 0.9.0 with a deprecation warning emitted by `ConfigInspector`
+* at config-load time. Removed in 1.0.0 — migrate to the new
+* {@link VersionFileConfigSchema} under
+* `changelog[1].packages[<name>].versionFiles`.
+*
+* @example
+* ```typescript
+* import { Schema } from "effect";
+* import { LegacyVersionFileConfigSchema } from "@savvy-web/changesets";
+*
+* // Owner named inline via the `package` field
+* const entry = Schema.decodeUnknownSync(LegacyVersionFileConfigSchema)({
+*   glob: "plugin/.claude-plugin/plugin.json",
+*   paths: ["$.version"],
+*   package: "@savvy-web/changesets",
+* });
+* ```
+*
+* @see {@link VersionFileConfigSchema} for the replacement (new) shape
+* @see {@link LegacyVersionFileConfig} for the inferred TypeScript type
+*
+* @deprecated 0.9.0 — migrate to {@link VersionFileConfigSchema} inside
+*   `packages[*].versionFiles`. Removed in 1.0.0.
+* @public
+*/
+const LegacyVersionFileConfigSchema = Schema.Struct({
+	/** Glob pattern to match JSON files. */
+	glob: Schema.String.pipe(Schema.minLength(1)),
+	/** JSONPath expressions to locate version fields. Defaults to `["$.version"]`. */
+	paths: Schema.optional(Schema.Array(JsonPathSchema)),
+	/** Workspace package name to source the version from, bypassing path-based resolution. */
+	package: Schema.optional(Schema.String.pipe(Schema.minLength(1)))
+});
+/**
+* Schema for an array of legacy {@link LegacyVersionFileConfigSchema}
+* entries — used by the deprecated top-level `versionFiles[]` array on
+* `ChangesetOptionsSchema`.
+*
+* @deprecated 0.9.0 — migrate to {@link VersionFilesSchema} inside
+*   `packages[*].versionFiles`. Removed in 1.0.0.
+* @public
+*/
+const LegacyVersionFilesSchema = Schema.Array(LegacyVersionFileConfigSchema);
+
+//#endregion
+export { JsonPathSchema, LegacyVersionFileConfigSchema, LegacyVersionFilesSchema, VersionFileConfigSchema, VersionFilesSchema };

package/changesets/services/branch-analyzer.js

@@ -0,0 +1,278 @@
+import { GitError } from "../errors.js";
+import { ConfigInspector } from "./config-inspector.js";
+import { Context, Effect, Layer } from "effect";
+import { execFileSync } from "node:child_process";
+
+//#region src/changesets/services/branch-analyzer.ts
+/**
+* `BranchAnalyzer` service — combine a git diff against the base branch with
+* the per-file classification produced by {@link ConfigInspector}.
+*
+* @remarks
+* This is the single call that the changeset-manager agent uses during its
+* inventory step: one invocation returns the diff, the per-file package
+* attribution, the set of packages affected by the branch, and the list of
+* paths that did not map to any known release surface (so the agent can ask
+* the user about them rather than silently excluding).
+*
+* Base-branch resolution order (highest priority first):
+*
+* 1. Explicit `opts.baseBranch` passed to {@link BranchAnalyzerShape.analyzeBranch}.
+* 2. `baseBranch` from `.changeset/config.json` (surfaced via the inspector).
+* 3. The branch `origin/HEAD` points to (`git symbolic-ref refs/remotes/origin/HEAD`).
+* 4. `"main"` as a final fallback.
+*
+* Diff resolution covers everything the user might commit before merging:
+*
+* 1. `git merge-base <base> HEAD` finds the common ancestor.
+* 2. `git diff --name-status <merge-base>` (working tree vs merge-base)
+*    returns every committed, staged, AND unstaged change since the
+*    branch diverged. The two-arg `<merge-base>...HEAD` form would miss
+*    work-in-progress — what the user has open in their editor right
+*    now is exactly the state the agent needs to document.
+* 3. `git ls-files --others --exclude-standard` adds untracked files
+*    (entirely new files not yet `git add`-ed). Each is reported with
+*    status `"added"`.
+*
+* The two results are deduped by path before classification. Renames
+* are reported as `"renamed"` with the new path; the old path is
+* discarded since the classifier needs a single canonical path per
+* file.
+*
+* @see {@link BranchAnalyzer} for the service tag
+* @see {@link BranchAnalyzerLive} for the production layer
+* @see {@link ConfigInspector} for the underlying classification service
+*
+* @packageDocumentation
+*/
+const _tag = Context.Tag("BranchAnalyzer");
+/**
+* Base class for {@link BranchAnalyzer}.
+*
+* @privateRemarks
+* Effect's `Context.Tag` creates an anonymous base class that api-extractor
+* cannot follow without an explicit export. Do not delete.
+*
+* @internal
+*/
+const BranchAnalyzerBase = _tag();
+/**
+* Effect service tag for {@link BranchAnalyzerShape}.
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import { BranchAnalyzer, BranchAnalyzerLive, ConfigInspectorLive } from "@savvy-web/changesets";
+*
+* const program = Effect.gen(function* () {
+*   const analyzer = yield* BranchAnalyzer;
+*   const analysis = yield* analyzer.analyzeBranch(process.cwd());
+*   return analysis.packagesAffected;
+* });
+*
+* Effect.runPromise(
+*   program.pipe(
+*     Effect.provide(BranchAnalyzerLive),
+*     Effect.provide(ConfigInspectorLive),
+*     // ... + ChangesetConfigReaderLive + WorkspacesLive + NodeContext.layer
+*   ),
+* );
+* ```
+*
+* @public
+*/
+var BranchAnalyzer = class extends BranchAnalyzerBase {};
+/**
+* Invoke `git` with the given args under `cwd` and return stdout. On
+* non-zero exit (or any throw), maps to a {@link GitError} carrying the
+* command, cwd, and captured stderr.
+*/
+function runGit(cwd, args) {
+	return Effect.try({
+		try: () => execFileSync("git", args, {
+			cwd,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		}),
+		catch: (error) => {
+			const e = error;
+			const stderr = typeof e.stderr === "string" ? e.stderr : e.stderr?.toString() ?? "";
+			return new GitError({
+				command: `git ${args.join(" ")}`,
+				cwd,
+				reason: stderr.trim() || e.message || String(error)
+			});
+		}
+	});
+}
+const STATUS_MAP = {
+	A: "added",
+	M: "modified",
+	D: "deleted",
+	R: "renamed",
+	C: "copied",
+	T: "typechange",
+	U: "unmerged"
+};
+function statusFromCode(code) {
+	return STATUS_MAP[code.charAt(0)] ?? "unknown";
+}
+/**
+* Parse `git diff --name-status -z` output into one entry per changed file.
+*
+* `-z` separates fields with NUL bytes and avoids the per-record `\n`
+* delimiter, so paths containing spaces or special characters round-trip
+* cleanly. Rename and copy entries occupy three NUL-separated tokens
+* (status, old path, new path) instead of two; everything else is two.
+*/
+function parseNameStatus(output) {
+	if (output.length === 0) return [];
+	const tokens = output.split("\0");
+	if (tokens[tokens.length - 1] === "") tokens.pop();
+	const entries = [];
+	for (let i = 0; i < tokens.length;) {
+		const code = tokens[i] ?? "";
+		if (code.length === 0) {
+			/* v8 ignore next 2 -- defensive guard; trailing empties stripped at parse time */
+			i += 1;
+			continue;
+		}
+		const status = statusFromCode(code);
+		if (status === "renamed" || status === "copied") {
+			const newPath = tokens[i + 2] ?? "";
+			if (newPath.length > 0) entries.push({
+				path: newPath,
+				status
+			});
+			i += 3;
+		} else {
+			const path = tokens[i + 1] ?? "";
+			if (path.length > 0) entries.push({
+				path,
+				status
+			});
+			i += 2;
+		}
+	}
+	return entries;
+}
+/**
+* Parse a NUL-separated list of paths (e.g., `git ls-files -z` output) into
+* an array of strings, dropping any trailing empty entry left by the final
+* NUL byte.
+*/
+function parseNulSeparatedPaths(output) {
+	if (output.length === 0) return [];
+	const tokens = output.split("\0");
+	if (tokens[tokens.length - 1] === "") tokens.pop();
+	return tokens.filter((t) => t.length > 0);
+}
+/**
+* Resolve the base branch using the documented priority order.
+*/
+function resolveBaseBranch(opts) {
+	if (opts.explicit && opts.explicit.length > 0) return Effect.succeed(opts.explicit);
+	if (opts.configBaseBranch && opts.configBaseBranch !== "main") return Effect.succeed(opts.configBaseBranch);
+	return runGit(opts.cwd, [
+		"symbolic-ref",
+		"--quiet",
+		"--short",
+		"refs/remotes/origin/HEAD"
+	]).pipe(
+		/* v8 ignore start -- callback only reachable with a remote that exposes origin/HEAD */
+		Effect.map((stdout) => {
+			const trimmed = stdout.trim();
+			return trimmed.length > 0 ? trimmed.replace(/^origin\//, "") : opts.configBaseBranch;
+		}),
+		/* v8 ignore stop */
+		Effect.catchAll(() => Effect.succeed(opts.configBaseBranch))
+	);
+}
+function makeShape(inspector) {
+	const analyzeBranch = (cwd, opts) => Effect.gen(function* () {
+		const inspected = yield* inspector.inspect(cwd);
+		const baseBranch = yield* resolveBaseBranch({
+			explicit: opts?.baseBranch,
+			configBaseBranch: inspected.baseBranch,
+			cwd
+		});
+		const mergeBaseSha = (yield* runGit(cwd, [
+			"merge-base",
+			baseBranch,
+			"HEAD"
+		])).trim();
+		const diffEntries = parseNameStatus(yield* runGit(cwd, [
+			"diff",
+			"--name-status",
+			"-z",
+			mergeBaseSha
+		]));
+		const untrackedEntries = parseNulSeparatedPaths(yield* runGit(cwd, [
+			"ls-files",
+			"-z",
+			"--others",
+			"--exclude-standard"
+		])).map((path) => ({
+			path,
+			status: "added"
+		}));
+		const seen = /* @__PURE__ */ new Set();
+		const rawEntries = [];
+		for (const e of diffEntries) {
+			if (seen.has(e.path)) continue;
+			seen.add(e.path);
+			rawEntries.push(e);
+		}
+		for (const e of untrackedEntries) {
+			if (seen.has(e.path)) continue;
+			seen.add(e.path);
+			rawEntries.push(e);
+		}
+		const paths = rawEntries.map((e) => e.path);
+		const classifications = yield* inspector.classify(cwd, paths);
+		const files = rawEntries.map((entry, idx) => {
+			const c = classifications[idx];
+			return {
+				path: entry.path,
+				status: entry.status,
+				package: c?.package ?? null,
+				reason: c?.reason ?? null
+			};
+		});
+		return {
+			baseBranch,
+			mergeBaseSha,
+			files,
+			packagesAffected: Array.from(new Set(files.map((f) => f.package).filter((p) => p !== null))).sort(),
+			unmappedFiles: files.filter((f) => f.package === null).map((f) => f.path)
+		};
+	});
+	return { analyzeBranch };
+}
+/**
+* Live layer for {@link BranchAnalyzer}.
+*
+* Requires {@link ConfigInspector} (which in turn requires
+* `ChangesetConfigReader` and `WorkspaceDiscovery`).
+*
+* @public
+*/
+const BranchAnalyzerLive = Layer.effect(BranchAnalyzer, Effect.gen(function* () {
+	return makeShape(yield* ConfigInspector);
+}));
+/**
+* Test factory — build a {@link BranchAnalyzer} that returns a fixed
+* {@link BranchAnalysis} for any input.
+*
+* @public
+*/
+function makeBranchAnalyzerTest(fixed) {
+	return Layer.succeed(BranchAnalyzer, { analyzeBranch: () => Effect.succeed(fixed) });
+}
+
+//#endregion
+export { BranchAnalyzer, BranchAnalyzerBase, BranchAnalyzerLive, makeBranchAnalyzerTest };

package/changesets/services/changelog.js

@@ -0,0 +1,50 @@
+import { Context } from "effect";
+
+//#region src/changesets/services/changelog.ts
+const _tag = Context.Tag("ChangelogService");
+/**
+* Base class for ChangelogService.
+*
+* @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 ChangelogServiceBase = _tag();
+/**
+* Effect service tag for changelog formatting.
+*
+* Provides dependency-injected access to the two Changesets API formatter
+* functions: `formatReleaseLine` and `formatDependencyReleaseLine`.
+*
+* @remarks
+* This is an abstract service tag — it has no default `Layer`. The concrete
+* implementation is the `\@savvy-web/changesets/changelog` subpath export,
+* which wires the formatting logic through `Effect.runPromise` for the
+* Changesets CLI. For direct Effect usage, build your own layer or use
+* the class-based `Changelog` wrapper.
+*
+* @example
+* ```typescript
+* import { Effect } from "effect";
+* import type { ChangesetOptions } from "\@savvy-web/changesets";
+* import { ChangelogService, GitHubLive, MarkdownLive } from "\@savvy-web/changesets";
+*
+* const program = Effect.gen(function* () {
+*   const changelog = yield* ChangelogService;
+*   const line = yield* changelog.formatReleaseLine(changeset, "minor", options);
+*   return line;
+* });
+* ```
+*
+* @see {@link ChangelogServiceShape} for the service interface
+* @see {@link ChangelogServiceBase} for the api-extractor base class
+*
+* @public
+*/
+var ChangelogService = class extends ChangelogServiceBase {};
+
+//#endregion
+export { ChangelogService, ChangelogServiceBase };