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
@@ -0,0 +1,245 @@
1
+ import type * as Action from "./action.ts";
2
+ import type * as Change from "./change.ts";
3
+ import type { Instruction, Text } from "./instruction.ts";
4
+ import type * as Migration from "./migration.ts";
5
+ import type * as Rule from "./rule.ts";
6
+ import type * as Shortcut from "./shortcut.ts";
7
+ import type { Version } from "./version.ts";
8
+
9
+ /**
10
+ * Which side of a migration runs.
11
+ *
12
+ * @since @next
13
+ */
14
+ export type Direction = "forward" | "revert";
15
+
16
+ /**
17
+ * How an occurrence entered the plan.
18
+ *
19
+ * @since @next
20
+ */
21
+ export type Origin =
22
+ | { readonly _tag: "Declared" }
23
+ | {
24
+ readonly _tag: "Replacement";
25
+ readonly rule: Rule.Any;
26
+ /** The occurrences the rule replaced, in order. */
27
+ readonly replaces: ReadonlyArray<Occurrence>;
28
+ };
29
+
30
+ /**
31
+ * One execution of an action instance in a plan. Its `id` is stable across prose edits:
32
+ * it combines the migration, direction, and action identifiers, or the rule and the
33
+ * replaced occurrences for a replacement.
34
+ *
35
+ * @since @next
36
+ */
37
+ export type Occurrence<A extends Action.Any = Action.Any> = {
38
+ readonly _tag: "Occurrence";
39
+ /**
40
+ * Unique within the plan. Built from the migration, direction, and action identifiers,
41
+ * or from the rule and the replaced occurrences. Separator characters in author
42
+ * identifiers are escaped with a backslash, so identifiers never collide.
43
+ */
44
+ readonly id: string;
45
+ readonly action: A;
46
+ /** The migration whose step contains this occurrence. */
47
+ readonly migration: Migration.Any;
48
+ readonly direction: Direction;
49
+ /** The instruction block that declared this occurrence, if any. */
50
+ readonly instruction: Instruction | undefined;
51
+ readonly origin: Origin;
52
+ };
53
+
54
+ /** @since @next */
55
+ export type Sequence<A extends Action.Any = Action.Any> = {
56
+ readonly _tag: "Sequence";
57
+ readonly children: ReadonlyArray<Node<A>>;
58
+ };
59
+
60
+ /** @since @next */
61
+ export type Parallel<A extends Action.Any = Action.Any> = {
62
+ readonly _tag: "Parallel";
63
+ readonly branches: ReadonlyArray<Node<A>>;
64
+ readonly concurrency: Action.Concurrency;
65
+ };
66
+
67
+ /**
68
+ * The declared execution structure.
69
+ *
70
+ * @since @next
71
+ */
72
+ export type Node<A extends Action.Any = Action.Any> = Occurrence<A> | Sequence<A> | Parallel<A>;
73
+
74
+ /**
75
+ * Resolved prose for a guide. Occurrences render as their instruction or description.
76
+ *
77
+ * @since @next
78
+ */
79
+ export type GuideItem<A extends Action.Any = Action.Any> =
80
+ | Text
81
+ | Action.Ref
82
+ | { readonly _tag: "Occurrence"; readonly occurrence: Occurrence<A> }
83
+ | {
84
+ readonly _tag: "Group";
85
+ readonly kind: "Sequence" | "Parallel";
86
+ /** One entry per retained child or branch. */
87
+ readonly children: ReadonlyArray<ReadonlyArray<GuideItem<A>>>;
88
+ };
89
+
90
+ /**
91
+ * One migration in the route. Steps are sequential barriers: a step starts only after
92
+ * the previous step completed.
93
+ *
94
+ * @since @next
95
+ */
96
+ export type Step<A extends Action.Any = Action.Any> = {
97
+ readonly _tag: "Step";
98
+ readonly migration: Migration.Any;
99
+ readonly direction: Direction;
100
+ readonly from: Version;
101
+ readonly to: Version;
102
+ readonly node: Sequence<A>;
103
+ /** Resolved guide content. Empty when the step is omitted from the guide. */
104
+ readonly guide: ReadonlyArray<GuideItem<A>>;
105
+ /**
106
+ * Whether the normal resolved guide leaves this step out: a noop, or a migration whose
107
+ * actions were all removed by rules.
108
+ */
109
+ readonly omitted: boolean;
110
+ };
111
+
112
+ /**
113
+ * Why the plan differs from the declared migrations.
114
+ *
115
+ * @since @next
116
+ */
117
+ export type Explanation =
118
+ | {
119
+ readonly _tag: "Rewrite";
120
+ readonly rule: Rule.Any;
121
+ readonly removed: ReadonlyArray<Occurrence>;
122
+ readonly produced: ReadonlyArray<Occurrence>;
123
+ }
124
+ | {
125
+ readonly _tag: "OmittedStep";
126
+ readonly migration: Migration.Any;
127
+ readonly direction: Direction;
128
+ readonly reason: "noop" | "all-actions-removed";
129
+ };
130
+
131
+ /**
132
+ * A hop in a route: the migrations between two versions, or a shortcut.
133
+ *
134
+ * @since @next
135
+ */
136
+ export type Hop =
137
+ | {
138
+ readonly _tag: "Migrations";
139
+ readonly from: Version;
140
+ readonly to: Version;
141
+ /**
142
+ * The migration side that moves between these versions. Validation allows one
143
+ * side per transition, so this holds exactly one entry.
144
+ */
145
+ readonly migrations: ReadonlyArray<{
146
+ readonly migration: Migration.Any;
147
+ readonly direction: Direction;
148
+ }>;
149
+ }
150
+ | {
151
+ readonly _tag: "Shortcut";
152
+ readonly from: Version;
153
+ readonly to: Version;
154
+ readonly shortcut: Shortcut.Any;
155
+ };
156
+
157
+ /** @since @next */
158
+ export type Route = {
159
+ /**
160
+ * Identifies the route for explicit selection: version identifiers joined by `>`,
161
+ * with shortcut hops written as `[shortcut-id]`. A backslash escapes `\`, `>`, `[`,
162
+ * and `]` inside identifiers, so a version `a>b` appears as `a\>b`.
163
+ */
164
+ readonly id: string;
165
+ readonly hops: ReadonlyArray<Hop>;
166
+ };
167
+
168
+ /**
169
+ * How the requested target relates to the source in release ancestry.
170
+ *
171
+ * @since @next
172
+ */
173
+ export type RequestDirection = "none" | "upgrade" | "downgrade" | "cross-branch";
174
+
175
+ /**
176
+ * When executors check handler coverage. Static plans also expose uncovered actions in
177
+ * the execution's type.
178
+ *
179
+ * @since @next
180
+ */
181
+ export type Coverage = "static" | "runtime";
182
+
183
+ /**
184
+ * A resolved, optimized route between two versions. Every step stays traceable to its
185
+ * migration and the changes that migration addresses.
186
+ *
187
+ * @since @next
188
+ */
189
+ export type Plan<
190
+ A extends Action.Any = Action.Any,
191
+ C extends Coverage = "static",
192
+ Ch extends Change.Any = Change.Any,
193
+ > = {
194
+ readonly _tag: "Plan";
195
+ readonly from: Version;
196
+ readonly to: Version;
197
+ readonly direction: RequestDirection;
198
+ readonly route: Route;
199
+ readonly steps: ReadonlyArray<Step<A>>;
200
+ /** Occurrences in plan order. */
201
+ readonly occurrences: ReadonlyArray<Occurrence<A>>;
202
+ /** The changes addressed by the route's migrations. */
203
+ readonly changes: ReadonlyArray<Ch>;
204
+ readonly explanations: ReadonlyArray<Explanation>;
205
+ /**
206
+ * Whether executors check handler coverage only at run time. Plans resolved from a
207
+ * history are checked statically against its conservative action union.
208
+ */
209
+ readonly coverage: C;
210
+ };
211
+
212
+ /**
213
+ * Any plan.
214
+ *
215
+ * @since @next
216
+ */
217
+ export type Any = Plan<any, any>;
218
+
219
+ /**
220
+ * The action instances of a plan.
221
+ *
222
+ * @since @next
223
+ */
224
+ export type ActionsOf<P> = P extends Plan<infer A, any> ? A : never;
225
+
226
+ /**
227
+ * Whether the plan has no action occurrences. An empty plan is valid.
228
+ *
229
+ * @since @next
230
+ */
231
+ export const isEmpty = (plan: Any): boolean => plan.occurrences.length === 0;
232
+
233
+ /**
234
+ * Marks a plan for run-time coverage checks only. Use it for dynamically selected or
235
+ * loaded plans whose action union is not known statically. Executors still reject
236
+ * missing handlers before any action body runs.
237
+ *
238
+ * @since @next
239
+ */
240
+ export const withRuntimeCoverage = <A extends Action.Any, Ch extends Change.Any>(
241
+ plan: Plan<A, Coverage, Ch>,
242
+ ): Plan<A, "runtime", Ch> => ({
243
+ ...plan,
244
+ coverage: "runtime",
245
+ });
@@ -0,0 +1,74 @@
1
+ import { Predicate } from "effect";
2
+
3
+ import type * as Action from "./action.ts";
4
+
5
+ /**
6
+ * What a rule matches: an action instance, or a parallel group matched by its branch
7
+ * structure. Matching a parallel group is an explicit structural rule.
8
+ *
9
+ * @since @next
10
+ */
11
+ export type Pattern = Action.Any | Action.Parallel;
12
+
13
+ /** @since @next */
14
+ export type Rule<A extends Action.Any = Action.Any> = {
15
+ readonly _tag: "Rule";
16
+ readonly id: string;
17
+ readonly match: ReadonlyArray<Pattern>;
18
+ /** Steps that take the place of the match. An empty replacement cancels it. */
19
+ readonly replacement: ReadonlyArray<Action.Step<A>>;
20
+ };
21
+
22
+ /**
23
+ * Any rule.
24
+ *
25
+ * @since @next
26
+ */
27
+ export type Any = Rule<any>;
28
+
29
+ /**
30
+ * The action instances a rule can contribute to a plan.
31
+ *
32
+ * @since @next
33
+ */
34
+ export type ActionsOf<R> = R extends Rule<infer A> ? A : never;
35
+
36
+ /**
37
+ * Declares a replacement. Cancellation, composition, and supersession all use it.
38
+ *
39
+ * The author asserts that the replacement is equivalent to the matched occurrences.
40
+ * deltafold checks the rule's structure and where it applies, but it cannot prove the
41
+ * equivalence.
42
+ *
43
+ * Ordinary rules match consecutive occurrences inside one sequential branch, including
44
+ * across migration boundaries of a route. They never match across parallel branches.
45
+ *
46
+ * @example
47
+ * ```ts
48
+ * const cancelRoundTrip = Rule.replace("cancel-timeout-round-trip", {
49
+ * match: [renameTimeout, restoreTimeout],
50
+ * replacement: [],
51
+ * });
52
+ * const combineRenames = Rule.replace("combine-renames", {
53
+ * match: [renameAtoB, renameBtoC],
54
+ * replacement: [renameAtoC],
55
+ * });
56
+ * ```
57
+ *
58
+ * @since @next
59
+ */
60
+ export const replace = <A extends Action.Any = never>(
61
+ id: string,
62
+ options: {
63
+ readonly match: ReadonlyArray<Pattern>;
64
+ readonly replacement: ReadonlyArray<Action.Step<A>>;
65
+ },
66
+ ): Rule<A> => ({
67
+ _tag: "Rule",
68
+ id,
69
+ match: options.match,
70
+ replacement: options.replacement,
71
+ });
72
+
73
+ /** @since @next */
74
+ export const isRule = (value: unknown): value is Any => Predicate.isTagged(value, "Rule");
@@ -0,0 +1,79 @@
1
+ import { Predicate } from "effect";
2
+
3
+ import type * as Action from "./action.ts";
4
+ import type * as Change from "./change.ts";
5
+ import type * as Migration from "./migration.ts";
6
+ import type { Version } from "./version.ts";
7
+
8
+ /** @since @next */
9
+ export type Shortcut<A extends Action.Any = Action.Any, C extends Change.Any = Change.Any> = {
10
+ readonly _tag: "Shortcut";
11
+ readonly id: string;
12
+ readonly from: Version;
13
+ readonly to: Version;
14
+ /** The canonical route this shortcut replaces, in order. */
15
+ readonly replaces: ReadonlyArray<Migration.Any>;
16
+ /** The migrations that run instead, in order. */
17
+ readonly migrations: ReadonlyArray<Migration.Migration<A, C>>;
18
+ /** Author-declared cost, used only by the `lowest-cost` route policy. */
19
+ readonly cost: number | undefined;
20
+ };
21
+
22
+ /**
23
+ * Any shortcut.
24
+ *
25
+ * @since @next
26
+ */
27
+ export type Any = Shortcut<any>;
28
+
29
+ /**
30
+ * The action instances a shortcut can contribute to a plan.
31
+ *
32
+ * @since @next
33
+ */
34
+ export type ActionsOf<S> = S extends Shortcut<infer A> ? A : never;
35
+
36
+ /**
37
+ * The changes addressed by a shortcut's migrations.
38
+ *
39
+ * @since @next
40
+ */
41
+ export type ChangesOf<S> = S extends Shortcut<any, infer C> ? C : never;
42
+
43
+ /**
44
+ * Declares a shortcut. The author asserts that its migrations are equivalent to the
45
+ * canonical route it replaces; deltafold does not prove it.
46
+ *
47
+ * @example
48
+ * ```ts
49
+ * const fastUpgrade = Shortcut.make("fast-upgrade", {
50
+ * from: v201,
51
+ * to: v208,
52
+ * replaces: [migrate202, migrate203, migrate204],
53
+ * migrations: [migrateDirectlyTo208],
54
+ * });
55
+ * ```
56
+ *
57
+ * @since @next
58
+ */
59
+ export const make = <A extends Action.Any, C extends Change.Any = never>(
60
+ id: string,
61
+ options: {
62
+ readonly from: Version;
63
+ readonly to: Version;
64
+ readonly replaces: ReadonlyArray<Migration.Any>;
65
+ readonly migrations: ReadonlyArray<Migration.Migration<A, C>>;
66
+ readonly cost?: number;
67
+ },
68
+ ): Shortcut<A, C> => ({
69
+ _tag: "Shortcut",
70
+ id,
71
+ from: options.from,
72
+ to: options.to,
73
+ replaces: options.replaces,
74
+ migrations: options.migrations,
75
+ cost: options.cost,
76
+ });
77
+
78
+ /** @since @next */
79
+ export const isShortcut = (value: unknown): value is Any => Predicate.isTagged(value, "Shortcut");
@@ -0,0 +1,28 @@
1
+ import dedentText from "dedent";
2
+
3
+ const placeholder = "\u0000";
4
+
5
+ /**
6
+ * Removes the common indentation of a tagged template and its surrounding whitespace.
7
+ *
8
+ * Returns one literal string per original literal, so interpolated values stay at their
9
+ * positions and are never stringified or re-indented.
10
+ */
11
+ export const dedent = (strings: ReadonlyArray<string>): ReadonlyArray<string> =>
12
+ dedentText(strings.join(placeholder)).split(placeholder);
13
+
14
+ /** Scalar values that interpolate as text. */
15
+ export type Scalar = string | number | boolean | bigint;
16
+
17
+ export const isScalar = (value: unknown): value is Scalar =>
18
+ typeof value === "string" ||
19
+ typeof value === "number" ||
20
+ typeof value === "boolean" ||
21
+ typeof value === "bigint";
22
+
23
+ export const describeValue = (value: unknown): string => {
24
+ if (value === null) return "null";
25
+ if (Array.isArray(value)) return "an array";
26
+
27
+ return typeof value === "object" ? "an object" : typeof value;
28
+ };
@@ -0,0 +1,78 @@
1
+ import { Predicate } from "effect";
2
+
3
+ import type * as Change from "./change.ts";
4
+
5
+ /** @since @next */
6
+ export type Version<C extends Change.Any = Change.Any> = {
7
+ readonly _tag: "Version";
8
+ readonly id: string;
9
+ /**
10
+ * The release this version descends from. Absent for a root such as `0.0.0`. Only
11
+ * this field sets ancestry: several versions can share a predecessor, and declaration
12
+ * order and semver order have no effect.
13
+ */
14
+ readonly previous: Version | undefined;
15
+ /** The changes that shipped in this release. */
16
+ readonly changes: ReadonlyArray<C>;
17
+ };
18
+
19
+ /** @since @next */
20
+ export type Options<C extends Change.Any = Change.Any> = {
21
+ readonly previous?: Version;
22
+ readonly changes: ReadonlyArray<C>;
23
+ };
24
+
25
+ /**
26
+ * Declares a version.
27
+ *
28
+ * @example
29
+ * ```ts
30
+ * const v0 = Version.make("0.0.0", { changes: [] });
31
+ * const v100 = Version.make("1.0.0", { previous: v0, changes: [timeoutRenamed] });
32
+ * ```
33
+ *
34
+ * @since @next
35
+ */
36
+ export const make = <C extends Change.Any = never>(
37
+ id: string,
38
+ options: Options<C>,
39
+ ): Version<C> => ({
40
+ _tag: "Version",
41
+ id,
42
+ previous: options.previous,
43
+ changes: options.changes,
44
+ });
45
+
46
+ /** @since @next */
47
+ export const isVersion = (value: unknown): value is Version => Predicate.isTagged(value, "Version");
48
+
49
+ /**
50
+ * Release metadata attached to a version by release tooling. It does not modify the
51
+ * version registered in history.
52
+ *
53
+ * @since @next
54
+ */
55
+ export type Release<M> = {
56
+ readonly _tag: "Release";
57
+ readonly version: Version;
58
+ readonly metadata: M;
59
+ };
60
+
61
+ /**
62
+ * Annotates a version with release metadata.
63
+ *
64
+ * @example
65
+ * ```ts
66
+ * export const release200 = Version.withMetadata(v200, {
67
+ * releasedAt: "2026-11-06T12:00:00Z",
68
+ * commit: "abc123",
69
+ * });
70
+ * ```
71
+ *
72
+ * @since @next
73
+ */
74
+ export const withMetadata = <const M>(version: Version, metadata: M): Release<M> => ({
75
+ _tag: "Release",
76
+ version,
77
+ metadata,
78
+ });
package/src/index.ts CHANGED
@@ -1,11 +1,22 @@
1
- /**
2
- * deltafold models version history, resolves migration instructions between versions,
3
- * and generates changelogs.
4
- *
5
- * The public API is not implemented yet.
6
- *
7
- * @packageDocumentation
8
- */
9
-
10
- // oxlint-disable-next-line unicorn/require-module-specifiers -- Remove with the first public export.
11
- export {};
1
+ /** @since @next */
2
+ export * as Action from "./foundation/action.ts";
3
+ /** @since @next */
4
+ export * as Change from "./foundation/change.ts";
5
+ /** @since @next */
6
+ export * as Executor from "./features/execution/executor.ts";
7
+ /** @since @next */
8
+ export * as Handler from "./features/execution/handler.ts";
9
+ /** @since @next */
10
+ export * as History from "./features/planning/history.ts";
11
+ /** @since @next */
12
+ export * as Migration from "./foundation/migration.ts";
13
+ /** @since @next */
14
+ export * as Package from "./features/package.ts";
15
+ /** @since @next */
16
+ export * as Plan from "./foundation/plan.ts";
17
+ /** @since @next */
18
+ export * as Rule from "./foundation/rule.ts";
19
+ /** @since @next */
20
+ export * as Shortcut from "./foundation/shortcut.ts";
21
+ /** @since @next */
22
+ export * as Version from "./foundation/version.ts";
@@ -0,0 +1,12 @@
1
+ import { toHtml } from "hast-util-to-html";
2
+ import { toHast } from "mdast-util-to-hast";
3
+
4
+ import type { Document } from "../features/documents/document.ts";
5
+ import { toMdast } from "./mdast.ts";
6
+
7
+ /**
8
+ * Renders a document as an HTML fragment. Throws `DocumentError` for unsupported structure.
9
+ *
10
+ * @since @next
11
+ */
12
+ export const render = (document: Document): string => toHtml(toHast(toMdast(document)));
@@ -0,0 +1,12 @@
1
+ import { toMarkdown } from "mdast-util-to-markdown";
2
+
3
+ import type { Document } from "../features/documents/document.ts";
4
+ import { toMdast } from "./mdast.ts";
5
+
6
+ /**
7
+ * Renders a document as Markdown. Throws `DocumentError` for unsupported structure.
8
+ *
9
+ * @since @next
10
+ */
11
+ export const render = (document: Document): string =>
12
+ toMarkdown(toMdast(document), { bullet: "-", emphasis: "_", strong: "*" });
@@ -0,0 +1,120 @@
1
+ import type * as Mdast from "mdast";
2
+ import { normalizeUri, sanitizeUri } from "micromark-util-sanitize-uri";
3
+
4
+ import {
5
+ DocumentError,
6
+ type Block,
7
+ type Document,
8
+ type Inline,
9
+ } from "../features/documents/document.ts";
10
+
11
+ /** Link schemes kept in rendered output. Relative URLs are always kept. */
12
+ const safeSchemes = /^(https?|mailto)$/i;
13
+
14
+ /**
15
+ * Keeps a URL whose scheme is allowed, and replaces any other URL with an empty one.
16
+ * `sanitizeUri` also HTML-escapes its result, which the serializers would escape again,
17
+ * so only its scheme check is used here.
18
+ */
19
+ const safeUrl = (url: string) => (sanitizeUri(url, safeSchemes) === "" ? "" : normalizeUri(url));
20
+
21
+ const maximumLevel = 6;
22
+
23
+ const isDepth = (level: number): level is Mdast.Heading["depth"] =>
24
+ Number.isInteger(level) && level >= 1 && level <= maximumLevel;
25
+
26
+ const lowerInline = (value: Inline): Mdast.PhrasingContent => {
27
+ switch (value._tag) {
28
+ case "Text":
29
+ return { type: "text", value: value.value };
30
+ case "Code":
31
+ return { type: "inlineCode", value: value.value };
32
+ case "Link":
33
+ return {
34
+ type: "link",
35
+ url: safeUrl(value.url),
36
+ children: value.children.map(lowerInline),
37
+ };
38
+ case "Strong":
39
+ return { type: "strong", children: value.children.map(lowerInline) };
40
+ }
41
+
42
+ return { type: "emphasis", children: value.children.map(lowerInline) };
43
+ };
44
+
45
+ type Scope = { readonly ids: Set<string>; readonly label: string };
46
+
47
+ const lowerBlocks = (
48
+ blocks: ReadonlyArray<Block>,
49
+ depth: number,
50
+ scope: Scope,
51
+ ): Array<Mdast.BlockContent> =>
52
+ blocks.flatMap((block): Array<Mdast.BlockContent> => {
53
+ switch (block._tag) {
54
+ case "Paragraph":
55
+ return [{ type: "paragraph", children: block.children.map(lowerInline) }];
56
+ case "CodeBlock":
57
+ return [{ type: "code", value: block.value, lang: block.lang ?? null }];
58
+ case "List":
59
+ return [
60
+ {
61
+ type: "list",
62
+ ordered: block.ordered,
63
+ spread: false,
64
+ children: block.items.map((item) => ({
65
+ type: "listItem",
66
+ spread: false,
67
+ children: lowerBlocks(item, depth, scope),
68
+ })),
69
+ },
70
+ ];
71
+ }
72
+
73
+ if (scope.ids.has(block.id)) {
74
+ throw new DocumentError({
75
+ reason: "duplicate-section",
76
+ message: `Section "${block.id}" appears more than once in ${scope.label}.`,
77
+ });
78
+ }
79
+ scope.ids.add(block.id);
80
+ const inner =
81
+ block.release === undefined
82
+ ? scope
83
+ : { ids: new Set<string>(), label: `release "${block.release.id}"` };
84
+
85
+ if (block.title === undefined) {
86
+ return [
87
+ ...lowerBlocks(block.before, depth, inner),
88
+ ...lowerBlocks(block.after, depth, inner),
89
+ ...lowerBlocks(block.children, depth, inner),
90
+ ];
91
+ }
92
+
93
+ const level = block.title.level ?? depth;
94
+ if (!isDepth(level)) {
95
+ throw new DocumentError({
96
+ reason: "heading-level",
97
+ message: `Section "${block.id}" needs heading level ${level}, but levels range from 1 to ${maximumLevel}.`,
98
+ });
99
+ }
100
+
101
+ return [
102
+ ...lowerBlocks(block.before, level + 1, inner),
103
+ { type: "heading", depth: level, children: block.title.children.map(lowerInline) },
104
+ ...lowerBlocks(block.after, level + 1, inner),
105
+ ...lowerBlocks(block.children, level + 1, inner),
106
+ ];
107
+ });
108
+
109
+ /**
110
+ * Lowers a document to an mdast root. Untitled sections contribute only their content,
111
+ * and titled sections get the next heading level unless their title sets one. Link URLs
112
+ * with a scheme other than http, https, or mailto become empty.
113
+ *
114
+ * Throws `DocumentError` when a section identifier repeats within the document or within
115
+ * one release, or when a heading level falls outside 1 to 6.
116
+ */
117
+ export const toMdast = (document: Document): Mdast.Root => ({
118
+ type: "root",
119
+ children: lowerBlocks(document.children, 1, { ids: new Set(), label: "the document" }),
120
+ });
package/src/types.ts ADDED
@@ -0,0 +1,2 @@
1
+ /** The union of an object type's property values. */
2
+ export type ValueOf<T> = T[keyof T];