deltafold 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +278 -4
  2. package/dist/changelog.d.ts +116 -0
  3. package/dist/changelog.d.ts.map +1 -0
  4. package/dist/changelog.js +304 -0
  5. package/dist/changelog.js.map +1 -0
  6. package/dist/document-BZcZo9nr.js +171 -0
  7. package/dist/document-BZcZo9nr.js.map +1 -0
  8. package/dist/document-DWHsgywm.d.ts +257 -0
  9. package/dist/document-DWHsgywm.d.ts.map +1 -0
  10. package/dist/html.d.ts +8 -0
  11. package/dist/html.d.ts.map +1 -0
  12. package/dist/html.js +13 -0
  13. package/dist/html.js.map +1 -0
  14. package/dist/index.d.ts +517 -1
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +2126 -0
  17. package/dist/index.js.map +1 -0
  18. package/dist/markdown.d.ts +8 -0
  19. package/dist/markdown.d.ts.map +1 -0
  20. package/dist/markdown.js +16 -0
  21. package/dist/markdown.js.map +1 -0
  22. package/dist/mdast-DiRsYwPU.js +108 -0
  23. package/dist/mdast-DiRsYwPU.js.map +1 -0
  24. package/dist/package-BfBYnaCz.d.ts +1125 -0
  25. package/dist/package-BfBYnaCz.d.ts.map +1 -0
  26. package/dist/rolldown-runtime-D8jQpDG7.js +12 -0
  27. package/package.json +13 -1
  28. package/src/features/documents/changelog.ts +450 -0
  29. package/src/features/documents/document.ts +357 -0
  30. package/src/features/documents/index.ts +4 -0
  31. package/src/features/documents/public-document.ts +31 -0
  32. package/src/features/documents/sections.ts +44 -0
  33. package/src/features/execution/executor.ts +968 -0
  34. package/src/features/execution/handler.ts +485 -0
  35. package/src/features/execution/settlement.ts +52 -0
  36. package/src/features/package.ts +32 -0
  37. package/src/features/planning/guide.ts +56 -0
  38. package/src/features/planning/history.ts +174 -0
  39. package/src/features/planning/identifiers.ts +43 -0
  40. package/src/features/planning/resolve-error.ts +201 -0
  41. package/src/features/planning/resolve.ts +724 -0
  42. package/src/features/planning/rewrite.ts +331 -0
  43. package/src/features/planning/validate.ts +388 -0
  44. package/src/foundation/action.ts +188 -0
  45. package/src/foundation/change.ts +147 -0
  46. package/src/foundation/instruction.ts +110 -0
  47. package/src/foundation/migration.ts +236 -0
  48. package/src/foundation/plan.ts +245 -0
  49. package/src/foundation/rule.ts +74 -0
  50. package/src/foundation/shortcut.ts +79 -0
  51. package/src/foundation/template.ts +28 -0
  52. package/src/foundation/version.ts +78 -0
  53. package/src/index.ts +22 -11
  54. package/src/renderers/html.ts +12 -0
  55. package/src/renderers/markdown.ts +12 -0
  56. package/src/renderers/mdast.ts +120 -0
  57. package/src/types.ts +2 -0
package/README.md CHANGED
@@ -1,10 +1,284 @@
1
1
  # deltafold
2
2
 
3
- deltafold is a planned TypeScript library for modeling version history,
4
- resolving migration instructions between versions, and generating changelogs.
3
+ deltafold models a package's version history and resolves the migration
4
+ instructions between two versions. You declare changes, actions, versions, and
5
+ migrations once. deltafold plans the route between two supported versions, runs
6
+ your handlers for the planned actions, and renders release notes and upgrade
7
+ guides from the same declarations.
5
8
 
6
- The package has no public API yet. Version 0.0.0 is a placeholder that reserves
7
- the package name. See the [repository](https://github.com/YLfjuk/deltafold) for the design notes and progress.
9
+ The planner never reads or writes your consumers' files: handlers that you or
10
+ your consumers supply do the work, as Promise callbacks or Effect programs. The
11
+ API is experimental and may change before 1.0; open design choices are listed in
12
+ the repository's
13
+ [decisions](https://github.com/YLfjuk/deltafold/blob/main/notes/decisions.md).
14
+
15
+ - [Install](#install)
16
+ - [Declare a history](#declare-a-history)
17
+ - [Resolve a plan](#resolve-a-plan)
18
+ - [Run a plan with Promise handlers](#run-a-plan-with-promise-handlers)
19
+ - [Run a plan with Effect handlers](#run-a-plan-with-effect-handlers)
20
+ - [Simplify routes with rules and shortcuts](#simplify-routes-with-rules-and-shortcuts)
21
+ - [Render changelogs and guides](#render-changelogs-and-guides)
22
+
23
+ ## Install
24
+
25
+ ```sh
26
+ pnpm add deltafold effect
27
+ ```
28
+
29
+ deltafold requires `effect` 4 as a peer dependency and a runtime with a global
30
+ `AbortSignal`, such as Node.js 22.18 or later, Deno, Bun, or a browser. Type
31
+ checking needs DOM or Node.js types for `AbortSignal`.
32
+
33
+ - `deltafold`: declarations, planning, handlers, and executors.
34
+ - `deltafold/changelog`: changelog and document builders.
35
+ - `deltafold/markdown` and `deltafold/html`: renderers for those documents.
36
+
37
+ ## Declare a history
38
+
39
+ An action kind describes an operation and its payload. An action instance is
40
+ one concrete instruction with a stable identifier. A migration names exact
41
+ versions and interpolates the actions it performs.
42
+
43
+ ```ts
44
+ import { Action, Change, History, Migration, Package, Version } from "deltafold";
45
+
46
+ const RenameKey = Action.define<{ file: string; from: string; to: string }>("config.rename", {
47
+ describe: ({ file, from, to }) => `In ${file}, rename "${from}" to "${to}"`,
48
+ });
49
+
50
+ const renameTimeout = RenameKey.make("rename-timeout", {
51
+ file: "app.json",
52
+ from: "timeout",
53
+ to: "requestTimeout",
54
+ });
55
+
56
+ const WidgetsChange = Change.define<{ readonly breaking: boolean }>();
57
+
58
+ const timeoutRenamed = WidgetsChange.make("2026-11-06.rename-timeout", { breaking: true })`
59
+ Rename the timeout option to requestTimeout.
60
+ `;
61
+
62
+ const v1 = Version.make("1.0.0", { changes: [] });
63
+ const v2 = Version.make("2.0.0", { previous: v1, changes: [timeoutRenamed] });
64
+
65
+ const toV2 = Migration.make("1.0.0-to-2.0.0", { from: v1, to: v2, addresses: [timeoutRenamed] })`
66
+ ${Migration.instruction(renameTimeout)`Rename the timeout option. Its value stays in milliseconds.`}
67
+ `;
68
+
69
+ export const history = History.make({ versions: [v1, v2], migrations: [toV2] });
70
+ export const widgets = Package.make("@acme/widgets", { history });
71
+ ```
72
+
73
+ `Version.changes` records what shipped in a release, and `Migration.addresses`
74
+ records which changes a transition handles. `Migration.instruction(action)`
75
+ attaches prose to one action, so the prose disappears from guides when a rule
76
+ removes that action. Use `Action.ref(action)` to mention an action without
77
+ running it again.
78
+
79
+ Declare a transition that needs no work with `Migration.noop`, so that "no
80
+ work" is never inferred from a missing migration:
81
+
82
+ ```ts
83
+ const v201 = Version.make("2.0.1", { previous: v2, changes: [] });
84
+ const patch = Migration.noop("2.0.0-to-2.0.1", { from: v2, to: v201 });
85
+ ```
86
+
87
+ A reverse transition exists only when you declare it. Register the result of
88
+ `Migration.withRevert` in place of the original migration:
89
+
90
+ ```ts
91
+ const restoreTimeout = RenameKey.make("restore-timeout", {
92
+ file: "app.json",
93
+ from: "requestTimeout",
94
+ to: "timeout",
95
+ });
96
+ const reversible = Migration.withRevert(toV2)`${restoreTimeout}`;
97
+ ```
98
+
99
+ `History.validate(history)` returns every declaration problem at once.
100
+
101
+ ## Resolve a plan
102
+
103
+ ```ts
104
+ import { Result } from "effect";
105
+
106
+ const resolved = History.resolve(history, { from: "1.0.0", to: "2.0.0" });
107
+ if (Result.isFailure(resolved)) throw new Error(resolved.failure.message);
108
+
109
+ const plan = resolved.success;
110
+ plan.route.id; // "1.0.0>2.0.0"
111
+ plan.occurrences.map((occurrence) => occurrence.id); // ["1.0.0-to-2.0.0/rename-timeout"]
112
+ ```
113
+
114
+ Resolution returns a `Result` and needs no handlers; a plan with no actions is
115
+ valid. When several routes connect the versions, it fails with
116
+ `AmbiguousRoute`: pass one of the listed route identifiers as `route`, or
117
+ choose a
118
+ [route policy](https://github.com/YLfjuk/deltafold/blob/main/packages/deltafold/src/features/planning/resolve.ts)
119
+ with `policy`. The other failures are described by
120
+ [`ResolveError`](https://github.com/YLfjuk/deltafold/blob/main/packages/deltafold/src/features/planning/resolve-error.ts).
121
+
122
+ A route that deltafold finds never goes down to a shared ancestor and back up
123
+ to another branch. Moving between release branches needs a migration declared
124
+ between them, or a shortcut: a declared shortcut may pass through a shared
125
+ ancestor, because its author asserts that it is equivalent.
126
+ `History.upgrades` and `History.downgrades` list the reachable versions.
127
+
128
+ ## Run a plan with Promise handlers
129
+
130
+ Handlers bind to action instances. A handler either applies its action
131
+ directly, or first runs a read-only `prepare` phase. `prepare` returns
132
+ `Handler.prepared(value)`, and `apply` then receives that value, or
133
+ `Handler.skip(reason)`, which skips the action and reports the reason. In this
134
+ example, `renameKey` and `fileExists` stand for your own file access.
135
+
136
+ ```ts
137
+ import { Executor, Handler } from "deltafold";
138
+
139
+ const handlers = [
140
+ Handler.promise(renameTimeout, {
141
+ prepare: async ({ file }) =>
142
+ (await fileExists(file))
143
+ ? Handler.prepared()
144
+ : Handler.skip("This project has no app.json"),
145
+ apply: async (_prepared, { payload: { file, from, to }, signal }) => {
146
+ await renameKey(file, from, to, { signal });
147
+ },
148
+ }),
149
+ ];
150
+
151
+ try {
152
+ const report = await Executor.runPromise(plan, { handlers });
153
+ } catch (error) {
154
+ if (error instanceof Executor.ExecutionFailed) {
155
+ for (const entry of error.report.occurrences) {
156
+ console.log(entry.occurrence.id, entry.outcome._tag);
157
+ }
158
+ }
159
+ throw error;
160
+ }
161
+ ```
162
+
163
+ - The executor checks that every action has one matching handler before any
164
+ action starts, and rejects with `HandlerCoverageError` otherwise.
165
+ - Migrations run one after another. On failure, no new action starts, actions
166
+ that already started finish, and the run rejects with `ExecutionFailed` and
167
+ the partial report.
168
+ - Nothing is rolled back and progress is not saved: running the plan again
169
+ repeats completed actions.
170
+ - `dryRun: true` runs `prepare` phases and never runs `apply`. A prepare phase
171
+ that may depend on an earlier action is reported `Undetermined`, because the
172
+ dry run does not apply that action.
173
+ - `signal` cancels and `timeout` limits each phase; both reject with
174
+ `ExecutionInterrupted`. Cancellation is cooperative: a callback that ignores
175
+ its signal can keep running after the run ends, and the report marks it as
176
+ possibly still running.
177
+
178
+ Options, errors, and outcomes are documented on
179
+ [`Executor`](https://github.com/YLfjuk/deltafold/blob/main/packages/deltafold/src/features/execution/executor.ts)
180
+ and [`Handler`](https://github.com/YLfjuk/deltafold/blob/main/packages/deltafold/src/features/execution/handler.ts).
181
+
182
+ ## Run a plan with Effect handlers
183
+
184
+ `Handler.effect` keeps the typed errors and services of its Effect. The
185
+ execution requires the handlers' services; provide them, then run it:
186
+
187
+ ```ts
188
+ import { Context, Effect } from "effect";
189
+
190
+ const ConfigFiles = Context.Service<{
191
+ readonly renameKey: (file: string, from: string, to: string) => Effect.Effect<void>;
192
+ }>("app/ConfigFiles");
193
+
194
+ const effectHandler = Handler.effect(renameTimeout, ({ file, from, to }) =>
195
+ Effect.gen(function* () {
196
+ const files = yield* ConfigFiles;
197
+ yield* files.renameKey(file, from, to);
198
+ }),
199
+ );
200
+
201
+ const report = await Effect.runPromise(
202
+ Executor.effect(plan, { handlers: [effectHandler] }).pipe(
203
+ Effect.provideService(ConfigFiles, configFiles),
204
+ ),
205
+ );
206
+ ```
207
+
208
+ Here `configFiles` is your implementation of the service. `Handler.effect`
209
+ also accepts `{ prepare, apply }`. Both phases run in the action's own scope,
210
+ so a resource acquired in `prepare`, such as a lock, stays open until the
211
+ action ends. To cancel an Effect
212
+ execution, interrupt its fiber; it ends as interrupted, without a report.
213
+
214
+ The handler array must cover every action of the history: a missing handler is
215
+ a type error that names the action. Use `Plan.withRuntimeCoverage(plan)` to
216
+ check coverage only at run time, before any action starts. `Handler.promise` can
217
+ declare services too, and `Executor.runPromise` then needs a `services` context
218
+ or layer that covers them.
219
+
220
+ ## Simplify routes with rules and shortcuts
221
+
222
+ Rules replace consecutive actions when you assert that they are equivalent.
223
+ Replacements can feed other rules. Rules never match across parallel branches
224
+ or around a text-only migration.
225
+
226
+ ```ts
227
+ import { Rule } from "deltafold";
228
+
229
+ const cancelRoundTrip = Rule.replace("cancel-timeout-round-trip", {
230
+ match: [renameTimeout, restoreTimeout],
231
+ replacement: [],
232
+ });
233
+ ```
234
+
235
+ `Action.sequence` groups ordered actions. `Action.parallel` groups independent
236
+ branches, each of which may contain a sequence. A shortcut offers an alternative
237
+ to a named sequence of migrations, and must replace every migration of each hop
238
+ it covers.
239
+
240
+ ## Render changelogs and guides
241
+
242
+ ```ts
243
+ import { Changelog } from "deltafold/changelog";
244
+ import * as Markdown from "deltafold/markdown";
245
+
246
+ const changelog = Changelog.make();
247
+
248
+ Markdown.render(changelog.upgrade(plan, { package: widgets }));
249
+ Markdown.render(
250
+ changelog.history(widgets, {
251
+ releases: [Version.withMetadata(v1, {}), Version.withMetadata(v2, {})],
252
+ }),
253
+ );
254
+ ```
255
+
256
+ `changelog.upgrade` prints the plan's resolved instructions; pass
257
+ `explain: true` to list what rules removed. `changelog.history` keeps every
258
+ historical change, including reverted ones, and needs one
259
+ `Version.withMetadata` annotation per release. `Html.render` from
260
+ `deltafold/html` renders the same documents as HTML.
261
+
262
+ Without sections, a release lists all of its changes under "Changes". Sections
263
+ group changes by their metadata, changes that no section selects go under "Other
264
+ changes", and annotations can carry release metadata, such as dates, for
265
+ plugins:
266
+
267
+ ```ts
268
+ const sectioned = Changelog.make<{ date: string }>({
269
+ sections: [
270
+ Changelog.section("breaking", {
271
+ title: "Breaking changes",
272
+ select: (change) => change.metadata.breaking === true,
273
+ }),
274
+ ],
275
+ });
276
+ ```
277
+
278
+ Sections, plugins, and release annotations are documented on
279
+ [`Changelog`](https://github.com/YLfjuk/deltafold/blob/main/packages/deltafold/src/features/documents/changelog.ts)
280
+ and
281
+ [`Document`](https://github.com/YLfjuk/deltafold/blob/main/packages/deltafold/src/features/documents/document.ts).
8
282
 
9
283
  ## License
10
284
 
@@ -0,0 +1,116 @@
1
+ import { _ as Any$1, d as Release, f as Version, h as Change, i as Coverage, m as Any, o as Plan, t as Package } from "./package-BfBYnaCz.js";
2
+ import { C as Text, D as withTitle, E as withLevel, S as Strong, T as append, _ as PluginOptions, a as CodeBlock, b as ReleaseContext, c as Emphasis, d as Inline, f as InlineInput, g as Plugin, h as Paragraph, i as Code, l as History, m as List, n as Block, o as Document, p as Link, r as Body, s as DocumentError, t as Anchor, u as HistoryContext, v as PluginOutput, w as Title, x as Section, y as Release$1 } from "./document-DWHsgywm.js";
3
+ declare namespace changelog_d_exports {
4
+ export { Changelog, GuideOptions, HistoryOptions, Options, ReleaseMetadataError, SectionDefinition, make, section };
5
+ }
6
+ /**
7
+ * A change section of a release. The first section whose `select` matches wins. Selectors
8
+ * read the metadata that the consumer declared on each change.
9
+ *
10
+ * @since @next
11
+ */
12
+ type SectionDefinition = {
13
+ readonly _tag: "ChangelogSection";
14
+ readonly id: string;
15
+ readonly title: string;
16
+ readonly select: (change: Change) => boolean;
17
+ };
18
+ /** @since @next */
19
+ declare const section: (id: string, options: {
20
+ readonly title: string;
21
+ readonly select: (change: Change) => boolean;
22
+ }) => SectionDefinition;
23
+ declare const ReleaseMetadataError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
24
+ readonly _tag: "ReleaseMetadataError";
25
+ } & Readonly<A>;
26
+ /**
27
+ * Release metadata does not match the package history.
28
+ *
29
+ * @since @next
30
+ */
31
+ declare class ReleaseMetadataError extends ReleaseMetadataError_base<{
32
+ readonly reason: "duplicate" | "unrelated" | "missing";
33
+ readonly versions: ReadonlyArray<string>;
34
+ readonly message: string;
35
+ }> {}
36
+ /** @since @next */
37
+ type HistoryOptions<M> = {
38
+ /**
39
+ * Release metadata annotations, one per included version, in any order. Missing,
40
+ * duplicate, or unrelated annotations throw `ReleaseMetadataError`.
41
+ */
42
+ readonly releases: ReadonlyArray<Release<M>>;
43
+ /** The versions to include. Defaults to every version in the package history. */
44
+ readonly versions?: ReadonlyArray<Version>;
45
+ };
46
+ /** @since @next */
47
+ type GuideOptions = {
48
+ /** The modeled package, for the guide title. */
49
+ readonly package?: Package;
50
+ /** Adds a section that lists omitted instructions and the rules responsible. */
51
+ readonly explain?: boolean;
52
+ };
53
+ /** @since @next */
54
+ type Changelog<M> = {
55
+ readonly sections: ReadonlyArray<SectionDefinition>;
56
+ readonly plugins: ReadonlyArray<Plugin<M>>;
57
+ /** A document for changes that are not assigned to a release yet. */
58
+ readonly change: (change: Any | ReadonlyArray<Any>, options?: {
59
+ readonly title?: string;
60
+ }) => Document;
61
+ /** The section for one release. */
62
+ readonly release: (pkg: Package, release: Release<M>) => Document;
63
+ /**
64
+ * Release history, titled with the package name. Historical changes stay, including
65
+ * reverted ones. Releases are listed newest first by semver when every identifier
66
+ * parses, and in reverse registration order otherwise.
67
+ */
68
+ readonly history: (pkg: Package, options: HistoryOptions<M>) => Document;
69
+ /**
70
+ * The resolved instructions of a plan. Cancelled instructions are omitted. Downgrade
71
+ * plans are titled as downgrades.
72
+ */
73
+ readonly upgrade: (plan: Plan<Any$1, Coverage>, options?: GuideOptions) => Document;
74
+ };
75
+ /** @since @next */
76
+ type Options<M> = {
77
+ readonly sections?: ReadonlyArray<SectionDefinition>;
78
+ readonly plugins?: ReadonlyArray<Plugin<M>>;
79
+ /**
80
+ * The section for changes that no section selects, or `false` to leave them out. Its
81
+ * title defaults to "Changes" without `sections` and to "Other changes" with them.
82
+ */
83
+ readonly other?: {
84
+ readonly title: string;
85
+ } | false;
86
+ };
87
+ /**
88
+ * Configures sections and plugins for changelog documents. Without `sections`, a release
89
+ * lists all of its changes in one "Changes" section.
90
+ *
91
+ * @example
92
+ * ```ts
93
+ * const changelog = Changelog.make<ReleaseMetadata>({
94
+ * sections: [
95
+ * Changelog.section("breaking", {
96
+ * title: "Breaking changes",
97
+ * select: (change) => change.metadata.breaking === true,
98
+ * }),
99
+ * Changelog.section("fixes", {
100
+ * title: "Fixes",
101
+ * select: (change) => change.metadata.kind === "fixed",
102
+ * }),
103
+ * ],
104
+ * plugins: [contributorsPlugin],
105
+ * });
106
+ * Markdown.render(changelog.history(widgets, { releases: [release100, release200] }));
107
+ * ```
108
+ *
109
+ * @since @next
110
+ */
111
+ declare const make: <M = unknown>(options?: Options<M>) => Changelog<M>;
112
+ declare namespace public_document_d_exports {
113
+ export { Anchor, Block, Body, Code, CodeBlock, Document, DocumentError, Emphasis, History, HistoryContext, Inline, InlineInput, Link, List, Paragraph, Plugin, PluginOptions, PluginOutput, Release$1 as Release, ReleaseContext, Section, Strong, Text, Title, append, withLevel, withTitle };
114
+ }
115
+ export { changelog_d_exports as Changelog, public_document_d_exports as Document };
116
+ //# sourceMappingURL=changelog.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"changelog.d.ts","names":["Change.Change","Document.Plugin","Change.Any","Document.Document","Action.Any"],"sources":["../src/features/documents/changelog.ts","../src/features/documents/public-document.ts"],"mappings":";;;;;;;;;;;KAiBY;WACF;WACA;WACA;WACA,SAAS,QAAQA;;;cAId,UAAO,YACT;WACU;WAAwB,SAAS,QAAQA;MAC3D;;;;;;;;;cAOU,6BAA6B;WAChC;WACA,UAAU;WACV;;;KAIE,eAAe;;;;;WAKjB,UAAU,cAAc,QAAQ;;WAEhC,WAAW,cAAc;;;KAIvB;;WAEF,UAAU;;WAEV;;;KAIE,UAAU;WACZ,UAAU,cAAc;WACxB,SAAS,cAAcC,OAAgB;;WAEvC,SACR,QAAQC,MAAa,cAAcA,MACnC;aAAqB;QACjBC;;WAEI,UAAU,KAAK,SAAS,SAAS,QAAQ,OAAOA;;;;;;WAMhD,UAAU,KAAK,SAAS,SAAS,eAAe,OAAOA;;;;;WAKvD,UACR,MAAM,KAAKC,OAAY,WACvB,UAAU,iBACND;;;KAIM,QAAQ;WACV,WAAW,cAAc;WACzB,UAAU,cAAcF,OAAgB;;;;;WAKxC;aAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6HhB,OAAQ,aAAW,UAAW,QAAQ,OAAU,UAAU"}