@savvy-web/silk-effects 5.0.1 → 5.1.1

package/README.md

@@ -107,6 +107,17 @@ const tags = strategy.tagsFor([{ name: "@savvy-web/silk-effects", version: "1.0.
 
 `WorkspaceAnalysis.versioning` and `WorkspaceAnalysis.tagStrategy` carry those kit types directly.
 
+#### ChangesetLinter
+
+Validate a changeset file against the Silk section rules. `ChangesetLinter.validateContent(content, filePath?)` and `ChangesetLinter.validateFile(filePath)` are static and synchronous, returning `LintMessage[]` — no Effect, no layers. Rules cover the valid section headings, structural constraints, and the dependency-table format, so a `## Dependencies` section written as prose or a bullet list is reported rather than accepted.
+
+```typescript
+import { Changesets } from "@savvy-web/silk-effects";
+
+const messages = Changesets.ChangesetLinter.validateFile(".changeset/quiet-moons-render.md");
+// => [] when the file is valid, otherwise one LintMessage per violation
+```
+
 ---
 
 ### FileSystem layer required
@@ -258,10 +269,68 @@ const result = await Effect.runPromise(
 // => { updated: true, skipped: false, current: "2.0.0" }
 ```
 
+#### ConfigInspector
+
+Resolve `.changeset/config.json` into a fully attributed view of the workspace: the configured changelog, base branch, access and ignore list, plus one scope per package carrying its `workspaceDir`, version, `additionalScopes` and resolved `versionFiles`. `inspect(cwd)` returns that view and `classify` maps arbitrary file paths to the package that owns them, which is how a branch diff becomes a per-package attribution. `refresh()` clears the per-root cache, which a long-lived host needs in order to see config edits made between calls.
+
+`Changesets.ConfigInspectorLive` requires `ChangesetConfigReader`, `WorkspaceDiscovery` from [`@effected/workspaces`](https://www.npmjs.com/package/@effected/workspaces) and `FileSystem`.
+
+#### ReleasePlanner
+
+Drive the genuine changesets engine rather than shelling out to the `changeset` binary. Three members:
+
+- `plan(root)` computes the in-memory release plan. It renders nothing, so it resolves no changelog module.
+- `preview(root, options?)` renders a non-destructive preview, running the real engine against a scope-managed temp directory and reading the generated CHANGELOG blocks back. The repository is never mutated.
+- `apply(root, options?)` performs the release — version bumps, CHANGELOG writes and configured version-file updates. Pass `dryRun` to compute without writing.
+
+Both `preview` and `apply` accept `changelogModules`, mapping the changelog id configured in `.changeset/config.json` to an absolute module path. Reach for it when running somewhere the configured id cannot be resolved — a bundled GitHub Action with no `node_modules`, for instance. When set, the configured id must be a key of the map, an unmapped id fails with a `ReleasePlanError` naming the supported keys, and the engine's formatter integration is disabled so the caller owns formatting.
+
+```typescript
+const preview = yield* planner.preview(root, {
+  changelogModules: { "@savvy-web/changelog": changelogModulePath },
+});
+// => ChangesetPreview: per-release changelogEntry, versions and changeset ids
+```
+
+`Changesets.ReleasePlannerLive` requires `ConfigInspector` and `FileSystem`.
+
 ---
 
 ### FileSystem + process layer required
 
+#### BranchAnalyzer
+
+`analyzeBranch` classifies a branch's diff by the package that owns each file, applying `ConfigInspector` attribution over the git range. This is what answers "what changed on this branch, and which package releases because of it", including the unmapped files that belong to no package.
+
+`Changesets.BranchAnalyzerLive` requires `ConfigInspector` and the platform process spawner.
+
+#### DepsRegen
+
+Own dependency-changeset orchestration, split so that detection and regeneration share one code path: `plan(options)` computes a complete, side-effect-free `RegenPlan` — target filenames, each row's from/to version, and any stale pure-dependency changesets marked for deletion — and `execute(plan)` applies exactly what the plan describes. A dry run is `plan()` plus rendering.
+
+Both sides of the diff are snapshotted at their own git ref, so `catalog:` and `workspace:` specifiers resolve per side before the comparison. A specifier that changes protocol without changing its resolved version produces no row.
+
+`Changesets.DepsRegenDefault` is the batteries-included layer, composing the full graph with silk's opinionated defaults and leaving only the platform services open. Because snapshots read git history, provide a spawn-capable layer such as `NodeServices.layer` rather than a filesystem-only one.
+
+```typescript
+import { Effect } from "effect";
+import { NodeServices } from "@effect/platform-node";
+import { Changesets } from "@savvy-web/silk-effects";
+
+const plan = await Effect.runPromise(
+  Effect.gen(function* () {
+    const regen = yield* Changesets.DepsRegen;
+    return yield* regen.plan({});
+  }).pipe(
+    Effect.provide(Changesets.DepsRegenDefault),
+    Effect.provide(NodeServices.layer),
+  ),
+);
+// => RegenPlan: files to write, rows per package, changesets to delete
+```
+
+`Changesets.DepsRegenLive` is the seam for callers injecting their own dependencies; it requires `WorkspaceSnapshots`, `ConfigInspector`, `WorkspaceDiscovery`, `PublishabilityDetector`, `ChangesetConfig`, `Git` and `FileSystem`.
+
 #### TurboInspector
 
 Read-only Turborepo inspection. Every method shells out to `turbo` with `--dry=json`, so no task ever runs. `diagnoseCache(task, cwd)` reports a per-package cache HIT/MISS breakdown for a task, `taskGraph(cwd, task?)` derives the task graph and its critical path and `affected(cwd, base?)` lists the packages affected relative to `base` (default `main`). It resolves the `turbo` binary through `ToolDiscovery` from [`@effected/commands`](https://www.npmjs.com/package/@effected/commands) and fails with a tagged error when `turbo` is missing or the directory is not a Turborepo. The service tag and its layer are exported under the `Turbo` namespace.

package/changesets/services/release-planner.js

@@ -49,7 +49,7 @@ function makeShape(inspector, fs) {
 			reason: errMsg(e)
 		})
 	});
-	const preview = (root) => previewEffect(root, fs);
+	const preview = (root, options) => previewEffect(root, options?.changelogModules, fs);
 	const apply = (root, options) => applyEffect(root, options?.dryRun ?? false, options?.changelogModules, inspector, fs);
 	return {
 		plan,
@@ -78,6 +78,44 @@ function makeReleasePlannerTest(fixed) {
 		apply: () => fixed.apply ? Effect.succeed(fixed.apply) : fail("apply")
 	});
 }
+/**
+* Rewrite the engine config for a caller that supplies its own changelog module
+* paths: `config.changelog[0]` becomes the mapped absolute path and the engine's
+* `format` integration is switched off.
+*
+* @remarks
+* Shared by `preview` and `apply` — both hand the result to
+* `applyReleasePlan`, and both are called from no-`node_modules` contexts where
+* neither the configured id nor a formatter can be resolved. An unmapped id
+* fails typed (naming the supported keys) rather than reaching
+* `import-meta-resolve`, which reports it as `expected to be defined`.
+*
+* Exported for tests only — not re-exported from the package index, so it is
+* not public API. Driving it directly is the only deterministic way to assert
+* the `format: false` half: every formatter the changesets config accepts
+* either shells out through `npx` (network) or to an ambient binary, so a
+* fixture that names one passes or fails on what the machine happens to have
+* installed rather than on this rewrite.
+*/
+function withChangelogModules(config, changelogModules, phase) {
+	const unformatted = {
+		...config,
+		format: false
+	};
+	if (!Array.isArray(config.changelog)) return Effect.succeed(unformatted);
+	const configuredId = config.changelog[0];
+	if (!Object.hasOwn(changelogModules, configuredId)) {
+		const supported = Object.keys(changelogModules).join(", ");
+		return Effect.fail(new ReleasePlanError({
+			phase,
+			reason: `changelog id "${configuredId}" is not in changelogModules (supported: ${supported})`
+		}));
+	}
+	return Effect.succeed({
+		...unformatted,
+		changelog: [changelogModules[configuredId], config.changelog[1]]
+	});
+}
 /** Extract the `## <version>` block (down to the next H2 or EOF) from a changelog. */
 function extractVersionBlock(changelog, version) {
 	const lines = changelog.split("\n");
@@ -105,7 +143,7 @@ function maintenanceReasons(plan, config) {
 * scope-managed temp directory (cleaned up automatically when the scope
 * closes) and reading the generated CHANGELOG blocks back.
 */
-function previewEffect(root, fs) {
+function previewEffect(root, changelogModules, fs) {
 	const program = Effect.gen(function* () {
 		const [plan, packages] = yield* Effect.tryPromise({
 			try: () => Promise.all([getReleasePlan(root), getPackages(root)]),
@@ -128,6 +166,7 @@ function previewEffect(root, fs) {
 		});
 		yield* Effect.forEach(warnings, (w) => Effect.logWarning(w));
 		const reasonByName = maintenanceReasons(plan, config);
+		const engineConfig = changelogModules ? yield* withChangelogModules(config, changelogModules, "preview") : config;
 		const preMode = plan.preState ? plan.preState.mode : null;
 		const changesets = plan.changesets.map((cs) => ({
 			id: cs.id,
@@ -180,7 +219,7 @@ function previewEffect(root, fs) {
 		const rootCl = join(packages.rootDir, "CHANGELOG.md");
 		if (yield* fs.exists(rootCl)) yield* fs.copyFile(rootCl, join(tempRoot, "CHANGELOG.md"));
 		yield* Effect.tryPromise({
-			try: () => applyReleasePlan(plan, tempPackages, config, void 0, root),
+			try: () => applyReleasePlan(plan, tempPackages, engineConfig, void 0, root),
 			catch: (e) => new ReleasePlanError({
 				phase: "preview",
 				reason: errMsg(e)
@@ -250,28 +289,7 @@ function applyEffect(root, dryRun, changelogModules, inspector, fs) {
 			})
 		});
 		yield* Effect.forEach(warnings, (w) => Effect.logWarning(w));
-		let engineConfig = config;
-		if (changelogModules) {
-			engineConfig = {
-				...config,
-				format: false
-			};
-			if (Array.isArray(config.changelog)) {
-				const configuredId = config.changelog[0];
-				const mapped = changelogModules[configuredId];
-				if (mapped === void 0) {
-					const supported = Object.keys(changelogModules).join(", ");
-					return yield* Effect.fail(new ReleasePlanError({
-						phase: "apply",
-						reason: `changelog id "${configuredId}" is not in changelogModules (supported: ${supported})`
-					}));
-				}
-				engineConfig = {
-					...engineConfig,
-					changelog: [mapped, config.changelog[1]]
-				};
-			}
-		}
+		const engineConfig = changelogModules ? yield* withChangelogModules(config, changelogModules, "apply") : config;
 		const releases = plan.releases.filter((r) => r.type !== "none").map((r) => ({
 			name: r.name,
 			type: r.type,
@@ -337,4 +355,4 @@ function applyEffect(root, dryRun, changelogModules, inspector, fs) {
 }
 
 //#endregion
-export { ReleasePlanner, ReleasePlannerLive, extractVersionBlock, makeReleasePlannerTest };
+export { ReleasePlanner, ReleasePlannerLive, extractVersionBlock, makeReleasePlannerTest, withChangelogModules };

package/index.d.ts

@@ -3899,8 +3899,22 @@ type AppliedRelease = Schema.Schema.Type<typeof AppliedReleaseSchema>;
 interface ReleasePlannerShape {
   /** Compute the in-memory release plan (read-only). */
   readonly plan: (root: string) => Effect.Effect<ReleasePlan, ReleasePlanError>;
-  /** Render a non-destructive preview of the next release. */
-  readonly preview: (root: string) => Effect.Effect<ChangesetPreview, ReleasePlanError>;
+  /**
+   * Render a non-destructive preview of the next release.
+   *
+   * @remarks
+   * Rendering `changelogEntry` means resolving the configured changelog module,
+   * so `changelogModules` matters here for the same reason it does on `apply`.
+   */
+  readonly preview: (root: string, options?: {
+    /**
+     * Map configured changelog ids to absolute module paths. When set,
+     * `config.changelog[0]` must be a key of this map (rewritten before the
+     * engine call; unmapped ids fail) and the engine's `format` integration
+     * is disabled — callers in no-`node_modules` contexts own formatting.
+     */
+    readonly changelogModules?: Readonly<Record<string, string>>;
+  }) => Effect.Effect<ChangesetPreview, ReleasePlanError>;
   /** Natively apply the release (destructive unless `dryRun`). */
   readonly apply: (root: string, options?: {
     readonly dryRun?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/silk-effects",
-	"version": "5.0.1",
+	"version": "5.1.1",
 	"private": false,
 	"description": "Shared Effect library for Silk Suite conventions",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",