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.
- package/README.md +274 -4
- package/dist/changelog.d.ts +116 -0
- package/dist/changelog.d.ts.map +1 -0
- package/dist/changelog.js +304 -0
- package/dist/changelog.js.map +1 -0
- package/dist/document-BZcZo9nr.js +171 -0
- package/dist/document-BZcZo9nr.js.map +1 -0
- package/dist/document-DWHsgywm.d.ts +257 -0
- package/dist/document-DWHsgywm.d.ts.map +1 -0
- package/dist/html.d.ts +8 -0
- package/dist/html.d.ts.map +1 -0
- package/dist/html.js +13 -0
- package/dist/html.js.map +1 -0
- package/dist/index.d.ts +378 -1
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +2058 -0
- package/dist/index.js.map +1 -0
- package/dist/markdown.d.ts +8 -0
- package/dist/markdown.d.ts.map +1 -0
- package/dist/markdown.js +16 -0
- package/dist/markdown.js.map +1 -0
- package/dist/mdast-DiRsYwPU.js +108 -0
- package/dist/mdast-DiRsYwPU.js.map +1 -0
- package/dist/package-BfBYnaCz.d.ts +1125 -0
- package/dist/package-BfBYnaCz.d.ts.map +1 -0
- package/dist/rolldown-runtime-D8jQpDG7.js +12 -0
- package/package.json +13 -1
- package/src/features/documents/changelog.ts +450 -0
- package/src/features/documents/document.ts +357 -0
- package/src/features/documents/index.ts +4 -0
- package/src/features/documents/public-document.ts +31 -0
- package/src/features/documents/sections.ts +44 -0
- package/src/features/execution/executor.ts +826 -0
- package/src/features/execution/handler.ts +257 -0
- package/src/features/execution/settlement.ts +49 -0
- package/src/features/package.ts +32 -0
- package/src/features/planning/guide.ts +56 -0
- package/src/features/planning/history.ts +174 -0
- package/src/features/planning/identifiers.ts +43 -0
- package/src/features/planning/resolve-error.ts +201 -0
- package/src/features/planning/resolve.ts +724 -0
- package/src/features/planning/rewrite.ts +331 -0
- package/src/features/planning/validate.ts +388 -0
- package/src/foundation/action.ts +188 -0
- package/src/foundation/change.ts +147 -0
- package/src/foundation/instruction.ts +110 -0
- package/src/foundation/migration.ts +236 -0
- package/src/foundation/plan.ts +245 -0
- package/src/foundation/rule.ts +74 -0
- package/src/foundation/shortcut.ts +79 -0
- package/src/foundation/template.ts +28 -0
- package/src/foundation/version.ts +78 -0
- package/src/index.ts +22 -11
- package/src/renderers/html.ts +12 -0
- package/src/renderers/markdown.ts +12 -0
- package/src/renderers/mdast.ts +120 -0
- 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
|
-
*
|
|
3
|
-
|
|
4
|
-
*
|
|
5
|
-
|
|
6
|
-
*
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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