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,147 @@
1
+ import { Predicate } from "effect";
2
+
3
+ import { describeValue, dedent, isScalar, type Scalar } from "./template.ts";
4
+
5
+ /**
6
+ * The metadata of a change whose shape is not known statically.
7
+ *
8
+ * @since @next
9
+ */
10
+ export type Metadata = { readonly [field: string]: unknown };
11
+
12
+ /** @since @next */
13
+ export type NoMetadata = { readonly [field: string]: undefined };
14
+
15
+ /**
16
+ * A human-readable record of one logical change. A change can exist before it is
17
+ * assigned to a release, and it does not need an executable migration.
18
+ *
19
+ * deltafold does not interpret `metadata`. Consumers choose its fields, such as a
20
+ * classification or a breaking flag, and what they mean.
21
+ *
22
+ * @since @next
23
+ */
24
+ export type Change<M extends object = Metadata> = {
25
+ readonly _tag: "Change";
26
+ /** Stable identifier. Editing the description does not change identity. */
27
+ readonly id: string;
28
+ readonly metadata: M;
29
+ readonly description: string;
30
+ /** Historical relationship only: it does not cancel actions or create routes. */
31
+ readonly reverts: ReadonlyArray<Any>;
32
+ /** The change that an adapted backport was derived from. */
33
+ readonly backportOf: Any | undefined;
34
+ };
35
+
36
+ /**
37
+ * A change whose metadata type is not known statically. Its metadata is an object, so
38
+ * reading a field requires narrowing first.
39
+ *
40
+ * @since @next
41
+ */
42
+ export type Any = Change<object>;
43
+
44
+ /**
45
+ * Relationships to other changes.
46
+ *
47
+ * @since @next
48
+ */
49
+ export type Relations = {
50
+ readonly reverts?: ReadonlyArray<Any>;
51
+ readonly backportOf?: Any;
52
+ };
53
+
54
+ /**
55
+ * Takes the description as a tagged template and returns the change.
56
+ *
57
+ * @since @next
58
+ */
59
+ export type Describe<M extends object> = (
60
+ strings: TemplateStringsArray,
61
+ ...values: ReadonlyArray<Scalar>
62
+ ) => Change<M>;
63
+
64
+ const describe =
65
+ <M extends object>(id: string, metadata: M, relations: Relations): Describe<M> =>
66
+ (strings, ...values) => {
67
+ const literals = dedent(strings);
68
+ let description = "";
69
+ for (const [index, literal] of literals.entries()) {
70
+ description += literal;
71
+ if (index >= values.length) continue;
72
+
73
+ const value: unknown = values[index];
74
+ if (!isScalar(value)) {
75
+ throw new TypeError(`Change "${id}": cannot interpolate ${describeValue(value)}.`);
76
+ }
77
+ description += String(value);
78
+ }
79
+
80
+ return {
81
+ _tag: "Change",
82
+ id,
83
+ metadata,
84
+ description,
85
+ reverts: relations.reverts ?? [],
86
+ backportOf: relations.backportOf,
87
+ };
88
+ };
89
+
90
+ /**
91
+ * Declares a change. The tagged template is its description. Metadata is optional, and
92
+ * its type is inferred from the value, literals included.
93
+ *
94
+ * @example
95
+ * ```ts
96
+ * const retriesAdded = Change.make("2026-11-20.add-retries")`
97
+ * Add a retry limit option.
98
+ * `;
99
+ * const timeoutRenamed = Change.make("2026-11-06.rename-timeout", { breaking: true })`
100
+ * Rename the timeout configuration option to requestTimeout.
101
+ * `;
102
+ * ```
103
+ *
104
+ * @since @next
105
+ */
106
+ export function make(id: string): Describe<NoMetadata>;
107
+ export function make<const M extends object>(
108
+ id: string,
109
+ metadata: M,
110
+ relations?: Relations,
111
+ ): Describe<M>;
112
+ export function make(id: string, metadata: object = {}, relations: Relations = {}) {
113
+ return describe(id, metadata, relations);
114
+ }
115
+
116
+ /**
117
+ * Makes changes that share one metadata shape.
118
+ *
119
+ * @since @next
120
+ */
121
+ export type Definition<M extends object> = {
122
+ readonly make: (id: string, metadata: M, relations?: Relations) => Describe<M>;
123
+ };
124
+
125
+ /**
126
+ * Defines a reusable change factory whose metadata must have the type `M`.
127
+ *
128
+ * @example
129
+ * ```ts
130
+ * const ConfigChange = Change.define<{
131
+ * readonly kind: "added" | "changed" | "fixed";
132
+ * readonly breaking: boolean;
133
+ * }>();
134
+ * const timeoutRenamed = ConfigChange.make("2026-11-06.rename-timeout", {
135
+ * kind: "changed",
136
+ * breaking: true,
137
+ * })`
138
+ * Rename the timeout configuration option to requestTimeout.
139
+ * `;
140
+ * ```
141
+ *
142
+ * @since @next
143
+ */
144
+ export const define = <M extends object>(): Definition<M> => ({ make: make<M> });
145
+
146
+ /** @since @next */
147
+ export const isChange = (value: unknown): value is Change => Predicate.isTagged(value, "Change");
@@ -0,0 +1,110 @@
1
+ import { Predicate } from "effect";
2
+
3
+ import type * as Action from "./action.ts";
4
+ import { isAction, isRef } from "./action.ts";
5
+ import { describeValue, dedent, isScalar, type Scalar } from "./template.ts";
6
+
7
+ /**
8
+ * Literal prose.
9
+ *
10
+ * @since @next
11
+ */
12
+ export type Text = {
13
+ readonly _tag: "Text";
14
+ readonly text: string;
15
+ };
16
+
17
+ /**
18
+ * Prose content: text and action mentions.
19
+ *
20
+ * @since @next
21
+ */
22
+ export type Prose = ReadonlyArray<Text | Action.Ref>;
23
+
24
+ /**
25
+ * Values accepted inside prose templates.
26
+ *
27
+ * @since @next
28
+ */
29
+ export type ProseValue = Scalar | Action.Ref;
30
+
31
+ /**
32
+ * Prose associated with exactly one action occurrence. The block declares that
33
+ * occurrence; when optimization removes the action, the block leaves the resolved guide
34
+ * with it.
35
+ *
36
+ * @since @next
37
+ */
38
+ export type Instruction<A extends Action.Any = Action.Any> = {
39
+ readonly _tag: "Instruction";
40
+ readonly action: A;
41
+ readonly content: Prose;
42
+ };
43
+
44
+ export const isInstruction = (value: unknown): value is Instruction =>
45
+ Predicate.isTagged(value, "Instruction");
46
+
47
+ /** Builds prose from a tagged template. Throws on values that are not text or mentions. */
48
+ export const prose = (
49
+ strings: ReadonlyArray<string>,
50
+ values: ReadonlyArray<unknown>,
51
+ context: string,
52
+ ): Prose => {
53
+ const literals = dedent(strings);
54
+ const content: Array<Text | Action.Ref> = [];
55
+
56
+ const pushText = (text: string) => {
57
+ if (text === "") return;
58
+
59
+ const last = content.at(-1);
60
+ if (last?._tag === "Text") {
61
+ content[content.length - 1] = { _tag: "Text", text: last.text + text };
62
+
63
+ return;
64
+ }
65
+ content.push({ _tag: "Text", text });
66
+ };
67
+
68
+ for (const [index, literal] of literals.entries()) {
69
+ pushText(literal);
70
+ if (index >= values.length) continue;
71
+
72
+ const value = values[index];
73
+ if (isScalar(value)) {
74
+ pushText(String(value));
75
+ continue;
76
+ }
77
+ if (isRef(value)) {
78
+ content.push(value);
79
+ continue;
80
+ }
81
+ if (isAction(value)) {
82
+ throw new TypeError(
83
+ `${context}: action "${value.id}" cannot be interpolated here because it would declare another occurrence. Use Action.ref(action) to mention it.`,
84
+ );
85
+ }
86
+ throw new TypeError(`${context}: cannot interpolate ${describeValue(value)}.`);
87
+ }
88
+
89
+ return content;
90
+ };
91
+
92
+ /**
93
+ * Associates prose with one action occurrence.
94
+ *
95
+ * @example
96
+ * ```ts
97
+ * Migration.instruction(renameTimeout)`
98
+ * Rename the timeout option, keeping its existing value.
99
+ * `;
100
+ * ```
101
+ *
102
+ * @since @next
103
+ */
104
+ export const instruction =
105
+ <A extends Action.Any>(action: A) =>
106
+ (strings: TemplateStringsArray, ...values: ReadonlyArray<ProseValue>): Instruction<A> => ({
107
+ _tag: "Instruction",
108
+ action,
109
+ content: prose(strings, values, `Instruction for "${action.id}"`),
110
+ });
@@ -0,0 +1,236 @@
1
+ import { Predicate } from "effect";
2
+
3
+ import type * as Action from "./action.ts";
4
+ import { isAction, isParallel, isRef, isSequence } from "./action.ts";
5
+ import type * as Change from "./change.ts";
6
+ import { instruction, isInstruction, type Text } from "./instruction.ts";
7
+ import { describeValue, dedent, isScalar, type Scalar } from "./template.ts";
8
+ import type { Version } from "./version.ts";
9
+
10
+ export { instruction };
11
+ export type { Instruction, Prose, ProseValue, Text } from "./instruction.ts";
12
+
13
+ /**
14
+ * Prose, mentions, and occurrence-declaring steps in template order.
15
+ *
16
+ * @since @next
17
+ */
18
+ export type Content<A extends Action.Any = Action.Any> = ReadonlyArray<
19
+ Text | Action.Ref | Action.Step<A>
20
+ >;
21
+
22
+ /**
23
+ * Values accepted in migration templates.
24
+ *
25
+ * @since @next
26
+ */
27
+ export type Interpolation = Scalar | Action.Ref | Action.Step;
28
+
29
+ /** @since @next */
30
+ export type Migration<A extends Action.Any = Action.Any, C extends Change.Any = Change.Any> = {
31
+ readonly _tag: "Migration";
32
+ readonly id: string;
33
+ readonly from: Version;
34
+ readonly to: Version;
35
+ /** The logical changes this transition handles. */
36
+ readonly addresses: ReadonlyArray<C>;
37
+ /** Whether this is an explicit zero-work transition. */
38
+ readonly noop: boolean;
39
+ /** Author-declared cost, used only by the `lowest-cost` route policy. */
40
+ readonly cost: number | undefined;
41
+ readonly content: Content;
42
+ /** The reverse transition, from `to` back to `from`. Absent means no reverse edge. */
43
+ readonly revert: Content | undefined;
44
+ /** Type-level record of the action instances in `content` and `revert`. */
45
+ readonly "~actions"?: A;
46
+ };
47
+
48
+ /**
49
+ * Any migration.
50
+ *
51
+ * @since @next
52
+ */
53
+ export type Any = Migration<any>;
54
+
55
+ /**
56
+ * The action instances a migration can contribute to a plan.
57
+ *
58
+ * @since @next
59
+ */
60
+ export type ActionsOf<M> = M extends Migration<infer A> ? A : never;
61
+
62
+ /**
63
+ * The changes a migration addresses.
64
+ *
65
+ * @since @next
66
+ */
67
+ export type ChangesOf<M> = M extends Migration<any, infer C> ? C : never;
68
+
69
+ /** @since @next */
70
+ export type Options<C extends Change.Any = Change.Any> = {
71
+ readonly from: Version;
72
+ readonly to: Version;
73
+ readonly addresses?: ReadonlyArray<C>;
74
+ readonly cost?: number;
75
+ };
76
+
77
+ /** @since @next */
78
+ export const isMigration = (value: unknown): value is Any => Predicate.isTagged(value, "Migration");
79
+
80
+ const isStep = (value: unknown): value is Action.Step =>
81
+ isAction(value) || isInstruction(value) || isSequence(value) || isParallel(value);
82
+
83
+ const validateStep = (step: Action.Step, context: string): void => {
84
+ if (isSequence(step)) {
85
+ for (const child of step.children) checkStep(child, context);
86
+
87
+ return;
88
+ }
89
+ if (isParallel(step)) {
90
+ for (const branch of step.branches) checkStep(branch, context);
91
+ }
92
+ };
93
+
94
+ const checkStep = (value: unknown, context: string): void => {
95
+ if (!isStep(value)) {
96
+ throw new TypeError(
97
+ `${context}: a group can only contain actions, instructions, and groups.`,
98
+ );
99
+ }
100
+ validateStep(value, context);
101
+ };
102
+
103
+ /** Builds content from a tagged template. */
104
+ const content = (
105
+ strings: ReadonlyArray<string>,
106
+ values: ReadonlyArray<unknown>,
107
+ context: string,
108
+ ): Content => {
109
+ const literals = dedent(strings);
110
+ const result: Array<Text | Action.Ref | Action.Step> = [];
111
+
112
+ const pushText = (text: string) => {
113
+ if (text === "") return;
114
+
115
+ const last = result.at(-1);
116
+ if (last?._tag === "Text") {
117
+ result[result.length - 1] = { _tag: "Text", text: last.text + text };
118
+
119
+ return;
120
+ }
121
+ result.push({ _tag: "Text", text });
122
+ };
123
+
124
+ for (const [index, literal] of literals.entries()) {
125
+ pushText(literal);
126
+ if (index >= values.length) continue;
127
+
128
+ const value = values[index];
129
+ if (isScalar(value)) {
130
+ pushText(String(value));
131
+ continue;
132
+ }
133
+ if (isRef(value)) {
134
+ result.push(value);
135
+ continue;
136
+ }
137
+ if (isStep(value)) {
138
+ validateStep(value, context);
139
+ result.push(value);
140
+ continue;
141
+ }
142
+ throw new TypeError(`${context}: cannot interpolate ${describeValue(value)}.`);
143
+ }
144
+
145
+ return result;
146
+ };
147
+
148
+ /**
149
+ * Declares a migration between exact versions. Interpolated actions, instruction blocks,
150
+ * and groups declare occurrences; `Action.ref` only mentions an action.
151
+ *
152
+ * @example
153
+ * ```ts
154
+ * const migrate152To200 = Migration.make("1.5.2-to-2.0.0", {
155
+ * from: v152,
156
+ * to: v200,
157
+ * addresses: [timeoutRenamed],
158
+ * })`
159
+ * Update the configuration for export A:
160
+ *
161
+ * ${renameExportA}
162
+ * `;
163
+ * ```
164
+ *
165
+ * @since @next
166
+ */
167
+ export const make =
168
+ <C extends Change.Any = never>(id: string, options: Options<C>) =>
169
+ <const V extends ReadonlyArray<Interpolation>>(
170
+ strings: TemplateStringsArray,
171
+ ...values: V
172
+ ): Migration<Action.ActionsOf<V[number]>, C> => ({
173
+ _tag: "Migration",
174
+ id,
175
+ from: options.from,
176
+ to: options.to,
177
+ addresses: options.addresses ?? [],
178
+ noop: false,
179
+ cost: options.cost,
180
+ content: content(strings, values, `Migration "${id}"`),
181
+ revert: undefined,
182
+ });
183
+
184
+ /** @since @next */
185
+ export type NoopOptions<C extends Change.Any = Change.Any> = Options<C> & {
186
+ /** Also declares the reverse transition as zero-work. */
187
+ readonly reversible?: boolean;
188
+ };
189
+
190
+ /**
191
+ * Declares a supported transition that requires no consumer work. It is a directed edge
192
+ * like any migration. Do not use it to hide missing support for changes that need
193
+ * instructions.
194
+ *
195
+ * @since @next
196
+ */
197
+ export const noop = <C extends Change.Any = never>(
198
+ id: string,
199
+ options: NoopOptions<C>,
200
+ ): Migration<never, C> => ({
201
+ _tag: "Migration",
202
+ id,
203
+ from: options.from,
204
+ to: options.to,
205
+ addresses: options.addresses ?? [],
206
+ noop: true,
207
+ cost: options.cost,
208
+ content: [],
209
+ revert: options.reversible === true ? [] : undefined,
210
+ });
211
+
212
+ /**
213
+ * Adds a reverse transition. Register the returned migration in place of the original:
214
+ * both share the same identifier. On a `Migration.noop`, the reverse is real work: only
215
+ * the forward side stays zero-work.
216
+ *
217
+ * @example
218
+ * ```ts
219
+ * const reversible = Migration.withRevert(migrate152To200)`
220
+ * Restore the previous configuration:
221
+ *
222
+ * ${restoreTimeout}
223
+ * `;
224
+ * ```
225
+ *
226
+ * @since @next
227
+ */
228
+ export const withRevert =
229
+ <A extends Action.Any, C extends Change.Any>(migration: Migration<A, C>) =>
230
+ <const V extends ReadonlyArray<Interpolation>>(
231
+ strings: TemplateStringsArray,
232
+ ...values: V
233
+ ): Migration<A | Action.ActionsOf<V[number]>, C> => ({
234
+ ...migration,
235
+ revert: content(strings, values, `Revert of migration "${migration.id}"`),
236
+ });