@liminalia/runtime 0.0.0-stage → 0.8.4

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/LICENSE +106 -0
  2. package/dist/src/chat.js +60 -0
  3. package/dist/src/commands-play.js +300 -0
  4. package/dist/src/commands.js +534 -0
  5. package/dist/src/coverage.js +208 -0
  6. package/dist/src/headless.js +109 -0
  7. package/dist/src/host.js +1 -0
  8. package/dist/src/index.js +15 -0
  9. package/dist/src/prefetch.js +80 -0
  10. package/dist/src/program.js +131 -0
  11. package/dist/src/project-options.js +84 -0
  12. package/dist/src/retranslate.js +44 -0
  13. package/dist/src/route.js +242 -0
  14. package/dist/src/runtime.js +1929 -0
  15. package/dist/src/save.js +51 -0
  16. package/dist/src/scenario-test.js +200 -0
  17. package/dist/src/state.js +62 -0
  18. package/dist/src/value.js +464 -0
  19. package/dist/src/voice-observe.js +82 -0
  20. package/package.json +33 -4
  21. package/src/chat.ts +109 -0
  22. package/src/commands-play.ts +280 -0
  23. package/src/commands.ts +457 -0
  24. package/src/coverage.ts +257 -0
  25. package/src/headless.ts +139 -0
  26. package/src/host.ts +116 -0
  27. package/src/index.ts +16 -0
  28. package/src/prefetch.ts +78 -0
  29. package/src/program.ts +186 -0
  30. package/src/project-options.ts +128 -0
  31. package/src/retranslate.ts +67 -0
  32. package/src/route.ts +365 -0
  33. package/src/runtime.ts +2143 -0
  34. package/src/save.ts +60 -0
  35. package/src/scenario-test.ts +218 -0
  36. package/src/state.ts +353 -0
  37. package/src/value.ts +443 -0
  38. package/src/voice-observe.ts +85 -0
  39. package/types/src/chat.d.ts +63 -0
  40. package/types/src/commands-play.d.ts +2 -0
  41. package/types/src/commands.d.ts +2 -0
  42. package/types/src/coverage.d.ts +100 -0
  43. package/types/src/headless.d.ts +77 -0
  44. package/types/src/host.d.ts +140 -0
  45. package/types/src/index.d.ts +16 -0
  46. package/types/src/prefetch.d.ts +18 -0
  47. package/types/src/program.d.ts +107 -0
  48. package/types/src/project-options.d.ts +103 -0
  49. package/types/src/retranslate.d.ts +39 -0
  50. package/types/src/route.d.ts +181 -0
  51. package/types/src/runtime.d.ts +553 -0
  52. package/types/src/save.d.ts +21 -0
  53. package/types/src/scenario-test.d.ts +43 -0
  54. package/types/src/state.d.ts +357 -0
  55. package/types/src/value.d.ts +61 -0
  56. package/types/src/voice-observe.d.ts +26 -0
  57. package/README.md +0 -3
package/src/route.ts ADDED
@@ -0,0 +1,365 @@
1
+ import type { Diagnostic } from "@liminalia/lang";
2
+ import type { ChoiceLook, Host, PresentEvent } from "./host.ts";
3
+ import { Runtime, type RunResult, type RuntimeOptions } from "./runtime.ts";
4
+ import { clonePlain, type SaveData } from "./state.ts";
5
+ import type { Scope, Value } from "./value.ts";
6
+
7
+ /**
8
+ * 画面なしで流して「道筋」(どの選択肢を選んで来たか)を探す仕組み。ブラウザでも Node でも動く。
9
+ * 書き出しに同梱するテスト用セーブ(lim build --seed)と、制作画面の各行の状態(現在地)が使う。
10
+ *
11
+ * 選び方: plan(何回目の選択で何番を選ぶか)を先に使い、使い切ったら、同じ選択肢(文の並びが同じもの)に
12
+ * 戻ってくるたびに (offset + 戻った回数) 番目を選ぶ。外れを選ぶと同じ選択肢に戻る作りの場面でも、輪から抜けられる。
13
+ */
14
+
15
+ /** 選んだ選択肢。 */
16
+ export interface ChoiceMade {
17
+ file: string;
18
+ line: number;
19
+ /** 選んだ番号(0 始まり)と、選択肢の数・文。 */
20
+ picked: number;
21
+ count: number;
22
+ text: string;
23
+ /** order で試す順を決めたときの、その順の中の位置(picked = order[rank])。 */
24
+ rank?: number;
25
+ }
26
+
27
+ /** 変数のパス → その値を最後に決めた行。 */
28
+ export type Assignments = Record<string, { file: string; line: number }>;
29
+
30
+ /** 流している途中の様子(手がかりの関数に渡す)。 */
31
+ export interface Walk {
32
+ runtime: Runtime;
33
+ /** ここまでに選んだ選択肢(start が save なら、そこから後のもの)。 */
34
+ choices: ChoiceMade[];
35
+ /** ここまでに変数を決めた行(start で渡したものに足していく)。 */
36
+ assigned: Assignments;
37
+ }
38
+
39
+ export interface WalkOptions {
40
+ loadSource(file: string): Promise<string>;
41
+ /** 実行器の設定(話者・作品固有の命令など)。onAssign・onStep は walk が使うので渡さない。 */
42
+ runtime?: Omit<RuntimeOptions, "onAssign" | "onStep">;
43
+ /** 開始位置(ファイル[#ラベル])か、セーブから再開(temp・system・assigned はその時点のもの)。 */
44
+ start: string | { save: SaveData; temp?: Scope; system?: Scope; assigned?: Assignments };
45
+ /** 何回目の選択で何番を選ぶか(order があれば、order の中の位置)。 */
46
+ plan?: readonly number[];
47
+ offset?: number;
48
+ /**
49
+ * 選択肢を試す順(選択肢の番号の並び)。あれば plan はこの順の中の位置で、plan を使い切ったら、同じ選択肢に戻ってくるたびに
50
+ * この順で次のものを選ぶ(目標に近いものから試す探索に使う)。
51
+ */
52
+ order?(at: { file: string; line: number }, options: string[], walk: Walk, targets?: (string | null)[]): number[];
53
+ /**
54
+ * plan を使い切ったときに選ぶ番号(出した選択肢の中の番号)。無ければ、同じ選択肢に戻ってくるたびに次のものを選ぶ(offset から)。
55
+ * order があれば order を使う。
56
+ */
57
+ pick?(at: { file: string; line: number }, options: string[], walk: Walk, targets?: (string | null)[]): number;
58
+ /** 描画側へ送るものすべて(ページ、本文、改行、命令)を、送るたびに呼ぶ(page・choice より先)。 */
59
+ present?(event: PresentEvent, walk: Walk): void;
60
+ /** ページを出す直前に呼ぶ(runtime.save() はそのページから再開するセーブになる)。true を返すとそこで止める。key はページの鍵(既読を見るため)。 */
61
+ page?(at: { file: string; line: number; key?: string }, walk: Walk): boolean | void;
62
+ /** 選択肢を出す直前(選ぶ前)に呼ぶ(runtime.save() はその選択肢から再開するセーブになる。targets は選択肢の飛び先)。true を返すとそこで止める。 */
63
+ choice?(at: { file: string; line: number }, options: string[], walk: Walk, targets?: (string | null)[]): boolean | void;
64
+ /** 一つの命令を実行する直前に呼ぶ(runtime.save() はその命令から再開するセーブ、つまり前の命令を実行した直後の状態)。 */
65
+ step?(at: { file: string; line: number }, walk: Walk): void;
66
+ /**
67
+ * 描画側へ送るたびと選択肢を選ぶ前に呼び、Promise を返せばそれを待ってから続ける。流している間も、ときどきほかの処理
68
+ * (開発サーバーのほかの要求など)へ手を離すため。
69
+ */
70
+ pause?(): void | Promise<void>;
71
+ onDiagnostic?(d: Diagnostic): void;
72
+ }
73
+
74
+ /** 選択肢の文(画像のボタンで文が無いものは画像の名前)。 */
75
+ function optionTexts(texts: string[], looks?: (ChoiceLook | null)[]): string[] {
76
+ return texts.map((t, i) => t || looks?.[i]?.image || t);
77
+ }
78
+
79
+ /** 一回流す。止めた・終わった・上限に達したら返る。 */
80
+ export async function walk(o: WalkOptions): Promise<{ result: RunResult; walk: Walk }> {
81
+ const plan = o.plan ?? [];
82
+ const offset = o.offset ?? 0;
83
+ const seen = new Map<string, number>();
84
+ const start = typeof o.start === "string" ? null : o.start;
85
+ const state: Walk = { runtime: null as unknown as Runtime, choices: [], assigned: { ...(start?.assigned ?? {}) } };
86
+ const host: Host = {
87
+ // 人が操作せずに流す(命令の autoplay の答えで進める)
88
+ automated: true,
89
+ loadSource: (file) => o.loadSource(file),
90
+ present: async (event: PresentEvent) => {
91
+ o.present?.(event, state);
92
+ if (event.type === "page" && o.page?.(event.key ? { ...event.at, key: event.key } : event.at, state)) runtime.stop();
93
+ const paused = o.pause?.();
94
+ if (paused) await paused;
95
+ },
96
+ waitClick: async () => {},
97
+ choose: async (texts, _signal, looks, targets) => {
98
+ const paused = o.pause?.();
99
+ if (paused) await paused;
100
+ const at = runtime.at ?? { file: "", line: 0 };
101
+ if (o.choice?.(at, optionTexts(texts, looks), state, targets)) {
102
+ runtime.stop();
103
+ return null;
104
+ }
105
+ const key = texts.join("\u0000");
106
+ const n = seen.get(key) ?? 0;
107
+ seen.set(key, n + 1);
108
+ const order = o.order?.(at, optionTexts(texts, looks), state, targets);
109
+ if (order && order.length === texts.length) {
110
+ const rank = Math.min(plan[state.choices.length] ?? n % texts.length, texts.length - 1);
111
+ const picked = order[rank]!;
112
+ state.choices.push({ file: at.file, line: at.line, picked, count: texts.length, text: optionTexts(texts, looks)[picked] ?? "", rank });
113
+ return picked;
114
+ }
115
+ const planned = plan[state.choices.length];
116
+ const picked = Math.min(Math.max(0, planned ?? o.pick?.(at, optionTexts(texts, looks), state, targets) ?? (offset + n) % texts.length), texts.length - 1);
117
+ state.choices.push({ file: at.file, line: at.line, picked, count: texts.length, text: optionTexts(texts, looks)[picked] ?? "" });
118
+ return picked;
119
+ },
120
+ ...(o.onDiagnostic ? { onDiagnostic: (d: Diagnostic) => o.onDiagnostic!(d) } : {}),
121
+ };
122
+ const runtime = new Runtime(host, {
123
+ ...o.runtime,
124
+ onAssign: (path: string, _value: Value, at: { file: string; line: number }) => {
125
+ state.assigned[path] = at;
126
+ },
127
+ ...(o.step ? { onStep: (at: { file: string; line: number }) => o.step!(at, state) } : {}),
128
+ });
129
+ state.runtime = runtime;
130
+ if (start) {
131
+ if (start.temp) runtime.state.temp = structuredClone(start.temp);
132
+ if (start.system) runtime.system = structuredClone(start.system);
133
+ return { result: await runtime.load(start.save), walk: state };
134
+ }
135
+ return { result: await runtime.start(o.start as string), walk: state };
136
+ }
137
+
138
+ /** 着いた時点の様子。 */
139
+ export interface Reached {
140
+ /** 着いたページ(選択肢)から再開するセーブ。 */
141
+ save: SaveData;
142
+ temp: Scope;
143
+ system: Scope;
144
+ at: { file: string; line: number };
145
+ /** 着くまでに選んだ選択肢。 */
146
+ choices: ChoiceMade[];
147
+ assigned: Assignments;
148
+ }
149
+
150
+ export interface FindRouteOptions extends Omit<WalkOptions, "page" | "choice" | "plan" | "offset"> {
151
+ /**
152
+ * 着いたと見なすか。ページと選択肢を出す直前ごとに呼ぶ。kind はページか選択肢か(選択肢で着いたと見なさないなら "choice" に false を返す)。
153
+ * walk は途中の様子(着かなかった道筋の途中も、ほかのファイルへの道筋として控えられる)。
154
+ */
155
+ reached(kind: "page" | "choice", at: { file: string; line: number }, walk: Walk): boolean;
156
+ /**
157
+ * この回をあきらめるか(ページと選択肢を出す直前ごとに、reached で着かなかったときに呼ぶ)。true ならその回をそこで打ち切り、
158
+ * 着かなかったものとして次の選び方へ進む(着かないと分かった回を終わりまで流さないため)。
159
+ */
160
+ giveUp?(walk: Walk): boolean;
161
+ /** やり直す回数の上限。既定 400。 */
162
+ attempts?: number;
163
+ }
164
+
165
+ /** その時点の様子を控える。 */
166
+ export function capture(walk: Walk, at: { file: string; line: number }): Reached {
167
+ return {
168
+ save: walk.runtime.save(),
169
+ temp: clonePlain(walk.runtime.state.temp),
170
+ system: clonePlain(walk.runtime.system),
171
+ at,
172
+ choices: walk.choices.map((c) => ({ ...c })),
173
+ assigned: { ...walk.assigned },
174
+ };
175
+ }
176
+
177
+ /**
178
+ * 後戻りの探索で、start から reached に着く道筋を探す。着かなければ、最後の選択を次の番号に変えてやり直す
179
+ * (選び尽くしたらその前の選択へ)。外れの選択でバッドエンドに行った道筋は捨て、着けた最初の道筋を使う。
180
+ * 見つからなければ null。
181
+ */
182
+ export async function findRoute(o: FindRouteOptions): Promise<Reached | null> {
183
+ let plan: number[] = [];
184
+ for (let attempt = 0; attempt < (o.attempts ?? 400); attempt++) {
185
+ const box: { found: Reached | null } = { found: null };
186
+ const check = (kind: "page" | "choice", at: { file: string; line: number }, w: Walk) => {
187
+ if (box.found) return false;
188
+ if (!o.reached(kind, at, w)) return o.giveUp?.(w) ?? false;
189
+ box.found = capture(w, at);
190
+ return true;
191
+ };
192
+ const { walk: w } = await walk({ ...o, plan, page: (at, w) => check("page", { file: at.file, line: at.line }, w), choice: (at, _options, w) => check("choice", at, w) });
193
+ if (box.found) return box.found;
194
+ // 最後の選択を次のものに変えてやり直す(試す順があれば、その順の次)
195
+ const choices = w.choices;
196
+ const pos = (c: ChoiceMade) => c.rank ?? c.picked;
197
+ let i = choices.length - 1;
198
+ while (i >= 0 && pos(choices[i]!) + 1 >= choices[i]!.count) i--;
199
+ if (i < 0) break;
200
+ plan = [...choices.slice(0, i).map(pos), pos(choices[i]!) + 1];
201
+ }
202
+ return null;
203
+ }
204
+
205
+ // ---- 選び方を広げて流す(全ルートテスト、lim coverage) ----
206
+
207
+ /** 選び方の木の一つの選択肢(ある選び方で来て出た、ある選択肢)。 */
208
+ interface ExploreNode {
209
+ /** ここへ来るまでに選んだ番号の並び。 */
210
+ prefix: number[];
211
+ /** 選択肢の場所("ファイル:行")と、出した選択肢の文。 */
212
+ site: string;
213
+ options: string[];
214
+ /** 試した番号。 */
215
+ tried: boolean[];
216
+ }
217
+
218
+ export interface ExploreOptions extends Omit<WalkOptions, "start" | "plan" | "offset" | "order" | "pick" | "choice"> {
219
+ /** 開始位置(ファイル[#ラベル])。 */
220
+ start: string;
221
+ /** 流す回数の上限。 */
222
+ runs: number;
223
+ /** 止める合図(止めたら、そこまでで返す)。 */
224
+ signal?: AbortSignal;
225
+ /** 選択肢を出す直前(選ぶ前)に呼ぶ(targets は選択肢の飛び先)。true ならその回をそこで止める。 */
226
+ choice?(at: { file: string; line: number }, options: string[], walk: Walk, targets?: (string | null)[]): boolean | void;
227
+ /** 一回流す前に呼ぶ(回ごとの控えを片づける)。index は 0 から数えた回。 */
228
+ begin?(index: number): void;
229
+ /**
230
+ * 一回流し終えるたびに呼ぶ。merged は、前の回で通ったのと同じ状態の選択肢に来たので、その先を流さずに止めた回
231
+ * (その先は前の回の選び方で試すので、終わり方には数えない)。
232
+ */
233
+ ran?(run: { index: number; result: RunResult; walk: Walk; merged: boolean }): void | Promise<void>;
234
+ }
235
+
236
+ export interface Exploration {
237
+ /** 流した回数。 */
238
+ runs: number;
239
+ /** 選び方をすべて試したか(false なら上限か止める合図で打ち切った)。 */
240
+ complete: boolean;
241
+ }
242
+
243
+ /**
244
+ * 選択肢の選び方を、まだ試していないものへ広げながら何回も流す(全ルートテストと lim coverage)。
245
+ *
246
+ * - 流した選び方を木に覚え、次の回は、まだ試していない「選択肢と番号」の組を一つ選び、そこまでの選び方をなぞってからそれを選ぶ。
247
+ * 選ぶ組は、その選択肢(場所と文)がまだ一度も選ばれていないものを先に、次に浅いもの(先に出る選択肢)を先にする。
248
+ * 試していない組が無くなれば、すべての選び方を試し終えたので止める(complete)。小さな作品は上限までにすべての道を通る。
249
+ * - なぞった先の、初めて出る選択肢では、その場所でまだ選ばれた数の少ない選択肢を選ぶ(同じ選択肢へ戻る輪も、いずれ別のものを選んで抜ける)。
250
+ * - 前の回で通ったのと同じ状態(場所、変数、呼び出し、舞台など)の選択肢に別の選び方で来たら、その先は同じ流れになるので、その回をそこで止める
251
+ * (merged)。ラベルに入った回数と選んだ回数は 2 回以上を同じとみなす(外れを選ぶと戻る輪を何周しても同じ状態にするため)。
252
+ * - random は seed で決まるので、同じ選び方なら同じ流れになる(なぞれる)。
253
+ */
254
+ export async function explore(o: ExploreOptions): Promise<Exploration> {
255
+ const { start, runs: limit, signal, choice, begin, ran, ...rest } = o;
256
+ const nodes = new Map<string, ExploreNode>();
257
+ const list: ExploreNode[] = [];
258
+ const states = new Set<string>();
259
+ /** 選択肢(場所と文)→ 選んだ回数(すべての回の合計)。 */
260
+ const taken = new Map<string, number>();
261
+ const takenKey = (site: string, text: string) => `${site}\u0000${text}`;
262
+ const prefixOf = (w: Walk) => w.choices.map((c) => c.picked).join(",");
263
+ let plan: number[] = [];
264
+ let runs = 0;
265
+ while (runs < limit && !signal?.aborted) {
266
+ const index = runs++;
267
+ begin?.(index);
268
+ let merged = false;
269
+ const { result, walk: w } = await walk({
270
+ ...rest,
271
+ start,
272
+ choice: (at, options, w, targets) => {
273
+ if (choice?.(at, options, w, targets)) return true;
274
+ const prefix = prefixOf(w);
275
+ if (nodes.has(prefix)) return false;
276
+ // 初めて出た選択肢。前に通った状態なら、その先は前の回で試すので止める
277
+ const key = stateKey(w.runtime, at, options);
278
+ if (states.has(key)) {
279
+ merged = true;
280
+ return true;
281
+ }
282
+ states.add(key);
283
+ const node: ExploreNode = { prefix: w.choices.map((c) => c.picked), site: `${at.file}:${at.line}`, options, tried: options.map(() => false) };
284
+ nodes.set(prefix, node);
285
+ list.push(node);
286
+ return false;
287
+ },
288
+ pick: (at, options, w) => {
289
+ const i = w.choices.length;
290
+ const site = `${at.file}:${at.line}`;
291
+ let picked = 0;
292
+ if (i < plan.length) picked = Math.min(plan[i]!, options.length - 1);
293
+ else {
294
+ // その場所でまだ選ばれた数の少ないもの(同じなら上のもの)
295
+ let fewest = Infinity;
296
+ options.forEach((text, n) => {
297
+ const count = taken.get(takenKey(site, text)) ?? 0;
298
+ if (count < fewest) [fewest, picked] = [count, n];
299
+ });
300
+ }
301
+ const node = nodes.get(prefixOf(w));
302
+ if (node && picked < node.tried.length) node.tried[picked] = true;
303
+ const key = takenKey(site, options[picked] ?? "");
304
+ taken.set(key, (taken.get(key) ?? 0) + 1);
305
+ return picked;
306
+ },
307
+ });
308
+ await ran?.({ index, result, walk: w, merged });
309
+ // 次に試す組: まだ選ばれていない選択肢を先に、次に浅いものを先に
310
+ let next: { node: ExploreNode; n: number; count: number } | null = null;
311
+ for (const node of list) {
312
+ for (let n = 0; n < node.tried.length; n++) {
313
+ if (node.tried[n]) continue;
314
+ const count = taken.get(takenKey(node.site, node.options[n] ?? "")) ?? 0;
315
+ if (!next || count < next.count || (count === next.count && node.prefix.length < next.node.prefix.length)) next = { node, n, count };
316
+ }
317
+ }
318
+ if (!next) return { runs, complete: true };
319
+ plan = [...next.node.prefix, next.n];
320
+ }
321
+ return { runs, complete: false };
322
+ }
323
+
324
+ /** 状態の比べ合わせで、ラベルに入った回数と選んだ回数をこの回数までで区別する。 */
325
+ const COUNT_CAP = 2;
326
+
327
+ /**
328
+ * 選択肢を出す時点の状態の鍵。同じ鍵なら、その先の流れ(通る行、終わり方、実行時の診断)は同じになる。
329
+ * 場所、出した選択肢、呼び出しの戻り先、変数(game、system、temp、局所変数)、乱数の種、舞台(NVL の読んだ文は除く)、
330
+ * 取っておいた状態、ラベルに入った回数と選んだ回数(COUNT_CAP まで)を見る。本文の出し分けの進み(variants)は流れを変えないので見ない。
331
+ */
332
+ function stateKey(runtime: Runtime, at: { file: string; line: number }, options: string[]): string {
333
+ const s = runtime.save();
334
+ const place = (p: { unit: string; index: number }) => [p.unit, p.index];
335
+ const capped = (r: Record<string, number> | undefined) => (r ? Object.fromEntries(Object.entries(r).map(([k, v]) => [k, Math.min(v, COUNT_CAP)])) : null);
336
+ const { nvlPages: _pages, noclickPage: _noclick, ...stage } = s.stage;
337
+ return stableJson([
338
+ at.file,
339
+ at.line,
340
+ options,
341
+ place(s.position),
342
+ s.callStack.map((f) => [place(f.return), f.locals, f.result ?? null, f.content ?? null, f.scene ?? false]),
343
+ s.locals,
344
+ s.game,
345
+ s.seed,
346
+ capped(s.visits),
347
+ capped(s.chosen),
348
+ stage,
349
+ s.sleep ?? null,
350
+ s.checkpoints ?? null,
351
+ runtime.state.temp,
352
+ runtime.system,
353
+ ]);
354
+ }
355
+
356
+ /** キーの順によらない JSON(同じ変数を違う順に入れた状態を同じにする)。 */
357
+ function stableJson(v: unknown): string {
358
+ if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
359
+ if (Array.isArray(v)) return `[${v.map(stableJson).join(",")}]`;
360
+ const o = v as Record<string, unknown>;
361
+ const keys = Object.keys(o)
362
+ .filter((k) => o[k] !== undefined)
363
+ .sort();
364
+ return `{${keys.map((k) => `${JSON.stringify(k)}:${stableJson(o[k])}`).join(",")}}`;
365
+ }