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,174 @@
1
+ import { Predicate, Result } from "effect";
2
+
3
+ import type * as Action from "../../foundation/action.ts";
4
+ import type * as Change from "../../foundation/change.ts";
5
+ import type * as Migration from "../../foundation/migration.ts";
6
+ import type { Plan } from "../../foundation/plan.ts";
7
+ import type * as Rule from "../../foundation/rule.ts";
8
+ import type * as Shortcut from "../../foundation/shortcut.ts";
9
+ import type { Version } from "../../foundation/version.ts";
10
+ import { InvalidHistory, type ResolveError, type UnknownVersion } from "./resolve-error.ts";
11
+ import {
12
+ destinations,
13
+ lookup as lookupVersion,
14
+ makeContext,
15
+ resolve as resolveRoute,
16
+ type Context,
17
+ type Destination,
18
+ type ResolveOptions,
19
+ type RoutePolicy,
20
+ } from "./resolve.ts";
21
+ import { validate as validateDeclarations, type Issue } from "./validate.ts";
22
+
23
+ export * from "./resolve-error.ts";
24
+ export type { Destination, Issue, ResolveOptions, RoutePolicy };
25
+
26
+ /** @since @next */
27
+ export type History<A extends Action.Any = Action.Any, C extends Change.Any = Change.Any> = {
28
+ readonly _tag: "History";
29
+ readonly versions: ReadonlyArray<Version>;
30
+ readonly migrations: ReadonlyArray<Migration.Any>;
31
+ readonly rules: ReadonlyArray<Rule.Any>;
32
+ readonly shortcuts: ReadonlyArray<Shortcut.Any>;
33
+ /** Type-level record of every action instance that a plan can contain. */
34
+ readonly "~actions"?: A;
35
+ /** Type-level record of every change that a plan's `changes` can contain. */
36
+ readonly "~changes"?: C;
37
+ };
38
+
39
+ /**
40
+ * Any history.
41
+ *
42
+ * @since @next
43
+ */
44
+ export type Any = History<any>;
45
+
46
+ /**
47
+ * Every action instance that a plan resolved from the history can contain.
48
+ *
49
+ * @since @next
50
+ */
51
+ export type ActionsOf<H> = H extends History<infer A> ? A : never;
52
+
53
+ /**
54
+ * Every change that a plan resolved from the history can list in `changes`.
55
+ *
56
+ * @since @next
57
+ */
58
+ export type ChangesOf<H> = H extends History<any, infer C> ? C : never;
59
+
60
+ /**
61
+ * Registers declarations. Migrations are registered independently of versions, so
62
+ * routes can be added later without changing published release definitions.
63
+ *
64
+ * `make` does not throw. Use `History.validate` to list declaration issues;
65
+ * resolution fails with `InvalidHistory` when there are any.
66
+ *
67
+ * @since @next
68
+ */
69
+ export const make = <
70
+ const M extends ReadonlyArray<Migration.Any>,
71
+ const R extends ReadonlyArray<Rule.Any> = [],
72
+ const S extends ReadonlyArray<Shortcut.Any> = [],
73
+ >(declarations: {
74
+ readonly versions: ReadonlyArray<Version>;
75
+ readonly migrations: M;
76
+ readonly rules?: R;
77
+ readonly shortcuts?: S;
78
+ }): History<
79
+ Migration.ActionsOf<M[number]> | Rule.ActionsOf<R[number]> | Shortcut.ActionsOf<S[number]>,
80
+ Migration.ChangesOf<M[number]> | Shortcut.ChangesOf<S[number]>
81
+ > => ({
82
+ _tag: "History",
83
+ versions: declarations.versions,
84
+ migrations: declarations.migrations,
85
+ rules: declarations.rules ?? [],
86
+ shortcuts: declarations.shortcuts ?? [],
87
+ });
88
+
89
+ /** @since @next */
90
+ export const isHistory = (value: unknown): value is Any => Predicate.isTagged(value, "History");
91
+
92
+ const contexts = new WeakMap<
93
+ Any,
94
+ { readonly issues: ReadonlyArray<Issue>; readonly context: Context }
95
+ >();
96
+
97
+ const prepare = (history: Any) => {
98
+ const cached = contexts.get(history);
99
+ if (cached !== undefined) return cached;
100
+
101
+ const prepared = { issues: validateDeclarations(history), context: makeContext(history) };
102
+ contexts.set(history, prepared);
103
+
104
+ return prepared;
105
+ };
106
+
107
+ /**
108
+ * Lists declaration issues in a deterministic order. An empty list means valid.
109
+ *
110
+ * @since @next
111
+ */
112
+ export const validate = (history: Any): ReadonlyArray<Issue> => prepare(history).issues;
113
+
114
+ const valid = (history: Any): Result.Result<Context, InvalidHistory> => {
115
+ const { issues, context } = prepare(history);
116
+
117
+ return issues.length === 0
118
+ ? Result.succeed(context)
119
+ : Result.fail(new InvalidHistory({ issues }));
120
+ };
121
+
122
+ /**
123
+ * Resolves an optimized plan between two versions. Planning needs no handlers or
124
+ * execution services, and it never reads or modifies consumer files.
125
+ *
126
+ * When several routes connect the versions, resolution fails with `AmbiguousRoute`
127
+ * unless the `route` option selects one or a route `policy` leaves exactly one.
128
+ *
129
+ * @example
130
+ * ```ts
131
+ * const result = History.resolve(history, { from: "1.5.3", to: "2.0.0" });
132
+ * if (Result.isSuccess(result)) console.log(result.success.route.id);
133
+ * ```
134
+ *
135
+ * @since @next
136
+ */
137
+ export const resolve = <A extends Action.Any, C extends Change.Any>(
138
+ history: History<A, C>,
139
+ options: ResolveOptions,
140
+ ): Result.Result<Plan<A, "static", C>, ResolveError> =>
141
+ // Every occurrence and change comes from the history's declarations, whose unions are
142
+ // `A` and `C`.
143
+ // oxlint-disable-next-line typescript/no-unsafe-type-assertion
144
+ Result.flatMap(valid(history), (context) => resolveRoute(context, options)) as Result.Result<
145
+ Plan<A, "static", C>,
146
+ ResolveError
147
+ >;
148
+
149
+ /**
150
+ * Destinations reachable by upgrade from a version, with their candidate routes.
151
+ *
152
+ * @since @next
153
+ */
154
+ export const upgrades = (
155
+ history: Any,
156
+ options: { readonly from: Version | string },
157
+ ): Result.Result<ReadonlyArray<Destination>, InvalidHistory | UnknownVersion> =>
158
+ reachableFrom(history, options.from, "upgrade");
159
+
160
+ /**
161
+ * Destinations reachable by downgrade from a version, with their candidate routes.
162
+ *
163
+ * @since @next
164
+ */
165
+ export const downgrades = (
166
+ history: Any,
167
+ options: { readonly from: Version | string },
168
+ ): Result.Result<ReadonlyArray<Destination>, InvalidHistory | UnknownVersion> =>
169
+ reachableFrom(history, options.from, "downgrade");
170
+
171
+ const reachableFrom = (history: Any, from: Version | string, kind: "upgrade" | "downgrade") =>
172
+ Result.flatMap(valid(history), (context) =>
173
+ Result.map(lookupVersion(context, from), (version) => destinations(context, version, kind)),
174
+ );
@@ -0,0 +1,43 @@
1
+ import type * as Action from "../../foundation/action.ts";
2
+ import type * as Migration from "../../foundation/migration.ts";
3
+ import type { Direction, Occurrence } from "../../foundation/plan.ts";
4
+ import type * as Rule from "../../foundation/rule.ts";
5
+
6
+ // Author identifiers may contain any character. Each format escapes its own separators,
7
+ // and the backslash itself, so distinct components never produce the same identifier.
8
+ const escape = (value: string, separators: RegExp) => value.replace(separators, "\\$&");
9
+
10
+ const occurrencePart = (id: string) => escape(id, /[\\/()+]/g);
11
+
12
+ const routePart = (id: string) => escape(id, /[\\>[\]]/g);
13
+
14
+ /** `<migration>/<action>` forward, `<migration>/revert/<action>` in reverse. */
15
+ export const declaredOccurrenceId = (
16
+ migration: Migration.Any,
17
+ direction: Direction,
18
+ action: Action.Any,
19
+ ): string =>
20
+ direction === "forward"
21
+ ? `${occurrencePart(migration.id)}/${occurrencePart(action.id)}`
22
+ : `${occurrencePart(migration.id)}/revert/${occurrencePart(action.id)}`;
23
+
24
+ /**
25
+ * `<rule>(<replaced>+<replaced>)/<action>`. Replaced identifiers are complete occurrence
26
+ * identifiers, so they nest without further escaping.
27
+ */
28
+ export const replacementOccurrenceId = (
29
+ rule: Rule.Any,
30
+ replaced: ReadonlyArray<Occurrence>,
31
+ action: Action.Any,
32
+ ): string =>
33
+ `${occurrencePart(rule.id)}(${replaced.map((occurrence) => occurrence.id).join("+")})/${occurrencePart(action.id)}`;
34
+
35
+ /** The first version of a route identifier. */
36
+ export const routeStart = (version: string): string => routePart(version);
37
+
38
+ /** A migration hop: `>` and the target version. */
39
+ export const routeHop = (to: string): string => `>${routePart(to)}`;
40
+
41
+ /** A shortcut hop: `>[shortcut]>` and the target version. */
42
+ export const routeShortcut = (shortcut: string, to: string): string =>
43
+ `>[${routePart(shortcut)}]>${routePart(to)}`;
@@ -0,0 +1,201 @@
1
+ import { Data } from "effect";
2
+
3
+ import type { RequestDirection } from "../../foundation/plan.ts";
4
+ import type { Issue } from "./validate.ts";
5
+
6
+ /**
7
+ * A candidate route, summarized for diagnostics and explicit selection.
8
+ *
9
+ * @since @next
10
+ */
11
+ export type RouteSummary = {
12
+ /** Pass this as the `route` option to select the route. */
13
+ readonly id: string;
14
+ readonly migrations: ReadonlyArray<string>;
15
+ readonly shortcuts: ReadonlyArray<string>;
16
+ /** Optimized action count, or `undefined` when the route failed to optimize. */
17
+ readonly actions: number | undefined;
18
+ readonly cost: number;
19
+ /** Why the route cannot be planned, if it cannot. */
20
+ readonly failure: string | undefined;
21
+ };
22
+
23
+ /**
24
+ * An ancestry hop with no declared route in the requested direction.
25
+ *
26
+ * @since @next
27
+ */
28
+ export type Blocker = {
29
+ readonly from: string;
30
+ readonly to: string;
31
+ readonly reason: string;
32
+ };
33
+
34
+ /**
35
+ * The history's declarations are invalid. Resolution needs a valid history.
36
+ *
37
+ * @since @next
38
+ */
39
+ export class InvalidHistory extends Data.TaggedError("InvalidHistory")<{
40
+ readonly issues: ReadonlyArray<Issue>;
41
+ }> {
42
+ override get message() {
43
+ return `The history has ${this.issues.length} declaration issue(s): ${this.issues
44
+ .map((issue) => issue.message)
45
+ .join(" ")}`;
46
+ }
47
+ }
48
+
49
+ /** @since @next */
50
+ export class UnknownVersion extends Data.TaggedError("UnknownVersion")<{
51
+ readonly version: string;
52
+ readonly known: ReadonlyArray<string>;
53
+ }> {
54
+ override get message() {
55
+ return `Version "${this.version}" is not registered in the history.`;
56
+ }
57
+ }
58
+
59
+ /**
60
+ * No declared route connects the versions. This never means that no work is needed:
61
+ * declare `Migration.noop` for a supported zero-work transition.
62
+ *
63
+ * @since @next
64
+ */
65
+ export class UnsupportedRoute extends Data.TaggedError("UnsupportedRoute")<{
66
+ readonly from: string;
67
+ readonly to: string;
68
+ readonly direction: RequestDirection;
69
+ /** Versions that are reachable from `from` in the requested direction. */
70
+ readonly reachable: ReadonlyArray<string>;
71
+ /** Reachable versions closest to `to` along release ancestry. Ties are all listed. */
72
+ readonly closest: ReadonlyArray<string>;
73
+ readonly blockers: ReadonlyArray<Blocker>;
74
+ }> {
75
+ override get message() {
76
+ const closest =
77
+ this.closest.length === 0 ? "" : ` Closest reachable: ${this.closest.join(", ")}.`;
78
+
79
+ return `No declared ${this.direction} route from "${this.from}" to "${this.to}".${closest}`;
80
+ }
81
+ }
82
+
83
+ /**
84
+ * Several routes connect the versions and no selection or policy chose one.
85
+ *
86
+ * @since @next
87
+ */
88
+ export class AmbiguousRoute extends Data.TaggedError("AmbiguousRoute")<{
89
+ readonly from: string;
90
+ readonly to: string;
91
+ readonly candidates: ReadonlyArray<RouteSummary>;
92
+ readonly policy: string | undefined;
93
+ }> {
94
+ override get message() {
95
+ const ids = this.candidates.map((candidate) => `"${candidate.id}"`).join(", ");
96
+ const reason =
97
+ this.policy === undefined ? "" : ` after applying the "${this.policy}" policy`;
98
+
99
+ return `${this.candidates.length} routes connect "${this.from}" and "${this.to}"${reason}: ${ids}. Select one with the \`route\` option, or choose a route policy.`;
100
+ }
101
+ }
102
+
103
+ /**
104
+ * The `route` option names no candidate route.
105
+ *
106
+ * @since @next
107
+ */
108
+ export class UnknownRoute extends Data.TaggedError("UnknownRoute")<{
109
+ readonly route: string;
110
+ readonly candidates: ReadonlyArray<RouteSummary>;
111
+ }> {
112
+ override get message() {
113
+ return `No candidate route has the identifier "${this.route}". Candidates: ${this.candidates
114
+ .map((candidate) => `"${candidate.id}"`)
115
+ .join(", ")}.`;
116
+ }
117
+ }
118
+
119
+ /**
120
+ * Rules rewrite a sequence back into itself.
121
+ *
122
+ * @since @next
123
+ */
124
+ export class RewriteCycle extends Data.TaggedError("RewriteCycle")<{
125
+ readonly route: string;
126
+ readonly rules: ReadonlyArray<string>;
127
+ readonly actions: string;
128
+ }> {
129
+ override get message() {
130
+ return `Rules ${this.rules.map((rule) => `"${rule}"`).join(", ")} rewrite a sequence back into itself on route "${this.route}".`;
131
+ }
132
+ }
133
+
134
+ /**
135
+ * Rules can produce different results depending on which applies first.
136
+ *
137
+ * @since @next
138
+ */
139
+ export class ConflictingRewrites extends Data.TaggedError("ConflictingRewrites")<{
140
+ readonly route: string;
141
+ readonly outcomes: ReadonlyArray<{
142
+ readonly actions: string;
143
+ readonly rules: ReadonlyArray<string>;
144
+ }>;
145
+ }> {
146
+ override get message() {
147
+ return `Rules produce ${this.outcomes.length} different results on route "${this.route}", depending on the order they apply in.`;
148
+ }
149
+ }
150
+
151
+ /**
152
+ * Optimization explored too many states or chained too many rule applications, for
153
+ * example because a rule keeps growing the sequence.
154
+ *
155
+ * @since @next
156
+ */
157
+ export class RewriteLimitExceeded extends Data.TaggedError("RewriteLimitExceeded")<{
158
+ readonly route: string;
159
+ readonly limit: "states" | "depth";
160
+ readonly value: number;
161
+ }> {
162
+ override get message() {
163
+ return this.limit === "states"
164
+ ? `Optimizing route "${this.route}" explored more than ${this.value} states.`
165
+ : `Optimizing route "${this.route}" chained more than ${this.value} rule applications.`;
166
+ }
167
+ }
168
+
169
+ /**
170
+ * More candidate routes exist than the resolver enumerates.
171
+ *
172
+ * @since @next
173
+ */
174
+ export class TooManyRoutes extends Data.TaggedError("TooManyRoutes")<{
175
+ readonly from: string;
176
+ readonly to: string;
177
+ readonly limit: number;
178
+ }> {
179
+ override get message() {
180
+ return `More than ${this.limit} routes connect "${this.from}" and "${this.to}".`;
181
+ }
182
+ }
183
+
184
+ /** @since @next */
185
+ export type RewriteError = RewriteCycle | ConflictingRewrites | RewriteLimitExceeded;
186
+
187
+ /**
188
+ * Why a plan could not be resolved. `UnsupportedRoute` lists the reachable versions, the
189
+ * closest ones by release ancestry, and blockers. `AmbiguousRoute` lists the candidate
190
+ * routes: pass one as `route`, or choose a `policy`.
191
+ *
192
+ * @since @next
193
+ */
194
+ export type ResolveError =
195
+ | InvalidHistory
196
+ | UnknownVersion
197
+ | UnsupportedRoute
198
+ | AmbiguousRoute
199
+ | UnknownRoute
200
+ | TooManyRoutes
201
+ | RewriteError;