@sdboyer/thema-playground 0.0.0-stage → 0.1.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/dist/types.ts ADDED
@@ -0,0 +1,623 @@
1
+ // Code generated by playground/tsapi from playground/types.go, diag and lacuna. DO NOT EDIT.
2
+ //
3
+ // The playground's wire format: what each operation of the wasm bridge takes
4
+ // and returns, as JSON.
5
+
6
+ //////////
7
+ // github.com/sdboyer/thema/playground
8
+
9
+ //////////
10
+ // source: types.go
11
+
12
+ /**
13
+ * File is one named text: a file of the authoring form, relative to the
14
+ * lineage's directory (tip.thema, history/0.0.thema), or a normal-form .cue
15
+ * file.
16
+ */
17
+ export interface File {
18
+ path: string;
19
+ text: string;
20
+ }
21
+ /**
22
+ * LineageInput is a lineage as the author wrote it, in exactly one of the two
23
+ * forms: the authoring form (Name and Files) or one normal-form file (Normal,
24
+ * with Path naming the lineage within it when it is not the file's root).
25
+ */
26
+ export interface LineageInput {
27
+ /**
28
+ * Name is the lineage's name in the authoring form, which the authoring
29
+ * form takes from its directory.
30
+ */
31
+ name?: string;
32
+ files?: File[];
33
+ /**
34
+ * Normal is a normal-form file. It may import github.com/sdboyer/thema,
35
+ * and nothing else.
36
+ */
37
+ normal?: File;
38
+ /**
39
+ * Path is the CUE path of the lineage within Normal, such as "lin" or
40
+ * "rename.l". Empty means the file's root.
41
+ */
42
+ path?: string;
43
+ }
44
+ /**
45
+ * DataInput is one data document.
46
+ */
47
+ export interface DataInput {
48
+ /**
49
+ * Filename names the document in diagnostics. It must not end in .cue.
50
+ */
51
+ filename: string;
52
+ text: string;
53
+ /**
54
+ * Format is "json" or "yaml". Empty detects it: JSON first, then YAML.
55
+ */
56
+ format?: string;
57
+ }
58
+ /**
59
+ * Result is what every response carries: whether the operation succeeded,
60
+ * and everything thema had to say about it. OK is false exactly when some
61
+ * diagnostic is an error.
62
+ */
63
+ export interface Result {
64
+ ok: boolean;
65
+ diagnostics: Diagnostic[];
66
+ }
67
+ /**
68
+ * InitResponse describes the playground: the versions it was built from and
69
+ * the operations it answers.
70
+ */
71
+ export interface InitResponse extends Result {
72
+ themaVersion: string;
73
+ cueVersion: string;
74
+ ops: string[];
75
+ }
76
+ /**
77
+ * BindRequest binds a lineage.
78
+ */
79
+ export interface BindRequest {
80
+ lineage: LineageInput;
81
+ }
82
+ /**
83
+ * BindResponse is a bound lineage: its name, its versions in order, and its
84
+ * normal form as text (for the authoring form, what the files compile to).
85
+ * The playground binds a lineage in the authoring form with its tip, on the
86
+ * development path: the tip is the file being edited, and binding the
87
+ * history alone would ignore every edit. Tip describes it, and the
88
+ * diagnostics carry a warning (E1001) for each lens the tip's edge lacks.
89
+ */
90
+ export interface BindResponse extends Result {
91
+ name?: string;
92
+ versions?: string[];
93
+ normal?: string;
94
+ tip?: TipInfo;
95
+ }
96
+ /**
97
+ * TipInfo describes the tip of a lineage in the authoring form.
98
+ */
99
+ export interface TipInfo {
100
+ /**
101
+ * Version is the version the tip cuts as, derived by the compatibility
102
+ * check against the newest version under history/; when the tip is
103
+ * clean, the newest version, which it equals.
104
+ */
105
+ version: string;
106
+ /**
107
+ * Clean says whether the tip equals the newest version under history/,
108
+ * with no lenses: there is nothing to cut.
109
+ */
110
+ clean: boolean;
111
+ /**
112
+ * Provisional says whether the lineage's versions end with the tip's:
113
+ * it is not clean, and an instance of that version is an instance of the
114
+ * tip, not of a version that was cut.
115
+ */
116
+ provisional: boolean;
117
+ }
118
+ /**
119
+ * ValidateRequest validates a data document against one schema. An empty
120
+ * Version means the latest.
121
+ */
122
+ export interface ValidateRequest {
123
+ lineage: LineageInput;
124
+ data: DataInput;
125
+ version?: string;
126
+ }
127
+ /**
128
+ * ValidateResponse names the version the data was validated against.
129
+ */
130
+ export interface ValidateResponse extends Result {
131
+ version?: string;
132
+ }
133
+ /**
134
+ * ValidateAnyRequest searches the lineage for a schema the data is an
135
+ * instance of.
136
+ */
137
+ export interface ValidateAnyRequest {
138
+ lineage: LineageInput;
139
+ data: DataInput;
140
+ }
141
+ /**
142
+ * VersionDiagnostics is what one schema said about the data.
143
+ */
144
+ export interface VersionDiagnostics {
145
+ version: string;
146
+ diagnostics: Diagnostic[];
147
+ }
148
+ /**
149
+ * ValidateAnyResponse names the version that accepted the data, if one did,
150
+ * and what every schema said about it, so that a failure shows why each
151
+ * version refused it.
152
+ */
153
+ export interface ValidateAnyResponse extends Result {
154
+ version?: string;
155
+ perVersion: VersionDiagnostics[];
156
+ }
157
+ /**
158
+ * TranslateRequest translates a data document from one version to another.
159
+ * An empty From searches the lineage for the data's schema.
160
+ */
161
+ export interface TranslateRequest {
162
+ lineage: LineageInput;
163
+ data: DataInput;
164
+ from?: string;
165
+ to: string;
166
+ }
167
+ /**
168
+ * TranslateResponse is the translated instance, as JSON, and the lacunas each
169
+ * step emitted. From and To are versions, except that the tip's provisional
170
+ * version is "tip", and CutsAs then gives the version it cuts as; CutsAs is
171
+ * omitted when the translation does not involve the tip.
172
+ */
173
+ export interface TranslateResponse extends Result {
174
+ from?: string;
175
+ to?: string;
176
+ cutsAs?: string;
177
+ output?: unknown;
178
+ lacunas?: TranslationLacunas;
179
+ }
180
+ /**
181
+ * CodegenRequest generates code from one schema. An empty Version means the
182
+ * latest. Format is "json" or "yaml" for OpenAPI and JSON Schema, and is
183
+ * ignored for TypeScript.
184
+ */
185
+ export interface CodegenRequest {
186
+ lineage: LineageInput;
187
+ version?: string;
188
+ format?: string;
189
+ }
190
+ /**
191
+ * CodegenResponse is the generated text.
192
+ */
193
+ export interface CodegenResponse extends Result {
194
+ version?: string;
195
+ output?: string;
196
+ }
197
+ /**
198
+ * CompileRequest compiles authoring files to the normal form, with the tip,
199
+ * as the playground binds them.
200
+ */
201
+ export interface CompileRequest {
202
+ name: string;
203
+ files: File[];
204
+ }
205
+ /**
206
+ * CompileResponse is the normal form as text.
207
+ */
208
+ export interface CompileResponse extends Result {
209
+ normal?: string;
210
+ }
211
+ /**
212
+ * DecompileRequest recovers the authoring files of a normal-form lineage.
213
+ */
214
+ export interface DecompileRequest {
215
+ normal: File;
216
+ path?: string;
217
+ }
218
+ /**
219
+ * DecompileResponse is the lineage's name and its files: its versions under
220
+ * history/, and a clean tip.
221
+ */
222
+ export interface DecompileResponse extends Result {
223
+ name?: string;
224
+ files?: File[];
225
+ }
226
+ /**
227
+ * FormatRequest lays out one file of the authoring form in its layout.
228
+ */
229
+ export interface FormatRequest {
230
+ file: File;
231
+ }
232
+ /**
233
+ * FormatResponse is the formatted text.
234
+ */
235
+ export interface FormatResponse extends Result {
236
+ text?: string;
237
+ }
238
+ /**
239
+ * ExampleInfo describes one example the playground offers.
240
+ */
241
+ export interface ExampleInfo {
242
+ id: string;
243
+ title: string;
244
+ category: string;
245
+ summary: string;
246
+ /**
247
+ * Kind is the form the example is written in: "authoring" or "normal".
248
+ */
249
+ kind: string;
250
+ /**
251
+ * Binds says whether the lineage binds; an example of an error does not.
252
+ */
253
+ binds: boolean;
254
+ }
255
+ /**
256
+ * ListExamplesResponse lists the examples.
257
+ */
258
+ export interface ListExamplesResponse extends Result {
259
+ examples: ExampleInfo[];
260
+ }
261
+ /**
262
+ * GetExampleRequest asks for one example by ID.
263
+ */
264
+ export interface GetExampleRequest {
265
+ id: string;
266
+ }
267
+ /**
268
+ * GetExampleResponse is an example's lineage and data documents.
269
+ */
270
+ export interface GetExampleResponse extends Result {
271
+ example: ExampleInfo;
272
+ lineage: LineageInput;
273
+ data: DataInput[];
274
+ }
275
+ /**
276
+ * RegisterExamplesRequest adds a host's own examples to thema's, for a
277
+ * deployment of the playground that offers lineages of its own. The examples
278
+ * and example operations then serve both, thema's first. It replaces the
279
+ * examples any earlier request registered.
280
+ */
281
+ export interface RegisterExamplesRequest {
282
+ examples: HostExample[];
283
+ }
284
+ /**
285
+ * HostExample is one example a host supplies, in the shape the example
286
+ * operation returns it. Its ID must be unique among all the examples, and its
287
+ * category must not be one of thema's own. An empty Kind is taken from the
288
+ * lineage's form; a Kind given must name that form. Binds is checked by
289
+ * binding the lineage. Data is offered with the example as it is given.
290
+ */
291
+ export interface HostExample {
292
+ example: ExampleInfo;
293
+ lineage: LineageInput;
294
+ data?: DataInput[];
295
+ }
296
+ /**
297
+ * RegisterExamplesResponse lists the IDs of the examples registered, in the
298
+ * request's order. Each example refused has an error diagnostic saying why;
299
+ * the others are registered regardless.
300
+ */
301
+ export interface RegisterExamplesResponse extends Result {
302
+ registered: string[];
303
+ }
304
+
305
+ //////////
306
+ // github.com/sdboyer/thema/diag
307
+
308
+ //////////
309
+ // source: address.go
310
+
311
+ /**
312
+ * AddrKind says what construct an Address names.
313
+ */
314
+ export type AddrKind = string;
315
+ export const AddrLineage: AddrKind = "lineage";
316
+ export const AddrName: AddrKind = "name";
317
+ export const AddrJoinSchema: AddrKind = "joinSchema";
318
+ export const AddrSchema: AddrKind = "schema"; // Version
319
+ export const AddrSchemaField: AddrKind = "schemaField"; // Version, Field
320
+ export const AddrExample: AddrKind = "example"; // Version, Name
321
+ export const AddrLens: AddrKind = "lens"; // From, To
322
+ export const AddrLensInput: AddrKind = "lensInput"; // From, To
323
+ export const AddrLensResult: AddrKind = "lensResult"; // From, To
324
+ export const AddrLensResultField: AddrKind = "lensResultField"; // From, To, Field
325
+ export const AddrLacuna: AddrKind = "lacuna"; // From, To, Index (or Field for keyed lacunas)
326
+ export const AddrLacunaField: AddrKind = "lacunaField"; // From, To, Index, Name
327
+ export const AddrStep: AddrKind = "step"; // From, To, Index: one step of a translation
328
+ export const AddrData: AddrKind = "data"; // Field
329
+ /**
330
+ * Version is a syntactic version as an Address carries it. It is a pair rather
331
+ * than thema.SyntacticVersion because diag must not import the thema root.
332
+ */
333
+ export type Version = number /* uint */[];
334
+ /**
335
+ * Address is the structured subject of a Diagnostic, in terms independent of
336
+ * how the lineage was written. A Vocabulary renders it into the author's.
337
+ */
338
+ export interface Address {
339
+ kind: AddrKind;
340
+ version?: Version;
341
+ from?: Version;
342
+ to?: Version;
343
+ /**
344
+ * Index is a lacuna's or a translation step's index.
345
+ */
346
+ index?: number /* int */;
347
+ /**
348
+ * Field is a path inside a schema, a lens result or the data.
349
+ */
350
+ field?: string[];
351
+ /**
352
+ * Name is an example's name, a lacuna field's name, or an unknown field.
353
+ */
354
+ name?: string;
355
+ }
356
+
357
+ //////////
358
+ // source: diag.go
359
+
360
+ /**
361
+ * Severity is how seriously a Diagnostic is to be taken.
362
+ */
363
+ export type Severity = string;
364
+ /**
365
+ * SeverityError: the operation failed. A lineage with an error does not bind; data
366
+ * with an error is not an instance.
367
+ */
368
+ export const SeverityError: Severity = "error";
369
+ /**
370
+ * SeverityWarning: the operation succeeded, but the author should look.
371
+ */
372
+ export const SeverityWarning: Severity = "warning";
373
+ /**
374
+ * SeverityNote: information with no judgment attached.
375
+ */
376
+ export const SeverityNote: Severity = "note";
377
+ /**
378
+ * Origin says whose text a position points into.
379
+ */
380
+ export type Origin = string;
381
+ /**
382
+ * OriginUser: a file the author wrote, or data they supplied.
383
+ */
384
+ export const OriginUser: Origin = "user";
385
+ /**
386
+ * OriginThema: thema's own CUE. Never the author's line.
387
+ */
388
+ export const OriginThema: Origin = "thema";
389
+ /**
390
+ * OriginSynth: a position with no file behind it, such as a value built
391
+ * in Go without a filename.
392
+ */
393
+ export const OriginSynth: Origin = "synth";
394
+ /**
395
+ * Code identifies a diagnostic's meaning, stably: E0304 always means the same
396
+ * thing, and a retired code is never reused. Codes are grouped by hundreds;
397
+ * see [Codes].
398
+ */
399
+ export type Code = string;
400
+ /**
401
+ * MaxHeadline is the longest a headline may be. A longer statement is split: a
402
+ * shorter headline names the rule and the construct, and the statement becomes
403
+ * a note.
404
+ */
405
+ export const MaxHeadline = 140;
406
+ /**
407
+ * Pos is a position in a file. Line and Col are 1-based; Col counts bytes, as
408
+ * CUE reports it.
409
+ */
410
+ export interface Pos {
411
+ file: string;
412
+ line: number /* int */;
413
+ col: number /* int */;
414
+ offset?: number /* int */;
415
+ origin: Origin;
416
+ }
417
+ /**
418
+ * Span is a range in one file, from Start up to but not including End.
419
+ */
420
+ export interface Span {
421
+ start: Pos;
422
+ end: Pos;
423
+ }
424
+ /**
425
+ * Note is a supporting statement, optionally anchored at a position.
426
+ */
427
+ export interface Note {
428
+ pos?: Pos;
429
+ label: string;
430
+ }
431
+ /**
432
+ * Fix is a machine-applicable edit that resolves the diagnostic.
433
+ */
434
+ export interface Fix {
435
+ span: Span;
436
+ replacement: string;
437
+ }
438
+ /**
439
+ * Diagnostic is one thing thema has to say about an input.
440
+ */
441
+ export interface Diagnostic {
442
+ code: Code;
443
+ severity: Severity;
444
+ /**
445
+ * Headline names the rule and what violates it, in the author's vocabulary.
446
+ */
447
+ headline: string;
448
+ /**
449
+ * Path locates the subject in the author's vocabulary, rendered from
450
+ * Address by a Vocabulary.
451
+ */
452
+ path?: string[];
453
+ /**
454
+ * Address is the structured subject, in terms independent of how the
455
+ * lineage was written.
456
+ */
457
+ address?: Address;
458
+ /**
459
+ * Primary is the author's position, or nil when none could be found.
460
+ */
461
+ primary?: Pos;
462
+ /**
463
+ * Notes say why, and where else to look.
464
+ */
465
+ notes?: Note[];
466
+ /**
467
+ * Help says what to do.
468
+ */
469
+ help?: string[];
470
+ /**
471
+ * Fix is an edit that resolves the diagnostic, when thema knows one.
472
+ */
473
+ fix?: Fix;
474
+ /**
475
+ * Detail is supporting text that is not thema's own, such as CUE's
476
+ * message verbatim.
477
+ */
478
+ detail?: string;
479
+ }
480
+ /**
481
+ * Report is what a tool emits: the diagnostics of one operation.
482
+ */
483
+ export interface Report {
484
+ diagnostics: Diagnostic[];
485
+ summary: Summary;
486
+ }
487
+ /**
488
+ * Summary counts a Report's diagnostics by severity.
489
+ */
490
+ export interface Summary {
491
+ errors: number /* int */;
492
+ warnings: number /* int */;
493
+ notes: number /* int */;
494
+ }
495
+
496
+ //////////
497
+ // github.com/sdboyer/thema/lacuna
498
+
499
+ //////////
500
+ // source: lacuna.go
501
+ /*
502
+ Package lacuna defines the Go types for lacunas, the semantic gaps a lens
503
+ reports when it translates an instance between schemas.
504
+
505
+ This package does not depend on CUE, and must not come to. Lacunas are
506
+ emitted not only by thema's CUE-evaluating Translate, but also by engines
507
+ that run lenses compiled from a lineage and never link CUE. A test enforces
508
+ the package's CUE-freedom.
509
+
510
+ The kinds of lacuna are defined, and documented, in thema's CUE (LacunaTypes
511
+ in lacuna.cue); the Go constants here mirror them, and a test keeps the two
512
+ in lockstep. Checks that need CUE, such as that a lacuna's field references
513
+ name fields its schemas declare, live with the callers that have CUE.
514
+ */
515
+
516
+ /**
517
+ * TranslationLacunas holds the lacunas emitted by a translation, step by step.
518
+ * A translation between non-adjacent schemas passes through each intermediate
519
+ * schema. Each step's lacunas are expressed in that step's terms: field paths
520
+ * refer to the step's source and target schemas, and are not re-mapped through
521
+ * later steps.
522
+ */
523
+ export type TranslationLacunas = TranslationStep[];
524
+ /**
525
+ * TranslationStep is a single step of a translation, between adjacent schemas,
526
+ * and the lacunas emitted by that step.
527
+ */
528
+ export interface TranslationStep {
529
+ from: SyntacticVersion;
530
+ to: SyntacticVersion;
531
+ lacunas: Lacuna[];
532
+ }
533
+ /**
534
+ * SyntacticVersion is the position of a schema within a lineage: the index of
535
+ * the schema's sequence within the lineage, then the index of the schema within
536
+ * that sequence.
537
+ * It duplicates thema.SyntacticVersion, which this package cannot import
538
+ * without depending on CUE. The two have the same underlying type, so each
539
+ * converts to the other.
540
+ */
541
+ export type SyntacticVersion = number /* uint */[];
542
+ /**
543
+ * A Lacuna represents a semantic gap in a Lens's mapping between schemas.
544
+ * For any given mapping between schema, there may exist some valid values and
545
+ * intended semantics on either side that are impossible to precisely translate.
546
+ * When such gaps occur, and an actual schema instance falls into such a gap,
547
+ * the Lens is expected to emit Lacuna that describe the general nature of the
548
+ * translation gap.
549
+ * The production of a lacuna as the output of the translation of a particular
550
+ * instance indicates the lacuna applies to that specific translation.
551
+ */
552
+ export interface Lacuna {
553
+ /**
554
+ * The fields in the pre-translation instance that are relevant to the lacuna.
555
+ */
556
+ sourceFields?: FieldRef[];
557
+ /**
558
+ * The fields in the post-translation instance that are relevant to the lacuna.
559
+ */
560
+ targetFields?: FieldRef[];
561
+ /**
562
+ * The kind of gap.
563
+ */
564
+ type: Type;
565
+ /**
566
+ * A human-readable message describing the gap in translation.
567
+ */
568
+ message: string;
569
+ }
570
+ /**
571
+ * Type identifies a kind of gap a lacuna can describe. The types are
572
+ * defined, and documented, in thema's CUE (LacunaTypes in lacuna.cue).
573
+ */
574
+ export type Type = string;
575
+ /**
576
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
577
+ * each means.
578
+ */
579
+ export const Placeholder: Type = "Placeholder";
580
+ /**
581
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
582
+ * each means.
583
+ */
584
+ export const DroppedField: Type = "DroppedField";
585
+ /**
586
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
587
+ * each means.
588
+ */
589
+ export const LossyFieldMapping: Type = "LossyFieldMapping";
590
+ /**
591
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
592
+ * each means.
593
+ */
594
+ export const ChangedDefault: Type = "ChangedDefault";
595
+ /**
596
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
597
+ * each means.
598
+ */
599
+ export const PrecisionLoss: Type = "PrecisionLoss";
600
+ /**
601
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
602
+ * each means.
603
+ */
604
+ export const AmbiguousMapping: Type = "AmbiguousMapping";
605
+ /**
606
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
607
+ * each means.
608
+ */
609
+ export const Defaulted: Type = "Defaulted";
610
+ /**
611
+ * FieldRef identifies a field in an instance being translated, and its value at
612
+ * the time of translation.
613
+ */
614
+ export interface FieldRef {
615
+ /**
616
+ * Path to the field, in CUE path syntax.
617
+ */
618
+ path: string;
619
+ /**
620
+ * The value of the field at the time of translation.
621
+ */
622
+ value: any;
623
+ }