@kition/convergence 0.0.0-stage → 0.2.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.
- package/dist/LICENSE +177 -0
- package/dist/index.js +1033 -0
- package/dist/node.js +8 -0
- package/dist/types/src/adapter.d.ts +131 -0
- package/dist/types/src/engine.d.ts +66 -0
- package/dist/types/src/index.d.ts +21 -0
- package/dist/types/src/net.d.ts +52 -0
- package/dist/types/src/node.d.ts +6 -0
- package/dist/types/src/report.d.ts +56 -0
- package/dist/types/src/rng.d.ts +12 -0
- package/dist/types/src/scenarios.d.ts +15 -0
- package/dist/types/src/state.d.ts +67 -0
- package/package.json +37 -3
- package/README.md +0 -3
package/dist/node.js
ADDED
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a kit supplies to the suite: the TypeScript twin of the Rust `KitAdapter` and `Script`.
|
|
3
|
+
* Errors are thrown; the suite reports them with the scenario.
|
|
4
|
+
*/
|
|
5
|
+
import type { Rng } from './rng.js';
|
|
6
|
+
/** Blob bytes by SHA-256 (lowercase hex), as a replica hands them to a peer. */
|
|
7
|
+
export type Blobs = Map<string, Uint8Array>;
|
|
8
|
+
/**
|
|
9
|
+
* A scripted step the suite asks a kit for. Each acts on the kit's **probe**: an object (or text)
|
|
10
|
+
* the adapter picks deterministically from the document's state (the first slide's first shape,
|
|
11
|
+
* the first paragraph), so every replica that has the same state picks the same one. An adapter
|
|
12
|
+
* answers `false` for a step its kit has no equivalent of; the scenarios that need it are then
|
|
13
|
+
* reported as skipped. Text positions count Unicode scalar values (code points), not UTF-16 units.
|
|
14
|
+
*/
|
|
15
|
+
export type Script =
|
|
16
|
+
/** Sets one register field of the probe object to a value derived from `value`. Slots 0 and 1 MUST be different fields of the same object. */
|
|
17
|
+
{
|
|
18
|
+
kind: 'SetField';
|
|
19
|
+
slot: number;
|
|
20
|
+
value: number;
|
|
21
|
+
}
|
|
22
|
+
/** Creates one object of the kit's main kind (a shape, a paragraph, a layer). */
|
|
23
|
+
| {
|
|
24
|
+
kind: 'Create';
|
|
25
|
+
}
|
|
26
|
+
/** Deletes the probe object. */
|
|
27
|
+
| {
|
|
28
|
+
kind: 'Delete';
|
|
29
|
+
}
|
|
30
|
+
/** Duplicates the probe object. */
|
|
31
|
+
| {
|
|
32
|
+
kind: 'Duplicate';
|
|
33
|
+
}
|
|
34
|
+
/** Moves an item of an ordered collection; `which` 0 and 1 SHOULD move different items. */
|
|
35
|
+
| {
|
|
36
|
+
kind: 'Reorder';
|
|
37
|
+
which: number;
|
|
38
|
+
}
|
|
39
|
+
/** Moves an object under another parent; `which` 0 and 1 SHOULD make conflicting moves (each into the other) when the kit allows it. */
|
|
40
|
+
| {
|
|
41
|
+
kind: 'Reparent';
|
|
42
|
+
which: number;
|
|
43
|
+
}
|
|
44
|
+
/** Inserts `text` at code point `at` of `KitAdapter.text`. */
|
|
45
|
+
| {
|
|
46
|
+
kind: 'InsertText';
|
|
47
|
+
at: number;
|
|
48
|
+
text: string;
|
|
49
|
+
}
|
|
50
|
+
/** Deletes `len` code points at `at` of `KitAdapter.text`. */
|
|
51
|
+
| {
|
|
52
|
+
kind: 'DeleteText';
|
|
53
|
+
at: number;
|
|
54
|
+
len: number;
|
|
55
|
+
}
|
|
56
|
+
/** Splits the paragraph at code point `at`: a `\n` appears there. */
|
|
57
|
+
| {
|
|
58
|
+
kind: 'SplitParagraph';
|
|
59
|
+
at: number;
|
|
60
|
+
}
|
|
61
|
+
/** Merges the paragraphs on both sides of the `\n` at code point `at`. */
|
|
62
|
+
| {
|
|
63
|
+
kind: 'MergeParagraph';
|
|
64
|
+
at: number;
|
|
65
|
+
}
|
|
66
|
+
/** Adds content backed by a new blob whose bytes derive from `seed`. */
|
|
67
|
+
| {
|
|
68
|
+
kind: 'InsertBlob';
|
|
69
|
+
seed: number;
|
|
70
|
+
};
|
|
71
|
+
/** A step as the Rust suite's `{:?}` writes it, for messages: `InsertText { at: 1, text: "zh" }`. */
|
|
72
|
+
export declare function describeStep(step: Script): string;
|
|
73
|
+
/** A contract 2 kit as the suite drives it; `Doc` is one replica (an open document). */
|
|
74
|
+
export interface KitAdapter<Doc> {
|
|
75
|
+
/** The kit id, for reports (`kit.board`). */
|
|
76
|
+
readonly name: string;
|
|
77
|
+
/** The kit's KDM schema (`model/schema.json`) as text, which the reference checks read. */
|
|
78
|
+
readonly schema: string;
|
|
79
|
+
/** A new document with some content (several objects, and text when the kit has text). */
|
|
80
|
+
create(): Doc;
|
|
81
|
+
/** Another replica of a document: opens `snapshot` with its blobs, as a new actor. */
|
|
82
|
+
join(snapshot: Uint8Array, blobs: Blobs): Doc;
|
|
83
|
+
/** The encoded version vector. */
|
|
84
|
+
version(doc: Doc): Uint8Array;
|
|
85
|
+
/** The changes a replica at `since` lacks; empty `since` asks for every change. */
|
|
86
|
+
exportChanges(doc: Doc, since: Uint8Array): Uint8Array;
|
|
87
|
+
/** Takes changes from a peer or from storage, in any order, any number of times. */
|
|
88
|
+
importChanges(doc: Doc, bytes: Uint8Array): void;
|
|
89
|
+
snapshot(doc: Doc): Uint8Array;
|
|
90
|
+
/** The canonical state (`Replica.stateJson`). */
|
|
91
|
+
state(doc: Doc): unknown;
|
|
92
|
+
/** Undoes this replica's last step; answers whether there was one. */
|
|
93
|
+
undo(doc: Doc): boolean;
|
|
94
|
+
redo(doc: Doc): boolean;
|
|
95
|
+
/**
|
|
96
|
+
* One random edit through the kit's commands; answers a label for the step log, or `null` when
|
|
97
|
+
* the picked command did not apply. A command the kit refuses for the document's state is `null`,
|
|
98
|
+
* not an error.
|
|
99
|
+
*/
|
|
100
|
+
randomEdit(doc: Doc, rng: Rng): string | null;
|
|
101
|
+
/** Runs a scripted step; `false` when the kit has no such step (the default). */
|
|
102
|
+
script?(doc: Doc, step: Script): boolean;
|
|
103
|
+
/** The document's text in reading order, paragraphs joined by `\n`, or `null` (the default) when the kit has no text the suite can type into. */
|
|
104
|
+
text?(doc: Doc): string | null;
|
|
105
|
+
/** Throws when the view (what the engine renders and saves) does not match the replica. */
|
|
106
|
+
checkView?(doc: Doc): void;
|
|
107
|
+
/** The blobs the replica holds, for a peer (none by default). */
|
|
108
|
+
blobs?(doc: Doc): Blobs;
|
|
109
|
+
/** Adds a peer's blobs. */
|
|
110
|
+
addBlobs?(doc: Doc, blobs: Blobs): void;
|
|
111
|
+
/** The document as file bytes, when the kit can save; `null` (the default) skips the export checks. */
|
|
112
|
+
exportFile?(doc: Doc): Uint8Array | null;
|
|
113
|
+
/** Whether `ty.field` may name an object that no longer exists (Kition platform `docs/platform/sets/model.md`). */
|
|
114
|
+
allowsDangling?(ty: string, field: string): boolean;
|
|
115
|
+
}
|
|
116
|
+
/** What the suite runs. */
|
|
117
|
+
export type Options = {
|
|
118
|
+
/** Seeds of the fuzzed runs; each runs on every replica count of `replicas`. */
|
|
119
|
+
seeds: number[];
|
|
120
|
+
/** Replica counts of the fuzzed runs (2 to 5). */
|
|
121
|
+
replicas: number[];
|
|
122
|
+
/** Steps of each fuzzed run. */
|
|
123
|
+
steps: number;
|
|
124
|
+
};
|
|
125
|
+
export declare const DEFAULT_OPTIONS: Readonly<Options>;
|
|
126
|
+
/**
|
|
127
|
+
* The default options, heavier when the environment asks (nightly jobs):
|
|
128
|
+
* `KITION_CONVERGENCE_SEEDS=<n>` runs seeds 1 to n (`KITION_CONVERGENCE_SEED_BASE=<b>`: b + 1 to
|
|
129
|
+
* b + n, another range of runs), `KITION_CONVERGENCE_STEPS=<n>` n steps.
|
|
130
|
+
*/
|
|
131
|
+
export declare function optionsFromEnv(env: Record<string, string | undefined>): Options;
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An adapter base for TypeScript engines made with `@kition/kit-engine` (`kitEngineClass` over a
|
|
3
|
+
* `KitModel`): the replica members go through the contract 2 document class a host drives
|
|
4
|
+
* (`version`, `exportChanges`, `importChanges`, `snapshot`, `undo`, `redo`, `blobs`, `addBlobs`,
|
|
5
|
+
* `execute`), and a replica joins a snapshot as a new `KitSession` on its own actor. A kit adds
|
|
6
|
+
* what only it knows: a new document with content, random edits from its command catalogue, the
|
|
7
|
+
* scripted steps on its probe, its text, and its view check.
|
|
8
|
+
*/
|
|
9
|
+
import { Replica } from '@kition/kdm';
|
|
10
|
+
import { KitSession, type KitEngineDocument, type KitModel } from '@kition/kit-engine';
|
|
11
|
+
import type { Blobs, KitAdapter, Script } from './adapter.js';
|
|
12
|
+
import type { Rng } from './rng.js';
|
|
13
|
+
/** A document of a `kitEngineClass` class: the contract 2 members and its session. */
|
|
14
|
+
export type EngineDocument<View> = KitEngineDocument & {
|
|
15
|
+
readonly session: KitSession<View>;
|
|
16
|
+
};
|
|
17
|
+
/** The class `kitEngineClass(model)` makes, as far as the adapter needs it. */
|
|
18
|
+
export type EngineClass<View> = new (session: KitSession<View>) => EngineDocument<View>;
|
|
19
|
+
/** Blobs as `openWithReplica` and `addBlobs` take them: `(64-character hex SHA-256, u64 LE length, bytes) * N`. */
|
|
20
|
+
export declare function encodeBlobBundle(blobs: Blobs): Uint8Array;
|
|
21
|
+
/** Reads a blob bundle (`encodeBlobBundle`). */
|
|
22
|
+
export declare function decodeBlobBundle(bundle: Uint8Array): Blobs;
|
|
23
|
+
/** What every `kitEngineClass` adapter shares. */
|
|
24
|
+
export type KitEngineAdapterOptions<View> = {
|
|
25
|
+
/** The kit id (`kit.board`). */
|
|
26
|
+
name: string;
|
|
27
|
+
/** `model/schema.json` as text. */
|
|
28
|
+
schema: string;
|
|
29
|
+
model: KitModel<View>;
|
|
30
|
+
/** `kitEngineClass(model)`: the class the kit's module exports. */
|
|
31
|
+
documentClass: EngineClass<View>;
|
|
32
|
+
/** The actor of each new replica; random by default. */
|
|
33
|
+
actor?: () => bigint;
|
|
34
|
+
/** The file name `exportFile` saves as; without it the export checks are skipped. */
|
|
35
|
+
fileName?: string;
|
|
36
|
+
};
|
|
37
|
+
export declare abstract class KitEngineAdapter<View> implements KitAdapter<EngineDocument<View>> {
|
|
38
|
+
readonly name: string;
|
|
39
|
+
readonly schema: string;
|
|
40
|
+
protected readonly model: KitModel<View>;
|
|
41
|
+
protected readonly documentClass: EngineClass<View>;
|
|
42
|
+
protected readonly newActor: () => bigint;
|
|
43
|
+
protected readonly fileName: string | null;
|
|
44
|
+
constructor(options: KitEngineAdapterOptions<View>);
|
|
45
|
+
/** A new document with some content (several objects, and text when the kit has text). */
|
|
46
|
+
abstract create(): EngineDocument<View>;
|
|
47
|
+
abstract randomEdit(doc: EngineDocument<View>, rng: Rng): string | null;
|
|
48
|
+
/** A document over `replica`, as the kit's class makes one. */
|
|
49
|
+
protected open(replica: Replica): EngineDocument<View>;
|
|
50
|
+
join(snapshot: Uint8Array, blobs: Blobs): EngineDocument<View>;
|
|
51
|
+
version(doc: EngineDocument<View>): Uint8Array<ArrayBufferLike>;
|
|
52
|
+
exportChanges(doc: EngineDocument<View>, since: Uint8Array): Uint8Array<ArrayBufferLike>;
|
|
53
|
+
importChanges(doc: EngineDocument<View>, bytes: Uint8Array): void;
|
|
54
|
+
snapshot(doc: EngineDocument<View>): Uint8Array<ArrayBufferLike>;
|
|
55
|
+
state(doc: EngineDocument<View>): unknown;
|
|
56
|
+
undo(doc: EngineDocument<View>): boolean;
|
|
57
|
+
redo(doc: EngineDocument<View>): boolean;
|
|
58
|
+
blobs(doc: EngineDocument<View>): Blobs;
|
|
59
|
+
addBlobs(doc: EngineDocument<View>, blobs: Blobs): void;
|
|
60
|
+
exportFile(doc: EngineDocument<View>): Uint8Array | null;
|
|
61
|
+
script(_doc: EngineDocument<View>, _step: Script): boolean;
|
|
62
|
+
/** Runs one of the kit's commands as the host's person, through the document's `execute`; answers its JSON result. */
|
|
63
|
+
protected run(doc: EngineDocument<View>, command: string, params: Record<string, unknown>): unknown;
|
|
64
|
+
}
|
|
65
|
+
/** The UTF-16 index of code point `at` of `text` (KDM text positions are UTF-16 in TypeScript, code points in the suite). */
|
|
66
|
+
export declare function utf16Index(text: string, at: number): number;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@kition/convergence`: the convergence suite of the Kition kit platform (docs/platform/kits/levels.md) for
|
|
3
|
+
* TypeScript engines, what a `ts-worker` kit runs to claim L6. The same 17 scenarios, pass and
|
|
4
|
+
* skip rules, and report as the Rust `kition-convergence` crate, driven through a `KitAdapter`;
|
|
5
|
+
* `KitEngineAdapter` does the replica part for engines made with `@kition/kit-engine`.
|
|
6
|
+
*
|
|
7
|
+
* ```ts
|
|
8
|
+
* it('converges', () => {
|
|
9
|
+
* const report = run(new MyKit(), DEFAULT_OPTIONS)
|
|
10
|
+
* saveReportIfRequested(report) // from '@kition/convergence/node'
|
|
11
|
+
* expect(report.level6(), report.render()).toBe(true)
|
|
12
|
+
* })
|
|
13
|
+
* ```
|
|
14
|
+
*/
|
|
15
|
+
export { DEFAULT_OPTIONS, describeStep, optionsFromEnv, type Blobs, type KitAdapter, type Options, type Script } from './adapter.js';
|
|
16
|
+
export { decodeBlobBundle, encodeBlobBundle, KitEngineAdapter, utf16Index, type EngineClass, type EngineDocument, type KitEngineAdapterOptions } from './engine.js';
|
|
17
|
+
export { bytesEqual, Net, Skip } from './net.js';
|
|
18
|
+
export { Report, SUITE, type Check, type Outcome, type ReportJson } from './report.js';
|
|
19
|
+
export { Rng } from './rng.js';
|
|
20
|
+
export { run, runOne, SCENARIOS } from './scenarios.js';
|
|
21
|
+
export { checkReferences, compareStrings, created, deleted, digest, firstDifference, isRegister, listSets, objects, register, registerChanges, Registers, sameValue, SchemaInfo, treeNodes, type FieldInfo, type Slot, } from './state.js';
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { type Blobs, type KitAdapter, type Script } from './adapter.js';
|
|
2
|
+
import { Rng } from './rng.js';
|
|
3
|
+
import { SchemaInfo } from './state.js';
|
|
4
|
+
/** Thrown by `Net.step` when the kit has no such step: the scenario is skipped. */
|
|
5
|
+
export declare class Skip extends Error {
|
|
6
|
+
}
|
|
7
|
+
export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
|
|
8
|
+
/** The text of `error` for a message. */
|
|
9
|
+
export declare function message(error: unknown): string;
|
|
10
|
+
/** Runs `f`; prefixes the message of what it throws. */
|
|
11
|
+
export declare function context<T>(prefix: string, f: () => T): T;
|
|
12
|
+
/**
|
|
13
|
+
* `count` replicas of one new document: the first made by `KitAdapter.create`, the others joined
|
|
14
|
+
* from its snapshot. Exported so a kit can write scenarios of its own on the same harness.
|
|
15
|
+
*/
|
|
16
|
+
export declare class Net<Doc> {
|
|
17
|
+
readonly kit: KitAdapter<Doc>;
|
|
18
|
+
readonly docs: Doc[];
|
|
19
|
+
readonly schema: SchemaInfo;
|
|
20
|
+
rng: Rng;
|
|
21
|
+
/** The snapshot and blobs every replica started from. */
|
|
22
|
+
readonly initial: {
|
|
23
|
+
snapshot: Uint8Array;
|
|
24
|
+
blobs: Blobs;
|
|
25
|
+
};
|
|
26
|
+
constructor(kit: KitAdapter<Doc>, count: number, seed: number | bigint);
|
|
27
|
+
doc(index: number): Doc;
|
|
28
|
+
state(index: number): unknown;
|
|
29
|
+
/** Runs a scripted step on one replica; `false` when the kit has no such step. */
|
|
30
|
+
script(index: number, step: Script): boolean;
|
|
31
|
+
/** Like `script`, and skips the scenario (throws `Skip`) when the kit has no such step. */
|
|
32
|
+
step(index: number, step: Script): void;
|
|
33
|
+
/** Like `script`, and fails when the kit has no such step. */
|
|
34
|
+
must(index: number, step: Script): void;
|
|
35
|
+
text(index: number): string;
|
|
36
|
+
/** Sends `to` what it lacks from `from`, blobs first. */
|
|
37
|
+
deliver(from: number, to: number): void;
|
|
38
|
+
/**
|
|
39
|
+
* Delivers every replica's changes to every other in seeded orders until no state changes
|
|
40
|
+
* (repairs made on import travel too), then sends everything again from scratch to prove
|
|
41
|
+
* duplicates harmless.
|
|
42
|
+
*/
|
|
43
|
+
sync(): void;
|
|
44
|
+
/** The common state; throws with the first difference. */
|
|
45
|
+
converged(): unknown;
|
|
46
|
+
/** `converged`, the schema's references, and every replica's view. */
|
|
47
|
+
check(): unknown;
|
|
48
|
+
/** `sync` then `check`. */
|
|
49
|
+
settle(): unknown;
|
|
50
|
+
}
|
|
51
|
+
/** The blobs a replica holds (a copy). */
|
|
52
|
+
export declare function blobsOf<Doc>(kit: KitAdapter<Doc>, doc: Doc): Blobs;
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { Report } from './report.js';
|
|
2
|
+
/**
|
|
3
|
+
* Writes the report's JSON to the file `KITION_CONVERGENCE_REPORT` names, when it is set, as the
|
|
4
|
+
* Rust `Report::save_if_requested` does.
|
|
5
|
+
*/
|
|
6
|
+
export declare function saveReportIfRequested(report: Report, env?: Record<string, string | undefined>): void;
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The suite's results and their JSON: the same report as the Rust `kition_convergence::Report`,
|
|
3
|
+
* which `tools/check-manifest.mjs --convergence` reads for L6.
|
|
4
|
+
*/
|
|
5
|
+
/** The suite's name and version in reports: scenarios are only added in a minor version. Both runners write the same one. */
|
|
6
|
+
export declare const SUITE = "kition-convergence 1.0";
|
|
7
|
+
/** How one scenario went; `skipped` when the kit has no such step, with why. */
|
|
8
|
+
export type Outcome = {
|
|
9
|
+
kind: 'passed';
|
|
10
|
+
} | {
|
|
11
|
+
kind: 'failed';
|
|
12
|
+
reason: string;
|
|
13
|
+
} | {
|
|
14
|
+
kind: 'skipped';
|
|
15
|
+
reason: string;
|
|
16
|
+
};
|
|
17
|
+
/** One scenario's result. */
|
|
18
|
+
export type Check = {
|
|
19
|
+
id: string;
|
|
20
|
+
title: string;
|
|
21
|
+
/** Whether L6 needs it to pass (rather than be skipped). */
|
|
22
|
+
required: boolean;
|
|
23
|
+
outcome: Outcome;
|
|
24
|
+
};
|
|
25
|
+
/** A report as JSON: `{ kit, suite, level6, checks: [{ id, title, required, outcome, reason? }] }`. */
|
|
26
|
+
export type ReportJson = {
|
|
27
|
+
kit: string;
|
|
28
|
+
suite: string;
|
|
29
|
+
level6: boolean;
|
|
30
|
+
checks: Array<{
|
|
31
|
+
id: string;
|
|
32
|
+
title: string;
|
|
33
|
+
required: boolean;
|
|
34
|
+
outcome: Outcome['kind'];
|
|
35
|
+
reason?: string;
|
|
36
|
+
}>;
|
|
37
|
+
};
|
|
38
|
+
export declare class Report {
|
|
39
|
+
readonly kit: string;
|
|
40
|
+
readonly checks: Check[];
|
|
41
|
+
constructor(kit: string);
|
|
42
|
+
/** No scenario failed. Skips are allowed here; `level6` is stricter. */
|
|
43
|
+
passed(): boolean;
|
|
44
|
+
/** The kit passes the convergence suite for L6: nothing failed and no required scenario was skipped. */
|
|
45
|
+
level6(): boolean;
|
|
46
|
+
outcome(id: string): Outcome | undefined;
|
|
47
|
+
toJson(): ReportJson;
|
|
48
|
+
/**
|
|
49
|
+
* The JSON as the Rust suite writes it to `KITION_CONVERGENCE_REPORT` (`{:#}` of a
|
|
50
|
+
* `serde_json` value): keys sorted, two-space indents, a final newline.
|
|
51
|
+
*/
|
|
52
|
+
toJsonText(): string;
|
|
53
|
+
/** One line per scenario, then the summary. */
|
|
54
|
+
render(): string;
|
|
55
|
+
push(id: string, title: string, required: boolean, outcome: Outcome): void;
|
|
56
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export declare class Rng {
|
|
2
|
+
private state;
|
|
3
|
+
constructor(seed: number | bigint);
|
|
4
|
+
nextU64(): bigint;
|
|
5
|
+
/** A value in `0..bound`, or 0 when `bound` is 0. */
|
|
6
|
+
below(bound: number): number;
|
|
7
|
+
/** `true` with `percent` percent probability. */
|
|
8
|
+
chance(percent: number): boolean;
|
|
9
|
+
shuffle<T>(items: T[]): void;
|
|
10
|
+
/** One item, or `undefined` for an empty list. */
|
|
11
|
+
pick<T>(items: readonly T[]): T | undefined;
|
|
12
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The scenarios of architecture section 16, scripted and fuzzed: a line-by-line port of the Rust
|
|
3
|
+
* `kition_convergence::scenarios`, with the same seeds, the same order of random draws, and the
|
|
4
|
+
* same pass and skip rules, so a TypeScript kit and a Rust kit are held to one suite. The table of
|
|
5
|
+
* scenarios is checked against the Rust source by this package's tests, and both runners reach the
|
|
6
|
+
* same states on the same toy kit (`test/cross-check.test.ts`).
|
|
7
|
+
*/
|
|
8
|
+
import type { KitAdapter, Options } from './adapter.js';
|
|
9
|
+
import { Report } from './report.js';
|
|
10
|
+
/** Every scenario: `[id, title]`, in the order `run` runs them. The same table as the Rust suite's `SCENARIOS`. */
|
|
11
|
+
export declare const SCENARIOS: ReadonlyArray<readonly [string, string]>;
|
|
12
|
+
/** Runs the whole suite against `kit`. */
|
|
13
|
+
export declare function run<Doc>(kit: KitAdapter<Doc>, options: Options): Report;
|
|
14
|
+
/** Runs one scenario by id (from `SCENARIOS`); `null` for an unknown id. */
|
|
15
|
+
export declare function runOne<Doc>(kit: KitAdapter<Doc>, id: string, options: Options): Report | null;
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/** A field's kind, as the schema names it, and the type a `ref`, `list`, or `tree` names. */
|
|
2
|
+
export type FieldInfo = {
|
|
3
|
+
kind: string;
|
|
4
|
+
of: string | null;
|
|
5
|
+
};
|
|
6
|
+
/** A register: one value, last writer wins. */
|
|
7
|
+
export declare function isRegister(field: FieldInfo): boolean;
|
|
8
|
+
/** Strings in Unicode code point order, as Rust orders `String`s (by their UTF-8 bytes). */
|
|
9
|
+
export declare function compareStrings(a: string, b: string): number;
|
|
10
|
+
/** Whether two JSON values are equal (`undefined` reads as `null`, as a missing key does in Rust). */
|
|
11
|
+
export declare function sameValue(a: unknown, b: unknown): boolean;
|
|
12
|
+
type Json = Record<string, unknown>;
|
|
13
|
+
/** The parts of a KDM schema the suite reads: each type's fields and their kinds. */
|
|
14
|
+
export declare class SchemaInfo {
|
|
15
|
+
readonly kit: string;
|
|
16
|
+
readonly root: string;
|
|
17
|
+
readonly types: ReadonlyMap<string, ReadonlyMap<string, FieldInfo>>;
|
|
18
|
+
constructor(kit: string, root: string, types: ReadonlyMap<string, ReadonlyMap<string, FieldInfo>>);
|
|
19
|
+
/** Reads `model/schema.json`. */
|
|
20
|
+
static parse(text: string): SchemaInfo;
|
|
21
|
+
/** Whether any type has a field of `kind`. */
|
|
22
|
+
hasKind(kind: string): boolean;
|
|
23
|
+
field(ty: string, field: string): FieldInfo | undefined;
|
|
24
|
+
/** A type's fields in name order (none for an unknown type). */
|
|
25
|
+
fieldsOf(ty: string): ReadonlyMap<string, FieldInfo>;
|
|
26
|
+
}
|
|
27
|
+
/** The objects of a state, by id. */
|
|
28
|
+
export declare function objects(state: unknown): Json;
|
|
29
|
+
/** Checks the schema's references in `state`; `dangling(ty, field)` says which fields may name deleted objects. Throws what it found. */
|
|
30
|
+
export declare function checkReferences(schema: SchemaInfo, state: unknown, dangling: (ty: string, field: string) => boolean): void;
|
|
31
|
+
/** A register a state holds: an object's register field, or one key of a map field (`field/key`). */
|
|
32
|
+
export type Slot = readonly [id: string, field: string];
|
|
33
|
+
/** Registers with their values, in slot order (id, then field). */
|
|
34
|
+
export declare class Registers {
|
|
35
|
+
private readonly entries;
|
|
36
|
+
private static key;
|
|
37
|
+
set(slot: Slot, value: unknown): void;
|
|
38
|
+
has(slot: Slot): boolean;
|
|
39
|
+
get(slot: Slot): unknown;
|
|
40
|
+
get size(): number;
|
|
41
|
+
/** The registers in slot order. */
|
|
42
|
+
list(): Array<{
|
|
43
|
+
slot: Slot;
|
|
44
|
+
value: unknown;
|
|
45
|
+
}>;
|
|
46
|
+
filter(keep: (slot: Slot, value: unknown) => boolean): Registers;
|
|
47
|
+
}
|
|
48
|
+
/** The registers that differ from `before` in `after` (new objects' registers included), with their values in `after`. */
|
|
49
|
+
export declare function registerChanges(schema: SchemaInfo, before: unknown, after: unknown): Registers;
|
|
50
|
+
/** A register's value in `state` (see `registerChanges`), `null` when absent. */
|
|
51
|
+
export declare function register(schema: SchemaInfo, state: unknown, slot: Slot): unknown;
|
|
52
|
+
/** Ids in `after` that are not in `before`, in order. */
|
|
53
|
+
export declare function created(before: unknown, after: unknown): string[];
|
|
54
|
+
/** Ids in `before` that are not in `after`, in order. */
|
|
55
|
+
export declare function deleted(before: unknown, after: unknown): string[];
|
|
56
|
+
/** Every list field's items as a set, by `id.field`, in key order. */
|
|
57
|
+
export declare function listSets(schema: SchemaInfo, state: unknown): Map<string, Set<string>>;
|
|
58
|
+
/** Every tree's count of nodes, by `id.field`, in key order. */
|
|
59
|
+
export declare function treeNodes(schema: SchemaInfo, state: unknown): Map<string, number>;
|
|
60
|
+
/** The first place where `a` and `b` differ, as a JSON path with both values (abbreviated), or `null`. */
|
|
61
|
+
export declare function firstDifference(a: unknown, b: unknown): string | null;
|
|
62
|
+
/**
|
|
63
|
+
* For reports only (the suite compares states directly): a short FNV-1a digest of the canonical
|
|
64
|
+
* text, the same as the Rust `state::digest`.
|
|
65
|
+
*/
|
|
66
|
+
export declare function digest(state: unknown): string;
|
|
67
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,40 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kition/convergence",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "The Kition kit platform's convergence suite for TypeScript engines: the scenarios of kition-convergence, run against a contract 2 kit through a small adapter, with the same report.",
|
|
5
|
+
"license": "Apache-2.0",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": {
|
|
9
|
+
"types": "./dist/types/src/index.d.ts",
|
|
10
|
+
"import": "./dist/index.js"
|
|
11
|
+
},
|
|
12
|
+
"./node": {
|
|
13
|
+
"types": "./dist/types/src/node.d.ts",
|
|
14
|
+
"import": "./dist/node.js"
|
|
15
|
+
}
|
|
16
|
+
},
|
|
17
|
+
"files": [
|
|
18
|
+
"dist"
|
|
19
|
+
],
|
|
20
|
+
"dependencies": {
|
|
21
|
+
"@kition/kdm": "0.2.0",
|
|
22
|
+
"@kition/kit-engine": "0.2.0"
|
|
23
|
+
},
|
|
24
|
+
"devDependencies": {
|
|
25
|
+
"@types/node": "^22.20.5"
|
|
26
|
+
},
|
|
27
|
+
"repository": {
|
|
28
|
+
"type": "git",
|
|
29
|
+
"url": "git+https://github.com/KitionAI/kition-sdk.git",
|
|
30
|
+
"directory": "packages/convergence"
|
|
31
|
+
},
|
|
32
|
+
"types": "./dist/types/src/index.d.ts",
|
|
33
|
+
"publishConfig": {
|
|
34
|
+
"access": "public"
|
|
35
|
+
},
|
|
36
|
+
"main": "./dist/index.js",
|
|
37
|
+
"scripts": {
|
|
38
|
+
"build": "node ../../tools/build-package.mjs"
|
|
39
|
+
}
|
|
6
40
|
}
|
package/README.md
DELETED