deltafold 0.0.0 → 0.0.1

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 +274 -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 +378 -1
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +2058 -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 +826 -0
  34. package/src/features/execution/handler.ts +257 -0
  35. package/src/features/execution/settlement.ts +49 -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
@@ -0,0 +1 @@
1
+ {"version":3,"file":"package-BfBYnaCz.d.ts","names":["Action.Ref","Action.Any","Any","Sequence","Step","Parallel","ActionsOf","define","Any","make","Change.Any","Options","make","Action.Any","Action.Ref","Action.Step","Change.Any","Any","ActionsOf","ChangesOf","make","Action.ActionsOf","Action.Any","Action.Parallel","Action.Step","Any","ActionsOf","Action.Any","Change.Any","Migration.Any","Migration.Migration","Any","ActionsOf","ChangesOf","make","Rule.Any","Action.Any","Migration.Any","Action.Concurrency","Action.Ref","Shortcut.Any","Change.Any","Any","ActionsOf","Action.Any","Change.Any","Migration.Any","Rule.Any","Shortcut.Any","make","Migration.ActionsOf","Rule.ActionsOf","Shortcut.ActionsOf","Migration.ChangesOf","Shortcut.ChangesOf","Action.Any"],"sources":["../src/foundation/template.ts","../src/foundation/instruction.ts","../src/foundation/action.ts","../src/foundation/change.ts","../src/foundation/version.ts","../src/foundation/migration.ts","../src/foundation/rule.ts","../src/foundation/shortcut.ts","../src/foundation/plan.ts","../src/features/planning/validate.ts","../src/features/planning/resolve-error.ts","../src/features/planning/resolve.ts","../src/features/planning/history.ts","../src/features/package.ts"],"mappings":"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"}
@@ -0,0 +1,12 @@
1
+ // \0rolldown/runtime.js
2
+ var __defProp = Object.defineProperty;
3
+ var __exportAll = (all, no_symbols) => {
4
+ let target = {};
5
+ for (var name in all) __defProp(target, name, {
6
+ get: all[name],
7
+ enumerable: true
8
+ });
9
+ if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
10
+ return target;
11
+ };
12
+ export { __exportAll as t };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "deltafold",
3
- "version": "0.0.0",
3
+ "version": "0.0.1",
4
4
  "description": "Model version history, resolve migration instructions between versions, and generate changelogs.",
5
5
  "keywords": [
6
6
  "changelog",
@@ -31,11 +31,23 @@
31
31
  "sideEffects": false,
32
32
  "exports": {
33
33
  ".": "./dist/index.js",
34
+ "./changelog": "./dist/changelog.js",
35
+ "./html": "./dist/html.js",
36
+ "./markdown": "./dist/markdown.js",
34
37
  "./package.json": "./package.json"
35
38
  },
36
39
  "publishConfig": {
37
40
  "access": "public"
38
41
  },
42
+ "dependencies": {
43
+ "@types/hast": "3.0.5",
44
+ "@types/mdast": "4.0.4",
45
+ "dedent": "1.7.2",
46
+ "hast-util-to-html": "9.0.5",
47
+ "mdast-util-to-hast": "13.2.1",
48
+ "mdast-util-to-markdown": "2.2.0",
49
+ "micromark-util-sanitize-uri": "2.0.1"
50
+ },
39
51
  "devDependencies": {
40
52
  "@arethetypeswrong/core": "0.18.5",
41
53
  "@effect/vitest": "4.1.2",
@@ -0,0 +1,450 @@
1
+ import { Array as Arr, Data, Order, Result, SemVer } from "effect";
2
+
3
+ import type * as Action from "../../foundation/action.ts";
4
+ import * as Change from "../../foundation/change.ts";
5
+ import type { Prose } from "../../foundation/instruction.ts";
6
+ import type { Coverage, GuideItem, Plan, Step } from "../../foundation/plan.ts";
7
+ import type { Release, Version } from "../../foundation/version.ts";
8
+ import type { Package } from "../package.ts";
9
+ import * as Document from "./document.ts";
10
+ import { asRelease, blocksOf, insertAll } from "./sections.ts";
11
+
12
+ /**
13
+ * A change section of a release. The first section whose `select` matches wins. Selectors
14
+ * read the metadata that the consumer declared on each change.
15
+ *
16
+ * @since @next
17
+ */
18
+ export type SectionDefinition = {
19
+ readonly _tag: "ChangelogSection";
20
+ readonly id: string;
21
+ readonly title: string;
22
+ readonly select: (change: Change.Change) => boolean;
23
+ };
24
+
25
+ /** @since @next */
26
+ export const section = (
27
+ id: string,
28
+ options: { readonly title: string; readonly select: (change: Change.Change) => boolean },
29
+ ): SectionDefinition => ({ _tag: "ChangelogSection", id, ...options });
30
+
31
+ /**
32
+ * Release metadata does not match the package history.
33
+ *
34
+ * @since @next
35
+ */
36
+ export class ReleaseMetadataError extends Data.TaggedError("ReleaseMetadataError")<{
37
+ readonly reason: "duplicate" | "unrelated" | "missing";
38
+ readonly versions: ReadonlyArray<string>;
39
+ readonly message: string;
40
+ }> {}
41
+
42
+ /** @since @next */
43
+ export type HistoryOptions<M> = {
44
+ /**
45
+ * Release metadata annotations, one per included version, in any order. Missing,
46
+ * duplicate, or unrelated annotations throw `ReleaseMetadataError`.
47
+ */
48
+ readonly releases: ReadonlyArray<Release<M>>;
49
+ /** The versions to include. Defaults to every version in the package history. */
50
+ readonly versions?: ReadonlyArray<Version>;
51
+ };
52
+
53
+ /** @since @next */
54
+ export type GuideOptions = {
55
+ /** The modeled package, for the guide title. */
56
+ readonly package?: Package;
57
+ /** Adds a section that lists omitted instructions and the rules responsible. */
58
+ readonly explain?: boolean;
59
+ };
60
+
61
+ /** @since @next */
62
+ export type Changelog<M> = {
63
+ readonly sections: ReadonlyArray<SectionDefinition>;
64
+ readonly plugins: ReadonlyArray<Document.Plugin<M>>;
65
+ /** A document for changes that are not assigned to a release yet. */
66
+ readonly change: (
67
+ change: Change.Any | ReadonlyArray<Change.Any>,
68
+ options?: { readonly title?: string },
69
+ ) => Document.Document;
70
+ /** The section for one release. */
71
+ readonly release: (pkg: Package, release: Release<M>) => Document.Document;
72
+ /**
73
+ * Release history, titled with the package name. Historical changes stay, including
74
+ * reverted ones. Releases are listed newest first by semver when every identifier
75
+ * parses, and in reverse registration order otherwise.
76
+ */
77
+ readonly history: (pkg: Package, options: HistoryOptions<M>) => Document.Document;
78
+ /**
79
+ * The resolved instructions of a plan. Cancelled instructions are omitted. Downgrade
80
+ * plans are titled as downgrades.
81
+ */
82
+ readonly upgrade: (
83
+ plan: Plan<Action.Any, Coverage>,
84
+ options?: GuideOptions,
85
+ ) => Document.Document;
86
+ };
87
+
88
+ /** @since @next */
89
+ export type Options<M> = {
90
+ readonly sections?: ReadonlyArray<SectionDefinition>;
91
+ readonly plugins?: ReadonlyArray<Document.Plugin<M>>;
92
+ /**
93
+ * The section for changes that no section selects, or `false` to leave them out. Its
94
+ * title defaults to "Changes" without `sections` and to "Other changes" with them.
95
+ */
96
+ readonly other?: { readonly title: string } | false;
97
+ };
98
+
99
+ const paragraphsOf = (text: string): ReadonlyArray<Document.Paragraph> =>
100
+ text
101
+ .split(/\n\s*\n/)
102
+ .map((part) => part.replace(/\s*\n\s*/g, " ").trim())
103
+ .filter((part) => part !== "")
104
+ .map((part) => Document.Paragraph(part));
105
+
106
+ /**
107
+ * Selectors read metadata fields by name. Reading any field of an object yields a value
108
+ * or `undefined`, so viewing the metadata as fields of type `unknown` is sound.
109
+ */
110
+ // oxlint-disable-next-line typescript/no-unsafe-type-assertion
111
+ const selectable = (change: Change.Any) => change as Change.Change;
112
+
113
+ const changeList = (changes: ReadonlyArray<Change.Any>) =>
114
+ Document.List(changes.map((change) => paragraphsOf(change.description)));
115
+
116
+ const knows = (pkg: Package, version: Version) =>
117
+ pkg.history.versions.some((known) => known.id === version.id);
118
+
119
+ const releaseOrder = (versions: ReadonlyArray<Version>): ReadonlyArray<Version> => {
120
+ const parsed = versions.map((version) => SemVer.parse(version.id));
121
+ if (!parsed.every(Result.isSuccess)) return Arr.reverse(versions);
122
+
123
+ return Arr.sort(
124
+ versions,
125
+ Order.flip(
126
+ Order.mapInput(SemVer.Order, (version: Version) => SemVer.parseUnsafe(version.id)),
127
+ ),
128
+ );
129
+ };
130
+
131
+ const occurrenceBlocks = (action: Action.Any, prose: Prose | undefined) =>
132
+ prose === undefined ? [Document.Paragraph(action.description)] : guideBlocks(prose);
133
+
134
+ /** Builds guide blocks: prose becomes paragraphs; groups become lists. */
135
+ const guideBlocks = (
136
+ items: ReadonlyArray<GuideItem | Prose[number]>,
137
+ ): ReadonlyArray<Document.Block> => {
138
+ const blocks: Array<Document.Block> = [];
139
+ let current: Array<Document.Inline> = [];
140
+ const flush = () => {
141
+ const trimmed = trimInlines(current);
142
+ if (trimmed.length > 0) blocks.push(Document.Paragraph(trimmed));
143
+ current = [];
144
+ };
145
+ for (const item of items) {
146
+ switch (item._tag) {
147
+ case "Text": {
148
+ const [first = "", ...rest] = item.text.split(/\n\s*\n/);
149
+ current.push(Document.Text(first.replace(/\s*\n\s*/g, " ")));
150
+ for (const part of rest) {
151
+ flush();
152
+ current.push(Document.Text(part.replace(/\s*\n\s*/g, " ")));
153
+ }
154
+ break;
155
+ }
156
+ case "ActionRef":
157
+ current.push(Document.Text(item.action.description));
158
+ break;
159
+ case "Occurrence": {
160
+ const { action, instruction } = item.occurrence;
161
+ if (instruction === undefined && trimInlines(current).length > 0) {
162
+ current.push(Document.Text(action.description));
163
+ break;
164
+ }
165
+ flush();
166
+ blocks.push(...occurrenceBlocks(action, instruction?.content));
167
+ break;
168
+ }
169
+ case "Group":
170
+ flush();
171
+ blocks.push(Document.List(item.children.map((child) => guideBlocks(child))));
172
+ break;
173
+ }
174
+ }
175
+ flush();
176
+
177
+ return blocks;
178
+ };
179
+
180
+ const trimInlines = (values: ReadonlyArray<Document.Inline>): ReadonlyArray<Document.Inline> => {
181
+ const result = values.flatMap((value) =>
182
+ value._tag === "Text" && value.value === "" ? [] : [value],
183
+ );
184
+ const first = result[0];
185
+ const last = result.at(-1);
186
+ if (first?._tag === "Text") result[0] = Document.Text(first.value.trimStart());
187
+ if (last?._tag === "Text") result[result.length - 1] = Document.Text(last.value.trimEnd());
188
+
189
+ return result.flatMap((value) => (value._tag === "Text" && value.value === "" ? [] : [value]));
190
+ };
191
+
192
+ // Generated sections take their identity from model identifiers under a kind that has no
193
+ // `/`, so any version or migration identifier renders without colliding with others.
194
+ const stepId = (step: Step) =>
195
+ `deltafold/${step.direction === "forward" ? "step" : "revert"}/${step.migration.id}`;
196
+
197
+ /**
198
+ * Configures sections and plugins for changelog documents. Without `sections`, a release
199
+ * lists all of its changes in one "Changes" section.
200
+ *
201
+ * @example
202
+ * ```ts
203
+ * const changelog = Changelog.make<ReleaseMetadata>({
204
+ * sections: [
205
+ * Changelog.section("breaking", {
206
+ * title: "Breaking changes",
207
+ * select: (change) => change.metadata.breaking === true,
208
+ * }),
209
+ * Changelog.section("fixes", {
210
+ * title: "Fixes",
211
+ * select: (change) => change.metadata.kind === "fixed",
212
+ * }),
213
+ * ],
214
+ * plugins: [contributorsPlugin],
215
+ * });
216
+ * Markdown.render(changelog.history(widgets, { releases: [release100, release200] }));
217
+ * ```
218
+ *
219
+ * @since @next
220
+ */
221
+ export const make = <M = unknown>(options: Options<M> = {}): Changelog<M> => {
222
+ const sections = options.sections ?? [];
223
+ const plugins = options.plugins ?? [];
224
+ const other = options.other ?? { title: sections.length === 0 ? "Changes" : "Other changes" };
225
+
226
+ const changeSections = (
227
+ changes: ReadonlyArray<Change.Any>,
228
+ ): ReadonlyArray<Document.Section> => {
229
+ const grouped = new Map<string, Array<Change.Any>>();
230
+ const unmatched: Array<Change.Any> = [];
231
+ for (const change of changes) {
232
+ const match = sections.find((definition) => definition.select(selectable(change)));
233
+ if (match === undefined) {
234
+ unmatched.push(change);
235
+ continue;
236
+ }
237
+ const list = grouped.get(match.id) ?? [];
238
+ list.push(change);
239
+ grouped.set(match.id, list);
240
+ }
241
+ const result = sections.flatMap((definition) => {
242
+ const matched = grouped.get(definition.id);
243
+ if (matched === undefined) return [];
244
+
245
+ return [
246
+ Document.Section(definition.id, {
247
+ title: definition.title,
248
+ children: [changeList(matched)],
249
+ }),
250
+ ];
251
+ });
252
+ if (other !== false && unmatched.length > 0) {
253
+ result.push(
254
+ Document.generatedSection("deltafold/other", {
255
+ title: other.title,
256
+ children: [changeList(unmatched)],
257
+ }),
258
+ );
259
+ }
260
+
261
+ return result;
262
+ };
263
+
264
+ const releaseSection = (context: Document.ReleaseContext<M>): Document.Section => {
265
+ const base = asRelease(
266
+ Document.generatedSection(`deltafold/release/${context.version.id}`, {
267
+ title: context.version.id,
268
+ children: changeSections(context.version.changes),
269
+ }),
270
+ context.version,
271
+ );
272
+
273
+ return insertAll(
274
+ base,
275
+ plugins.flatMap((plugin) =>
276
+ plugin.scope === Document.Release
277
+ ? [{ at: plugin.at, blocks: blocksOf(plugin.resolve(context)) }]
278
+ : [],
279
+ ),
280
+ );
281
+ };
282
+
283
+ const requireKnown = (pkg: Package, releases: ReadonlyArray<Release<M>>) => {
284
+ const unrelated = releases.flatMap((release) =>
285
+ knows(pkg, release.version) ? [] : [release.version.id],
286
+ );
287
+ if (unrelated.length > 0) {
288
+ throw new ReleaseMetadataError({
289
+ reason: "unrelated",
290
+ versions: unrelated,
291
+ message: `Release metadata for ${unrelated.map((id) => `"${id}"`).join(", ")} does not belong to the history of "${pkg.name}".`,
292
+ });
293
+ }
294
+ };
295
+
296
+ return {
297
+ sections,
298
+ plugins,
299
+ change: (input, changeOptions = {}) => {
300
+ const changes = Arr.ensure(input);
301
+
302
+ return {
303
+ _tag: "Document",
304
+ kind: "change",
305
+ children: [
306
+ Document.generatedSection("deltafold/unreleased", {
307
+ title: changeOptions.title ?? "Unreleased",
308
+ children: changeSections(changes),
309
+ }),
310
+ ],
311
+ };
312
+ },
313
+ release: (pkg, release) => {
314
+ requireKnown(pkg, [release]);
315
+
316
+ return {
317
+ _tag: "Document",
318
+ kind: "release",
319
+ children: [
320
+ releaseSection({
321
+ package: pkg,
322
+ version: release.version,
323
+ metadata: release.metadata,
324
+ }),
325
+ ],
326
+ };
327
+ },
328
+ history: (pkg, historyOptions) => {
329
+ const { releases } = historyOptions;
330
+ requireKnown(pkg, releases);
331
+ const byVersion = new Map<string, Release<M>>();
332
+ const duplicates = new Set<string>();
333
+ for (const release of releases) {
334
+ if (byVersion.has(release.version.id)) duplicates.add(release.version.id);
335
+ byVersion.set(release.version.id, release);
336
+ }
337
+ if (duplicates.size > 0) {
338
+ throw new ReleaseMetadataError({
339
+ reason: "duplicate",
340
+ versions: [...duplicates],
341
+ message: `Release metadata is supplied more than once for ${[...duplicates].map((id) => `"${id}"`).join(", ")}.`,
342
+ });
343
+ }
344
+ const included = historyOptions.versions ?? pkg.history.versions;
345
+ const missing = included.flatMap((version) =>
346
+ byVersion.has(version.id) ? [] : [version.id],
347
+ );
348
+ if (missing.length > 0) {
349
+ throw new ReleaseMetadataError({
350
+ reason: "missing",
351
+ versions: missing,
352
+ message: `Release metadata is missing for ${missing.map((id) => `"${id}"`).join(", ")}. Supply an annotation for each, or limit the document with the \`versions\` option.`,
353
+ });
354
+ }
355
+
356
+ const contexts = releaseOrder(included).flatMap((version) => {
357
+ const release = byVersion.get(version.id);
358
+
359
+ return release === undefined
360
+ ? []
361
+ : [{ package: pkg, version, metadata: release.metadata }];
362
+ });
363
+ const root = insertAll(
364
+ Document.generatedSection("deltafold/package", {
365
+ title: pkg.name,
366
+ children: contexts.map(releaseSection),
367
+ }),
368
+ plugins.flatMap((plugin) =>
369
+ plugin.scope === Document.History
370
+ ? [
371
+ {
372
+ at: plugin.at,
373
+ blocks: blocksOf(
374
+ plugin.resolve({ package: pkg, releases: contexts }),
375
+ ),
376
+ },
377
+ ]
378
+ : [],
379
+ ),
380
+ );
381
+
382
+ return { _tag: "Document", kind: "history", children: [root] };
383
+ },
384
+ upgrade: (plan, guideOptions = {}) => {
385
+ const verb =
386
+ plan.direction === "downgrade"
387
+ ? "Downgrade"
388
+ : plan.direction === "upgrade"
389
+ ? "Upgrade"
390
+ : "Migrate";
391
+ const subject =
392
+ guideOptions.package === undefined ? "" : ` ${guideOptions.package.name}`;
393
+ const shown = plan.steps.filter((step) => !step.omitted);
394
+ const sharedEndpoints = (step: Step) =>
395
+ shown.filter(
396
+ (candidate) =>
397
+ candidate.from.id === step.from.id && candidate.to.id === step.to.id,
398
+ ).length > 1;
399
+ const stepSections = shown.map((step) =>
400
+ Document.generatedSection(stepId(step), {
401
+ title: `${step.from.id} to ${step.to.id}${sharedEndpoints(step) ? ` (${step.migration.id})` : ""}`,
402
+ children: guideBlocks(step.guide),
403
+ }),
404
+ );
405
+ const children: Array<Document.Block> =
406
+ stepSections.length === 0
407
+ ? [Document.Paragraph("No migration work is needed.")]
408
+ : stepSections;
409
+ if (guideOptions.explain === true && plan.explanations.length > 0) {
410
+ children.push(
411
+ Document.generatedSection("deltafold/explanations", {
412
+ title: "Omitted instructions",
413
+ children: [
414
+ Document.List(
415
+ plan.explanations.map((explanation) => {
416
+ if (explanation._tag === "OmittedStep") {
417
+ return explanation.reason === "noop"
418
+ ? `Migration "${explanation.migration.id}" needs no work.`
419
+ : `Rules removed every action of migration "${explanation.migration.id}".`;
420
+ }
421
+ const removed = explanation.removed.map(
422
+ (occurrence) => occurrence.action.description,
423
+ );
424
+ const produced = explanation.produced.map(
425
+ (occurrence) => occurrence.action.description,
426
+ );
427
+
428
+ return produced.length === 0
429
+ ? `Rule "${explanation.rule.id}" cancelled: ${removed.join("; ")}.`
430
+ : `Rule "${explanation.rule.id}" replaced ${removed.join("; ")} with ${produced.join("; ")}.`;
431
+ }),
432
+ ),
433
+ ],
434
+ }),
435
+ );
436
+ }
437
+
438
+ return {
439
+ _tag: "Document",
440
+ kind: plan.direction === "downgrade" ? "downgrade" : "upgrade",
441
+ children: [
442
+ Document.generatedSection("deltafold/guide", {
443
+ title: `${verb}${subject} from ${plan.from.id} to ${plan.to.id}`,
444
+ children,
445
+ }),
446
+ ],
447
+ };
448
+ },
449
+ };
450
+ };