@savvy-web/silk-effects 4.2.5 → 5.0.0

package/README.md

@@ -3,27 +3,28 @@
 [![npm](https://img.shields.io/npm/v/@savvy-web%2Fsilk-effects?label=npm&color=cb3837)](https://www.npmjs.com/package/@savvy-web/silk-effects)
 [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
 
-Shared [Effect](https://effect.website/) library providing Silk Suite conventions for publishability detection, versioning strategy, tag formatting, managed file sections, config discovery, Biome schema synchronization and CLI tool resolution. Platform-agnostic — consumers provide their own runtime layer (`NodeContext`, `BunContext`, etc.).
+Shared [Effect](https://effect.website/) library providing Silk Suite conventions for publishability detection, changeset config access, release planning, config discovery, Biome schema synchronization and read-only Turborepo inspection. Platform-agnostic — consumers provide their own platform layer (`NodeServices.layer` from `@effect/platform-node`, or the equivalent for their runtime).
 
 ## Features
 
-- Detect a package's publish targets from its `package.json` `publishConfig`, with multi-registry support and a changeset-ignore-aware override for `workspaces-effect`'s `PublishabilityDetector`
+- Detect a package's publish targets from its `package.json` `publishConfig`, with multi-registry support and a changeset-ignore-aware override for `@effected/workspaces`'s `PublishabilityDetector`
 - Read changeset config through a typed accessor service that reports silk vs vanilla mode, ignore patterns and fixed groups
-- Manage tool-owned sections in user-editable files without clobbering surrounding content, including ordered multi-section sync for composing several managed regions per file
-- Discover and resolve CLI tools globally or locally with version enforcement and caching
-- Detect versioning strategy and format git tags from changeset configuration
-- Locate config files and keep Biome schema URLs in sync across workspaces
+- Plan, preview and apply a release over the genuine changesets engine, lint changeset files against the section-aware Silk rules and regenerate pure dependency changesets from a branch diff
+- Supply the Silk commitlint config, its prompt and formatter, and the `silk/body-no-markdown` rule
+- Run the lint-staged handlers and the `savvy lint fmt` formatters from a single implementation so the hook and the CLI cannot drift
 - Inspect a Turborepo read-only — diagnose per-package cache hits, derive the task graph and compute affected packages, all over `turbo --dry`
+- Manage the vendored reference repos declared in `.repos/config.json`, including submodule sync, pinning and drift reporting
+- Locate config files and keep Biome schema URLs in sync across workspaces
 
 ## Install
 
 ```bash
-npm install @savvy-web/silk-effects effect @effect/platform @effect/platform-node
+npm install @savvy-web/silk-effects effect @effect/platform-node
 # or
-pnpm add @savvy-web/silk-effects effect @effect/platform @effect/platform-node
+pnpm add @savvy-web/silk-effects effect @effect/platform-node
 ```
 
-`effect` and `@effect/platform` are peer dependencies. Install a platform package (`@effect/platform-node`, `@effect/platform-bun`) matching your runtime.
+`effect` is a peer dependency. Install the platform package matching your runtime — `@effect/platform-node` for Node.js — to satisfy the `FileSystem` and process services the file-reading services need.
 
 ## Quick start
 
@@ -32,8 +33,8 @@ All exports come from the package root:
 ```typescript
 import {
   SilkPublishability,
-  ManagedSection, ManagedSectionLive, SectionDefinition,
-  ToolDiscovery, ToolDiscoveryLive, ToolDefinition,
+  ChangesetConfig, ChangesetConfigLive,
+  Changesets, Lint, Turbo,
 } from "@savvy-web/silk-effects";
 ```
 
@@ -66,7 +67,7 @@ These services are pure logic — no filesystem or shell access needed.
 
 #### SilkPublishability
 
-Apply silk publishability rules to a raw `package.json` and the bundler's resolved target binding, and resolve the publish targets. Targets are `PublishTarget` records from `workspaces-effect` with `name`, `registry`, `directory`, `access` and `provenance` fields. The static `detect` helper is pure; `resolveTargets` and `listPublishable` are Effects that read from disk (see below), and `readTargetsBinding` reads the binding `detect` consumes.
+Apply silk publishability rules to a raw `package.json` and the bundler's resolved target binding, and resolve the publish targets. Targets are `PublishTarget` records from `@effected/workspaces` with `name`, `registry`, `directory`, `access` and `provenance` fields. The static `detect` helper is pure; `resolveTargets` and `listPublishable` are Effects that read from disk (see below), and `readTargetsBinding` reads the binding `detect` consumes.
 
 In silk mode `private: true` is the norm on workspace `package.json` files. Publishability is derived from `publishConfig`, with the `private` flag consulted only as a last-resort default. Publish targets are declared as the bundler's keyed `publishConfig.targets` map; the legacy array form is no longer supported.
 
@@ -90,43 +91,39 @@ const none = SilkPublishability.detect("@my-org/internal", { private: true }, nu
 // => []
 ```
 
-See [Publishability](./docs/publishability.md) for the full rule order and the disk-reading helpers.
+See [Publishability](./docs/03-publishability.md) for the full rule order and the disk-reading helpers.
 
-#### TagStrategy
+#### Tags and versioning classification
 
-Determine git-tag naming strategy and format tag strings. Strategy is `"single"` (one publishable package, tags like `1.2.3`) or `"scoped"` (multiple packages, tags like `@scope/pkg@1.2.3`). Tag format follows strict SemVer 2.0.0 with no `v` prefix.
+Git-tag naming and versioning classification live upstream in `@effected/workspaces` as pure value classes — `ReleaseTag`, `TrackingTag`, `classifyTag` and `VersioningStrategy` — so there is no service, no layer and no error channel.
 
 ```typescript
-import { Effect } from "effect";
-import { TagStrategy, TagStrategyLive } from "@savvy-web/silk-effects";
+import { VersioningStrategy } from "@effected/workspaces";
 
-const tag = await Effect.runPromise(
-  Effect.gen(function* () {
-    const ts = yield* TagStrategy;
-    const strategy = yield* ts.determine(versioningResult);
-    return yield* ts.formatTag("@savvy-web/silk-effects", "1.0.0", strategy);
-  }).pipe(Effect.provide(TagStrategyLive)),
-);
-// => "@savvy-web/silk-effects@1.0.0"
+const strategy = VersioningStrategy.classify({ packages: publishablePackages, fixedGroups });
+const tags = strategy.tagsFor([{ name: "@savvy-web/silk-effects", version: "1.0.0" }]);
+// => [ReleaseTag { value: "@savvy-web/silk-effects@1.0.0" }]
 ```
 
+`WorkspaceAnalysis.versioning` and `WorkspaceAnalysis.tagStrategy` carry those kit types directly.
+
 ---
 
 ### FileSystem layer required
 
-These services read or write files. Provide a platform layer such as `NodeContext.layer` or `BunContext.layer`.
+These services read or write files. Provide the platform layer for your runtime, such as `NodeServices.layer`.
 
 #### SilkPublishabilityDetectorLive and PublishabilityDetectorAdaptiveLive
 
-`SilkPublishability.detect` is also exposed through `workspaces-effect`'s `PublishabilityDetector` Tag so consumers can swap silk rules into any program that already yields the detector. Two layers override the Tag:
+`SilkPublishability.detect` is also exposed through `@effected/workspaces`'s `PublishabilityDetector` Tag so consumers can swap silk rules into any program that already yields the detector. Two layers override the Tag:
 
 - `SilkPublishabilityDetectorLive` — applies silk rules unconditionally. Requires `FileSystem`.
-- `PublishabilityDetectorAdaptiveLive` — ignore-aware. Changeset-`ignore`d packages resolve to `[]`, then it dispatches by changeset mode (`none` → `[]`, `silk` → silk rules, `vanilla` → the `workspaces-effect` default). Requires `FileSystem` and `ChangesetConfig`.
+- `PublishabilityDetectorAdaptiveLive` — ignore-aware. Changeset-`ignore`d packages resolve to `[]`, then it dispatches by changeset mode (`none` → `[]`, `silk` → silk rules, `vanilla` → the `@effected/workspaces` default). Requires `FileSystem` and `ChangesetConfig`.
 
 ```typescript
 import { Effect } from "effect";
-import { NodeContext } from "@effect/platform-node";
-import { PublishabilityDetector } from "workspaces-effect";
+import { NodeServices } from "@effect/platform-node";
+import { PublishabilityDetector } from "@effected/workspaces";
 import { SilkPublishabilityDetectorLive } from "@savvy-web/silk-effects";
 
 const targets = await Effect.runPromise(
@@ -135,13 +132,13 @@ const targets = await Effect.runPromise(
     return yield* detector.detect(pkg, root);
   }).pipe(
     Effect.provide(SilkPublishabilityDetectorLive),
-    Effect.provide(NodeContext.layer),
+    Effect.provide(NodeServices.layer),
   ),
 );
 // => ReadonlyArray<PublishTarget>
 ```
 
-See [Publishability](./docs/publishability.md) for the adaptive layer and the `ChangesetConfig` service.
+See [Publishability](./docs/03-publishability.md) for the adaptive layer and the `ChangesetConfig` service.
 
 #### ChangesetConfig
 
@@ -149,7 +146,7 @@ Typed accessor over a workspace root's `.changeset/config.json`, reading through
 
 ```typescript
 import { Effect } from "effect";
-import { NodeContext } from "@effect/platform-node";
+import { NodeServices } from "@effect/platform-node";
 import {
   ChangesetConfig, ChangesetConfigLive, ChangesetConfigReaderLive,
 } from "@savvy-web/silk-effects";
@@ -161,128 +158,48 @@ const mode = await Effect.runPromise(
   }).pipe(
     Effect.provide(ChangesetConfigLive),
     Effect.provide(ChangesetConfigReaderLive),
-    Effect.provide(NodeContext.layer),
+    Effect.provide(NodeServices.layer),
   ),
 );
 // => "silk" | "vanilla" | "none"
 ```
 
-#### ManagedSection
-
-Manage tool-owned delimited sections inside user-editable files. Sections are bounded by markers like `# --- BEGIN TOOL MANAGED SECTION ---` / `# --- END ... ---`. User content outside the markers is never touched.
-
-`SectionDefinition` is a value object representing section identity (tool name + comment style). It creates `SectionBlock` instances that hold the actual content. Definitions support typed content factories via `generate()` and `generateEffect()`.
-
-`SectionBlock` represents the content between markers. It supports `diff()`, `prepend()` and `append()` operations and uses normalized content for equality comparison.
-
-Methods: `read`, `write`, `sync`, `syncMany`, `check`, `remove`, `isManaged` — all support dual API (data-first and data-last) for pipe composition. `sync` manages one section; `syncMany` manages several ordered sections in one file; `remove` deletes a section including its markers.
-
-```typescript
-import { Effect } from "effect";
-import { NodeContext } from "@effect/platform-node";
-import {
-  ManagedSection, ManagedSectionLive, SectionDefinition,
-} from "@savvy-web/silk-effects";
-
-// Define section identity
-const def = SectionDefinition.make({ toolName: "LINT-STAGED" });
-
-// Create a content block from the definition
-const block = def.block("\nnpx lint-staged\n");
-
-await Effect.runPromise(
-  Effect.gen(function* () {
-    const ms = yield* ManagedSection;
-
-    // Sync: creates the section if missing, updates if changed, no-op if identical
-    const result = yield* ms.sync(".husky/pre-commit", block);
-    // => SyncResult: Created | Updated | Unchanged
-
-    // Check: compare file content against expected block
-    const check = yield* ms.check(".husky/pre-commit", block);
-    // => CheckResult: Found | NotFound
-
-    // Remove: delete the section and its markers, collapsing the leftover blank line
-    const removed = yield* ms.remove(".husky/pre-commit", def);
-    // => true if a section was removed, false if none was present
-  }).pipe(
-    Effect.provide(ManagedSectionLive),
-    Effect.provide(NodeContext.layer),
-  ),
-);
-```
-
-`SectionDefinition` also supports `//` comment style for JavaScript/TypeScript files:
+#### Husky hook sections
 
-```typescript
-const jsDef = SectionDefinition.make({ toolName: "MY-TOOL", commentStyle: "//" });
-```
-
-Use `ShellSectionDefinition` when the comment style is always `#` and should not be configurable.
-
-`syncMany` keeps several sections in one file in their declared relative order. It updates existing sections in place, inserts a missing section next to its declared sibling, normalizes order when sections drift out of order and preserves user content and unrelated tool sections. It returns one `SyncResult` per input block in input order and is idempotent.
-
-The `SavvySections` exports compose ordered managed sections per husky hook file. A base section defines shared shell, then each consumer layers its own one-line tool section on top:
+The Silk husky hooks are data. `SavvySections` supplies the section identities and the shell that goes inside them, and [`@effected/templates`](https://www.npmjs.com/package/@effected/templates)' `ManagedSection` service does the reading and writing, so user content outside the `# --- BEGIN ... ---` markers is never touched.
 
-- `SavvyBaseSection` is a `ShellSectionDefinition` (tool name `savvy-base`); pair it with `savvyBasePreamble()`, which defines `ROOT`, the `in_ci` predicate, `PM` via package-manager detection and `pm_exec`.
-- `SavvyHooksSection` (tool name `savvy-hooks`) pairs with `savvyHooksHygiene()`, a self-guarded repo-hygiene block that runs outside CI.
-- `savvyToolSection(toolName, command)` builds a consumer's one-line tool section whose content is exactly `in_ci || pm_exec <command>` — the command is appended verbatim, so shell tokens like `$ROOT` and `$1` survive into the output. A `savvy-base` section must precede it in the same hook file, so pass both to `syncMany` in that order.
+- `SavvyBaseSection` is the shared preamble's identity (key `SAVVY-BASE`); pair it with `savvyBasePreamble()`, which defines `ROOT`, the `in_ci` predicate, `PM` via package-manager detection and `pm_exec`.
+- `SavvyHooksSection` (key `SAVVY-HOOKS`) pairs with `savvyHooksHygiene()`, a self-guarded repo-hygiene block that runs outside CI.
+- `savvyToolSection(toolName, command)` builds a consumer's one-line tool section whose content is exactly `in_ci || pm_exec <command>` — the command is appended verbatim, so shell tokens like `$ROOT` and `$1` survive into the output. A `savvy-base` section must come first in the same hook file, so pass both to `syncAll` in that order.
 
 ```typescript
 import { Effect } from "effect";
-import { NodeContext } from "@effect/platform-node";
-import {
-  ManagedSection, ManagedSectionLive,
-  SavvyBaseSection, savvyBasePreamble, savvyToolSection,
-} from "@savvy-web/silk-effects";
+import { NodeServices } from "@effect/platform-node";
+import { ManagedSection } from "@effected/templates";
+import { SavvyBaseSection, savvyBasePreamble, savvyToolSection } from "@savvy-web/silk-effects";
 
 await Effect.runPromise(
   Effect.gen(function* () {
     const ms = yield* ManagedSection;
-    const results = yield* ms.syncMany(".husky/commit-msg", [
-      SavvyBaseSection.block(savvyBasePreamble()),
+    const results = yield* ms.syncAll(".husky/commit-msg", [
+      SavvyBaseSection.section(savvyBasePreamble()),
       savvyToolSection("savvy-commit", 'commitlint --config "$ROOT/lib/configs/commitlint.config.ts" --edit "$1"'),
     ]);
-    // => ReadonlyArray<SyncResult>, one per input block in declared order
+    // => one sync result per input section, in declared order
   }).pipe(
-    Effect.provide(ManagedSectionLive),
-    Effect.provide(NodeContext.layer),
+    Effect.provide(ManagedSection.layer),
+    Effect.provide(NodeServices.layer),
   ),
 );
 ```
 
-#### VersioningStrategy
-
-Classify the versioning strategy from changeset configuration. Outputs `"single"` (0-1 publishable packages), `"fixed-group"` (all packages in one fixed group) or `"independent"` (multiple packages, not in a single group). Falls back gracefully if config is missing.
-
-```typescript
-import { Effect } from "effect";
-import { NodeContext } from "@effect/platform-node";
-import {
-  VersioningStrategy, VersioningStrategyLive,
-  ChangesetConfigReaderLive,
-} from "@savvy-web/silk-effects";
-
-const result = await Effect.runPromise(
-  Effect.gen(function* () {
-    const vs = yield* VersioningStrategy;
-    return yield* vs.detect(publishablePackages, process.cwd());
-  }).pipe(
-    Effect.provide(VersioningStrategyLive),
-    Effect.provide(ChangesetConfigReaderLive),
-    Effect.provide(NodeContext.layer),
-  ),
-);
-// => { strategy: "single" | "fixed-group" | "independent", ... }
-```
-
 #### ChangesetConfigReader
 
 Read and decode `.changeset/config.json`. Auto-detects whether the project uses `@savvy-web/changesets` (returning `SilkChangesetConfigFile` with `_isSilk: true`) or standard changesets (returning `ChangesetConfigFile`).
 
 ```typescript
 import { Effect } from "effect";
-import { NodeContext } from "@effect/platform-node";
+import { NodeServices } from "@effect/platform-node";
 import {
   ChangesetConfigReader, ChangesetConfigReaderLive,
 } from "@savvy-web/silk-effects";
@@ -293,7 +210,7 @@ const config = await Effect.runPromise(
     return yield* reader.read(process.cwd());
   }).pipe(
     Effect.provide(ChangesetConfigReaderLive),
-    Effect.provide(NodeContext.layer),
+    Effect.provide(NodeServices.layer),
   ),
 );
 // => ChangesetConfigFile | SilkChangesetConfigFile
@@ -305,7 +222,7 @@ Locate config files using a priority-based search convention. Checks `lib/config
 
 ```typescript
 import { Effect } from "effect";
-import { NodeContext } from "@effect/platform-node";
+import { NodeServices } from "@effect/platform-node";
 import { ConfigDiscovery, ConfigDiscoveryLive } from "@savvy-web/silk-effects";
 
 const result = await Effect.runPromise(
@@ -314,7 +231,7 @@ const result = await Effect.runPromise(
     return yield* cd.find("biome.jsonc");
   }).pipe(
     Effect.provide(ConfigDiscoveryLive),
-    Effect.provide(NodeContext.layer),
+    Effect.provide(NodeServices.layer),
   ),
 );
 // => { path: "/project/biome.jsonc", source: "root" } | null
@@ -326,7 +243,7 @@ Keep Biome config `$schema` URLs current. Locates `biome.json` or `biome.jsonc`,
 
 ```typescript
 import { Effect } from "effect";
-import { NodeContext } from "@effect/platform-node";
+import { NodeServices } from "@effect/platform-node";
 import { BiomeSchemaSync, BiomeSchemaSyncLive } from "@savvy-web/silk-effects";
 
 const result = await Effect.runPromise(
@@ -335,7 +252,7 @@ const result = await Effect.runPromise(
     return yield* bss.sync("2.0.0");
   }).pipe(
     Effect.provide(BiomeSchemaSyncLive),
-    Effect.provide(NodeContext.layer),
+    Effect.provide(NodeServices.layer),
   ),
 );
 // => { updated: true, skipped: false, current: "2.0.0" }
@@ -343,59 +260,27 @@ const result = await Effect.runPromise(
 
 ---
 
-### FileSystem + CommandExecutor layer required
-
-#### ToolDiscovery
-
-Locate CLI tools globally (PATH) or locally (via package manager), extract versions, enforce constraints and cache results.
+### FileSystem + process layer required
 
-`ToolDefinition` configures how a tool is resolved: `VersionExtractor` (Flag, Json or None), `ResolutionPolicy` (Report, PreferLocal, PreferGlobal, RequireMatch) and `SourceRequirement` (Any, OnlyLocal, OnlyGlobal, Both). Equality is based on tool name only.
-
-`ResolvedTool` is the result of resolution. It carries the tool's name, source (`"global"` or `"local"`), version and package manager. Its `exec()` and `dlx()` methods return a `ToolCommand` — a wrapper around `@effect/platform` `Command` with instance-method ergonomics (`string()`, `lines()`, `exitCode()`, `stream()`).
-
-```typescript
-import { Effect } from "effect";
-import { NodeContext } from "@effect/platform-node";
-import {
-  ToolDiscovery, ToolDiscoveryLive, ToolDefinition,
-} from "@savvy-web/silk-effects";
-
-const output = await Effect.runPromise(
-  Effect.gen(function* () {
-    const td = yield* ToolDiscovery;
-
-    // Resolve a tool (results are cached by name)
-    const biome = yield* td.resolve(ToolDefinition.make({ name: "biome" }));
-
-    // Check availability without throwing
-    const hasBiome = yield* td.isAvailable(ToolDefinition.make({ name: "biome" }));
+#### TurboInspector
 
-    // Execute the resolved tool
-    return yield* biome.exec("check", ".").string();
-  }).pipe(
-    Effect.provide(ToolDiscoveryLive),
-    Effect.provide(NodeContext.layer),
-  ),
-);
-```
+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.
 
-Use `require()` to fail with a descriptive error if the tool is not found:
+`Turbo.TurboInspectorLive` requires `ToolDiscovery`, `Git` from [`@effected/git`](https://www.npmjs.com/package/@effected/git), `FileSystem` and the platform process spawner. Wire `ToolDiscovery` to the workspace with `Workspaces.localExecLayer()`, which teaches it the argv prefix that runs a project-local binary:
 
 ```typescript
-const biome = yield* td.require(
-  ToolDefinition.make({ name: "biome" }),
-  "Biome is required for linting",
+import { Effect, Layer } from "effect";
+import { NodeServices } from "@effect/platform-node";
+import { ToolDiscovery } from "@effected/commands";
+import { Git } from "@effected/git";
+import { PackageManagerDetector, WorkspaceRoot, Workspaces } from "@effected/workspaces";
+import { Turbo } from "@savvy-web/silk-effects";
+
+const WorkspaceLive = Layer.mergeAll(WorkspaceRoot.layer, PackageManagerDetector.layer);
+const ToolsLive = ToolDiscovery.layer.pipe(
+  Layer.provide(Workspaces.localExecLayer()),
+  Layer.provide(WorkspaceLive),
 );
-```
-
-#### 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` 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.
-
-```typescript
-import { Effect } from "effect";
-import { NodeContext } from "@effect/platform-node";
-import { Turbo, ToolDiscoveryLive } from "@savvy-web/silk-effects";
 
 const diagnosis = await Effect.runPromise(
   Effect.gen(function* () {
@@ -403,8 +288,8 @@ const diagnosis = await Effect.runPromise(
     return yield* turbo.diagnoseCache("build:dev", process.cwd());
   }).pipe(
     Effect.provide(Turbo.TurboInspectorLive),
-    Effect.provide(ToolDiscoveryLive),
-    Effect.provide(NodeContext.layer),
+    Effect.provide(Layer.mergeAll(ToolsLive, Git.layer)),
+    Effect.provide(NodeServices.layer),
   ),
 );
 // => CacheDiagnosis: per-package HIT/MISS breakdown for the task
@@ -412,16 +297,12 @@ const diagnosis = await Effect.runPromise(
 
 ## Documentation
 
-- [Overview](./docs/overview.md) — what the library is, its design philosophy and platform-layer model
-- [Publishability](./docs/publishability.md) — silk publishability rules, the detector overrides and the ChangesetConfig service
-- [Changeset config](./docs/changeset-config.md) — reading and decoding `.changeset/config.json`
-- [Platform layers](./docs/platform-layers.md) — composing layers and providing platform dependencies
-- [Managed sections](./docs/managed-section.md) — tool-owned regions in user-editable files
-- [Tool discovery](./docs/tool-discovery.md) — locating and resolving CLI tools
-- [Versioning strategy](./docs/versioning-strategy.md) — classifying workspace versioning
-- [Config discovery](./docs/config-discovery.md) — priority-based config file search
-- [Biome sync](./docs/biome-sync.md) — keeping Biome `$schema` URLs current
-- [Tag strategy](./docs/tag-strategy.md) — git tag naming and formatting
+- [Overview](./docs/01-overview.md) — what the library is, its design philosophy and platform-layer model
+- [Platform layers](./docs/02-platform-layers.md) — composing layers and providing platform dependencies
+- [Publishability](./docs/03-publishability.md) — silk publishability rules, the detector overrides and the ChangesetConfig service
+- [Changeset config](./docs/04-changeset-config.md) — reading and decoding `.changeset/config.json`
+- [Config discovery](./docs/05-config-discovery.md) — priority-based config file search
+- [Biome sync](./docs/06-biome-sync.md) — keeping Biome `$schema` URLs current
 
 ## License
 

package/changesets/api/changelog.js

@@ -15,8 +15,7 @@ import changelogFunctions from "../changelog/index.js";
 * Delegates to the Changesets-compatible `getReleaseLine` and
 * `getDependencyReleaseLine` functions. Internally, these use the
 * {@link ChangelogService} Effect service layer, which coordinates
-* the {@link GitHubService} (for commit/PR metadata) and
-* {@link MarkdownService} (for AST manipulation) to produce
+* the {@link GitHubService} (for commit/PR metadata) to produce
 * structured changelog entries.
 *
 * @remarks

package/changesets/changelog/index.js

@@ -1,9 +1,8 @@
 import { validateChangesetOptions } from "../schemas/options.js";
 import { GitHubLive } from "../services/github.js";
-import { MarkdownLive } from "../services/markdown.js";
 import { getDependencyReleaseLine } from "./getDependencyReleaseLine.js";
 import { getReleaseLine } from "./getReleaseLine.js";
-import { Effect, Layer } from "effect";
+import { Effect } from "effect";
 
 //#region src/changesets/changelog/index.ts
 /**
@@ -17,8 +16,7 @@ import { Effect, Layer } from "effect";
 * @remarks
 * The module composes two Effect programs — {@link getReleaseLine} and
 * {@link getDependencyReleaseLine} — and runs each through
-* `Effect.runPromise` with a merged layer of {@link GitHubLive} (for commit
-* metadata) and {@link MarkdownLive} (for mdast parsing). Options are
+* `Effect.runPromise` with {@link GitHubLive} (for commit metadata). Options are
 * validated at the boundary via `validateChangesetOptions` before being
 * passed to the formatters.
 *
@@ -58,16 +56,16 @@ import { Effect, Layer } from "effect";
 * @see {@link getDependencyReleaseLine} in `./getDependencyReleaseLine.ts` for dependency table formatting
 */
 /**
-* Combined layer providing all services needed by the formatters.
+* The layer providing every service the formatters need.
 *
-* Merges {@link GitHubLive} and {@link MarkdownLive} into a single layer
-* that satisfies the environment requirements of both `getReleaseLine`
-* (which needs `GitHubService` and `MarkdownService`) and
-* `getDependencyReleaseLine` (which needs `GitHubService`).
+* {@link GitHubLive} satisfies the requirements of both `getReleaseLine` and
+* `getDependencyReleaseLine`, which each need only `GitHubService`. Markdown
+* parsing is not a layer: the formatters call the remark pipeline's
+* `parseMarkdown` / `stringifyMarkdown` functions directly.
 *
 * @internal
 */
-const MainLayer = Layer.mergeAll(GitHubLive, MarkdownLive);
+const MainLayer = GitHubLive;
 /**
 * Changesets API `ChangelogFunctions` implementation.
 *

package/changesets/errors.js

@@ -154,7 +154,6 @@ const MarkdownParseErrorBase = Data.TaggedError("MarkdownParseError");
 * );
 * ```
 *
-* @see {@link MarkdownService} for the Effect service that may produce this error
 *
 * @public
 */

package/changesets/index.js

@@ -5,7 +5,6 @@ import { JsonPathSchema, LegacyVersionFileConfigSchema, LegacyVersionFilesSchema
 import { GlobSchema, PackageScopeSchema, PackagesRecordSchema } from "./schemas/package-scope.js";
 import { ChangesetOptionsSchema, RepoSchema } from "./schemas/options.js";
 import { GitHubLive, GitHubService, makeGitHubTest } from "./services/github.js";
-import { MarkdownLive, MarkdownService } from "./services/markdown.js";
 import { NonEmptyString, PositiveInteger } from "./schemas/primitives.js";
 import { DependencyActionSchema, DependencyTableRowSchema, DependencyTableSchema, DependencyTableTypeSchema, VERSION_RE, VersionOrEmptySchema } from "./schemas/dependency-table.js";
 import { serializeDependencyTableToMarkdown } from "./utils/dependency-table.js";
@@ -108,9 +107,7 @@ var changesets_exports = /* @__PURE__ */ __exportAll({
 	MaintenanceNotePlugin: () => MaintenanceNotePlugin,
 	MaintenanceReasonSchema: () => MaintenanceReasonSchema,
 	MaintenanceTriggerSchema: () => MaintenanceTriggerSchema,
-	MarkdownLive: () => MarkdownLive,
 	MarkdownParseError: () => MarkdownParseError,
-	MarkdownService: () => MarkdownService,
 	MarkdownlintContentStructureRule: () => ContentStructureRule$1,
 	MarkdownlintDependencyTableFormatRule: () => DependencyTableFormatRule$1,
 	MarkdownlintHeadingHierarchyRule: () => HeadingHierarchyRule$1,
@@ -162,4 +159,4 @@ var changesets_exports = /* @__PURE__ */ __exportAll({
 });
 
 //#endregion
-export { AggregateDependencyTablesPlugin, AppliedReleaseEntrySchema, AppliedReleaseSchema, BranchAnalysisSchema, BranchAnalyzer, BranchAnalyzerLive, BranchFileEntrySchema, BumpTypeSchema, Categories, Changelog, ChangelogService, ChangelogTransformer, ChangesetIOError, ChangesetLinter, ChangesetOptionsSchema, ChangesetPreviewSchema, ChangesetSchema, ChangesetSummarySchema, ChangesetValidationError, ClassificationReasonSchema, ClassificationSchema, CommitHashSchema, ConfigInspector, ConfigInspectorLive, ConfigurationError, ContentStructureRule, ContributorFootnotesPlugin, DeduplicateItemsPlugin, DependencyActionSchema, DependencyTable, DependencyTableFormatRule, DependencyTableRowSchema, DependencyTableSchema, DependencyTableTypeSchema, DependencyTypeSchema, DependencyUpdateSchema, DepsRegen, DepsRegenDefault, DepsRegenLive, FileStatusSchema, GitError, GitHubApiError, GitHubInfoSchema, GitHubLive, GitHubService, GlobSchema, HeadingHierarchyRule, InspectedConfigSchema, IssueLinkRefsPlugin, IssueNumberSchema, JsonPathSchema, LegacyVersionFileConfigSchema, LegacyVersionFilesSchema, MaintenanceNotePlugin, MaintenanceReasonSchema, MaintenanceTriggerSchema, MarkdownLive, MarkdownParseError, MarkdownService, ContentStructureRule$1 as MarkdownlintContentStructureRule, DependencyTableFormatRule$1 as MarkdownlintDependencyTableFormatRule, HeadingHierarchyRule$1 as MarkdownlintHeadingHierarchyRule, RequiredSectionsRule$1 as MarkdownlintRequiredSectionsRule, UncategorizedContentRule$1 as MarkdownlintUncategorizedContentRule, MergeSectionsPlugin, NonEmptyString, NormalizeFormatPlugin, PackageScopeSchema, PackagesRecordSchema, PendingChangesetSchema, PositiveInteger, PreviewReleaseSchema, ReleasePlanError, ReleasePlanner, ReleasePlannerLive, ReorderSectionsPlugin, RepoSchema, RequiredSectionsRule, ResolvedPackageScopeSchema, ResolvedVersionFileSchema, SectionCategorySchema, SilkChangesetPreset, SilkChangesetTransformPreset, SilkChangesetsRules, UncategorizedContentRule, UrlOrMarkdownLinkSchema, UsernameSchema, VERSION_RE, VersionFileConfigSchema, VersionFileError, VersionFileUpdateRecordSchema, VersionFiles, VersionFilesSchema, VersionOrEmptySchema, VersionTypeSchema, changelogFunctions, changesets_exports, computeWorkspaceDependencyDiffs, deriveMaintenanceReason, gitMergeBase, isPureDependencyChangeset, listPublishablePackageNames, makeBranchAnalyzerTest, makeConfigInspectorTest, makeDepsRegenDefault, makeGitHubTest, makeReleasePlannerTest, serializeDependencyTableToMarkdown };
+export { AggregateDependencyTablesPlugin, AppliedReleaseEntrySchema, AppliedReleaseSchema, BranchAnalysisSchema, BranchAnalyzer, BranchAnalyzerLive, BranchFileEntrySchema, BumpTypeSchema, Categories, Changelog, ChangelogService, ChangelogTransformer, ChangesetIOError, ChangesetLinter, ChangesetOptionsSchema, ChangesetPreviewSchema, ChangesetSchema, ChangesetSummarySchema, ChangesetValidationError, ClassificationReasonSchema, ClassificationSchema, CommitHashSchema, ConfigInspector, ConfigInspectorLive, ConfigurationError, ContentStructureRule, ContributorFootnotesPlugin, DeduplicateItemsPlugin, DependencyActionSchema, DependencyTable, DependencyTableFormatRule, DependencyTableRowSchema, DependencyTableSchema, DependencyTableTypeSchema, DependencyTypeSchema, DependencyUpdateSchema, DepsRegen, DepsRegenDefault, DepsRegenLive, FileStatusSchema, GitError, GitHubApiError, GitHubInfoSchema, GitHubLive, GitHubService, GlobSchema, HeadingHierarchyRule, InspectedConfigSchema, IssueLinkRefsPlugin, IssueNumberSchema, JsonPathSchema, LegacyVersionFileConfigSchema, LegacyVersionFilesSchema, MaintenanceNotePlugin, MaintenanceReasonSchema, MaintenanceTriggerSchema, MarkdownParseError, ContentStructureRule$1 as MarkdownlintContentStructureRule, DependencyTableFormatRule$1 as MarkdownlintDependencyTableFormatRule, HeadingHierarchyRule$1 as MarkdownlintHeadingHierarchyRule, RequiredSectionsRule$1 as MarkdownlintRequiredSectionsRule, UncategorizedContentRule$1 as MarkdownlintUncategorizedContentRule, MergeSectionsPlugin, NonEmptyString, NormalizeFormatPlugin, PackageScopeSchema, PackagesRecordSchema, PendingChangesetSchema, PositiveInteger, PreviewReleaseSchema, ReleasePlanError, ReleasePlanner, ReleasePlannerLive, ReorderSectionsPlugin, RepoSchema, RequiredSectionsRule, ResolvedPackageScopeSchema, ResolvedVersionFileSchema, SectionCategorySchema, SilkChangesetPreset, SilkChangesetTransformPreset, SilkChangesetsRules, UncategorizedContentRule, UrlOrMarkdownLinkSchema, UsernameSchema, VERSION_RE, VersionFileConfigSchema, VersionFileError, VersionFileUpdateRecordSchema, VersionFiles, VersionFilesSchema, VersionOrEmptySchema, VersionTypeSchema, changelogFunctions, changesets_exports, computeWorkspaceDependencyDiffs, deriveMaintenanceReason, gitMergeBase, isPureDependencyChangeset, listPublishablePackageNames, makeBranchAnalyzerTest, makeConfigInspectorTest, makeDepsRegenDefault, makeGitHubTest, makeReleasePlannerTest, serializeDependencyTableToMarkdown };

package/changesets/services/changelog.js

@@ -18,7 +18,7 @@ import { Context } from "effect";
 * ```typescript
 * import { Effect } from "effect";
 * import type { ChangesetOptions } from "\@savvy-web/changesets";
-* import { ChangelogService, GitHubLive, MarkdownLive } from "\@savvy-web/changesets";
+* import { ChangelogService, GitHubLive } from "\@savvy-web/changesets";
 *
 * const program = Effect.gen(function* () {
 *   const changelog = yield* ChangelogService;