ドキュメントをtsdocに移動、useRuntimeAllを追加しテストを修正

Author: na-trium-144

app/terminal/page.tsx

@@ -30,6 +30,7 @@ import {
 } from "@my-code/runtime/tests/utils";
 import { replTests } from "@my-code/runtime/tests/repl";
 import { fileExecutionTests } from "@my-code/runtime/tests/fileExecution";
+import { useRuntimeAll } from "@my-code/runtime/context";
 
 export default function RuntimeTestPage() {
   return (
@@ -206,21 +207,7 @@ function AnsiColorSample() {
 }
 
 function MochaTest() {
-  const pyodide = usePyodide();
-  const ruby = useRuby();
-  const jsEval = useJSEval();
-  const typescript = useTypeScript(jsEval);
-  const wandboxCpp = useWandbox("cpp");
-  const wandboxRust = useWandbox("rust");
-  const runtimeRef = useRef<Record<RuntimeLang, RuntimeContext>>(null!);
-  runtimeRef.current = {
-    python: pyodide,
-    ruby: ruby,
-    javascript: jsEval,
-    typescript: typescript,
-    cpp: wandboxCpp,
-    rust: wandboxRust,
-  };
+  const runtimeRef = useRuntimeAll();
 
   const [searchParams, setSearchParams] = useState<string>("");
   useEffect(() => {

app/terminal/terminal.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
+import { RefObject, useEffect, useRef, useState } from "react";
 import type { Terminal } from "@xterm/xterm";
 import type { FitAddon } from "@xterm/addon-fit";
 import "@xterm/xterm/css/xterm.css";
@@ -85,10 +85,33 @@ function computeTerminalTheme() {
 }
 
 interface TerminalProps {
+  /**
+   * ターミナルの幅がcolsの場合の高さの最小値を指定します。
+   * 未指定または5未満の場合5になります。
+   * 内部でuseRefを使用しターミナル初期化完了の瞬間のgetRows関数インスタンスが呼び出されるので、一時オブジェクトでも大丈夫
+   */
   getRows?: (cols: number) => number;
+  /**
+   * ターミナルが初期化された際に呼び出されます。
+   * 内部でuseRefを使用しターミナル初期化完了の瞬間のonReady関数インスタンスが呼び出されるので、一時オブジェクトでも大丈夫
+   */
   onReady?: () => void;
 }
-export function useTerminal(props: TerminalProps) {
+interface TerminalContext {
+  /**
+   * ターミナルを描画するためのdiv要素にこのrefを渡してください。
+   */
+  terminalRef: RefObject<HTMLDivElement>;
+  /**
+   * xterm.jsのTerminalインスタンスへのref
+   */
+  terminalInstanceRef: RefObject<Terminal | null>;
+  /**
+   * ターミナルが初期化されたかどうかを示します。
+   */
+  termReady: boolean;
+}
+export function useTerminal(props: TerminalProps): TerminalContext {
   const terminalRef = useRef<HTMLDivElement>(null!);
   const terminalInstanceRef = useRef<Terminal | null>(null);
   const fitAddonRef = useRef<FitAddon | null>(null);
@@ -110,7 +133,7 @@ export function useTerminal(props: TerminalProps) {
           const rows = Math.max(5, getRowsRef.current?.(dims.cols) ?? 0);
           terminalInstanceRef.current?.resize(dims.cols, rows);
         }
-      }
+      };
       /*
       globals.cssでフォントを指定し読み込んでいるが、
       それが読み込まれる前にterminalを初期化してしまうとバグるので、

packages/runtime/README.md

@@ -1,135 +1,28 @@
 # my.code(); Runtime API
 
-
 ## RuntimeContext (interface.ts)
 
-各言語のランタイムはRuntimeContextインターフェースの実装を返すフックを実装する必要があります。
-
-context.tsx の `useRuntime(lang)` は各言語のフックを呼び出し、その中で指定された言語のランタイムを返します。
-
-関数はすべてuseCallbackやuseMemoなどを用いレンダリングごとに同じインスタンスを返すように実装してください。
-
-### 共通
-
-* init?: `() => void`
-    * useRuntime() 内のuseEffectなどで呼び出されます。ランタイムを使う側では通常呼び出す必要はないです。
-    * ランタイムの初期化にコストがかかるものは、init()で初期化フラグがトリガーされたときだけ初期化するようにします。
-    * useRuntime() が複数回使われた場合はinitも複数回呼ばれます。
-        * init()はフラグを立てるだけにし、完了する前にreturnしてよいです。初期化とcleanupはuseEffect()で非同期に行うのがよいと思います。
-* ready: `boolean`
-    * ランタイムの初期化が完了したか、不要である場合true
-* mutex?: `MutexInterface`
-    * ランタイムに排他制御が必要な場合、MutexInterfaceのインスタンスを返してください。
-* interrupt?: `() => void`
-    * 実行中のコマンドを中断します。
-    * 呼び出し側でmutexのロックはしません。interrupt()を呼ぶ際にはrunCommand()やrunFiles()が実行中であるためmutexはすでにロックされているはずです。
-    * interrupt()内で実行中の処理のPromiseをrejectしたあと、runtimeを再開する際の処理に必要であればmutexをロックすることも可能です。
-
-### REPL用
-
-* runCommand?: `(command: string) => Promise<ReplOutput[]>`
-    * コマンドを実行します。実行結果をReplOutputの配列で返します。
-    * runCommandを呼び出す際には呼び出し側 (主に repl.tsx) でmutexをロックします。複数のコマンドを連続実行したい場合があるからです。
-* checkSyntax?: `(code: string) => Promise<SyntaxStatus>`
-    * コードの構文チェックを行います。行がコマンドとして完結していれば`complete`、次の行に続く場合(if文の条件式の途中など)は`incomplete`を返してください。
-    * REPLでEnterを押した際の動作に影響します。
-    * 呼び出し側でmutexのロックはせず、必要であればcheckSyntax()内でロックします。
-* splitReplExamples?: `(code: string) => ReplCommands[]`
-    * markdown内に記述されているREPLのサンプルコードをパースします。例えば
-    ```
-    >>> if True:
-    ...     print("Hello")
-    Hello
-    ```
-    をsplitReplExamplesに通すと
-    ```ts
-    [
-      {
-        command: 'if True:\n    print("Hello")',
-        output: {
-          type: 'output',
-          content: 'Hello'
-        }
-      }
-    ]
-    ```
-    が返されるようにします。
-
-### ファイル実行用
-
-* runFiles: `(filenames: string[], files: Record<string, string>) => Promise<ReplOutput[]>`
-    * 指定されたファイルを実行します。
-    * EmbedContextから取得したfilesを呼び出し側で引数に渡します
-    * 呼び出し側でmutexのロックはせず、必要であればrunFiles()内でロックします。
-* getCommandlineStr: `(filenames: string[]) => string`
-    * 指定されたファイルを実行するためのコマンドライン引数文字列を返します。表示用です。
-
-## languages.ts
-
-### LangConstant
-
-言語ごとに固定の定数です。
-
-* tabSize: `number`
-    * REPLおよびコードエディターののタブ幅を指定します。1以上
-* prompt?: `string`
-    * REPLの1行目のプロンプト文字列を指定します。
-* promptMore?: `string`
-    * REPLの2行目以降のプロンプト文字列を指定します。省略時はpromptが使われます
-
-## embedContext.tsx
-
-Replの実行結果(`replOutputs`)、ユーザーが編集したファイル(`files`)、ファイルの実行結果(`execResults`)の情報を保持します。
-
-## terminal.tsx
-
-xterm.jsを制御する useTerminal() フックを提供します。
-リサイズやテーマ切り替えなどの処理を行います。
-
-引数:
-* getRows?: `(cols: number) => number`
-    * ターミナルの幅がcolsの場合の高さの最小値を指定します。
-    * 未指定または5未満の場合5になります。
-    * 内部でuseRefを使用しターミナル初期化完了の瞬間のgetRows関数インスタンスが呼び出されるので、一時オブジェクトでも大丈夫
-* onReady?: `() => void`
-    * ターミナルが初期化された際に呼び出されます。
-    * 内部でuseRefを使用しターミナル初期化完了の瞬間のonReady関数インスタンスが呼び出されるので、一時オブジェクトでも大丈夫
-
-返り値:
-* terminalRef: `RefObject<HTMLDivElement>`
-    * ターミナルを描画するためのdiv要素にこのrefを渡してください。
-* terminalInstanceRef: `RefObject<Terminal | null>`
-    * xterm.jsのTerminalインスタンスへのrefです。
-* termReady: `boolean`
-    * ターミナルが初期化されたかどうかを示します。
+各言語の実行環境は`RuntimeContext`インターフェースの実装を返すフックを実装する必要があります。
 
-## repl.tsx
+## context.tsx
 
-ReplTerminal コンポーネントを提供します。
-useRuntimeとuseTerminalを呼び出し、REPLの入出力、キーハンドリング処理を行います。
+* RuntimeProvider がすべての言語の実行環境のコンテキストを管理します。
+* useRuntime() で使用したい言語のコンテキストを取得します。
+* useRuntimeAll() ですべての言語のコンテキストを取得します。ただしinit()は自動的に呼び出されません
 
-また、実行したコマンド結果はEmbedContextに送信されます。
-
-シンタックスハイライトはprism.jsでパースしたものを独自処理で色付けしています。(highlight.ts 内の highlightCodeToAnsi 関数)
-パース処理の実装は不要ですがhighlight.tsに言語定義のインポートとswitch文分岐の追加が必要です。
-
-## editor.tsx
-
-EditorComponent コンポーネントを提供します。
-
-ファイルの内容はEmbedContextと同期されます。
-
-## exec.tsx
-
-実行ボタンと結果を表示する ExecFile コンポーネントを提供します。
-
-実行結果はEmbedContextに送信されます。
+## languages.ts
 
-## page.tsx, tests.ts
+* markdownで指定される可能性のある言語名をすべて列挙します。
+* ReactAce, ReactSyntaxHighlighter, Prism.js における言語名との対応関係を定義します。
+* ReactAceで利用可能な言語の場合tab幅も指定します。
+* REPL実行環境が利用可能な言語の場合プロンプト文字列などのパラメータを指定します。
 
-ブラウザーで localhost:3000/terminal を開くと、各実行環境のテストを行います。
+## tests
 
-ランタイムを追加した場合、ここにテストケースを追加してください。
+* `npm run test -w packages/runtime` でvitestを使ってテストを実行できます
+* my.code(); の /terminal ページでMochaを使ってテストを実行できます
+* どちらからでも実行できるようテスト本体は ./tests/repl.ts, ./tests/fileExecution.ts に記述しています。
+新しい言語の実行環境を追加した場合、ここにテストケースを追加してください。
 
 ## 各言語の実装
 
@@ -138,24 +31,26 @@ EditorComponent コンポーネントを提供します。
 web worker でコードを実行する実装です。
 workerとの通信部分は言語によらず共通なので、それをworker/runtime.tsxで定義しています。
 
-Pythonの実行環境にはPyodideを使用しています。
-PyodideにはKeyboardInterruptを送信する機能があるのでinterrupt()でそれを利用しています。
-
-Rubyの実行環境にはruby.wasmを使用しています。
-
-JavaScriptはeval()を使用しています。
+* Python (Pyodide)
+    * PyodideにはKeyboardInterruptを送信する機能があるのでinterrupt()でそれを利用しています。
+    * next.config.tsで指定しているwebpackのPyodidePluginにより、pyodide本体は `/_next/static/pyodide/バージョン/` 以下に出力され、それをimportします。
+    * ただしvitest時には利用できないのでCDNにフォールバックしています
+* Ruby (ruby.wasm)
+* JavaScript (eval)
+    * 実装は複雑になるので別パッケージ (packages/jsEval) に分離し、独立したテストもそちらに記述しています
 
 ### Wandbox
 
 wandbox.org のAPIを利用してコードを実行します。
 
 APIから利用可能なコンパイラとオプションのリストが得られるので、言語ごとにそこからオプションを選択するロジックを実装しています。
 
-C++ではg++の中でheadでない最新のものを選択し、warningスイッチオン、boost有効、std=最新を指定しています。
-また、コード実行時にシグナルハンドラーをユーザーのコードに挿入し、エラー時にスタックトレースを表示する処理とそれをjs側でパースする処理を実装しています。
-
-Rustは最新のものを選択し、-Cdebuginfo=1を追加しています。
-ユーザーのコードをモジュールとしてprog.rsのmain()から呼び出す形に変更しており、ユーザーのコードに `mod foo;` → `use super::foo;`, `fn main()` → `pub fn main()` の改変を加えています。
+* C++
+    * g++の中でheadでない最新のものを選択し、warningスイッチオン、boost有効、std=最新を指定しています。
+    * また、コード実行時にシグナルハンドラーをユーザーのコードに挿入し、エラー時にスタックトレースを表示する処理とそれをjs側でパースする処理を実装しています。
+* Rust
+    * 最新のrustcを選択し、-Cdebuginfo=1を追加しています。
+    * ユーザーのコードをモジュールとしてprog.rsのmain()から呼び出す形に変更しており、ユーザーのコードに `mod foo;` → `use super::foo;`, `fn main()` → `pub fn main()` の改変を加えています。
 
 ### TypeScript
 

packages/runtime/src/context.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { ReactNode, useEffect } from "react";
+import { ReactNode, RefObject, useEffect, useRef } from "react";
 import { RuntimeContext } from "./interface";
 import { RuntimeLang } from "./languages";
 import { TypeScriptProvider, useTypeScript } from "./typescript/runtime";
@@ -11,6 +11,15 @@ import { RubyContext, useRuby } from "./worker/ruby";
 import { WorkerProvider } from "./worker/runtime";
 
 export function useRuntime(language: RuntimeLang): RuntimeContext {
+  const runtimes = useRuntimeAll();
+  const runtime = runtimes.current[language];
+  const { init } = runtime;
+  useEffect(() => {
+    init?.();
+  }, [init]);
+  return runtime;
+}
+export function useRuntimeAll(): RefObject<Record<RuntimeLang, RuntimeContext>> {
   // すべての言語のcontextをインスタンス化
   const pyodide = usePyodide();
   const ruby = useRuby();
@@ -19,35 +28,16 @@ export function useRuntime(language: RuntimeLang): RuntimeContext {
   const wandboxCpp = useWandbox("cpp");
   const wandboxRust = useWandbox("rust");
 
-  let runtime: RuntimeContext;
-  switch (language) {
-    case "python":
-      runtime = pyodide;
-      break;
-    case "ruby":
-      runtime = ruby;
-      break;
-    case "javascript":
-      runtime = jsEval;
-      break;
-    case "typescript":
-      runtime = typescript;
-      break;
-    case "cpp":
-      runtime = wandboxCpp;
-      break;
-    case "rust":
-      runtime = wandboxRust;
-      break;
-    default:
-      language satisfies never;
-      throw new Error(`Runtime not implemented for language: ${language}`);
-  }
-  const { init } = runtime;
-  useEffect(() => {
-    init?.();
-  }, [init]);
-  return runtime;
+  const runtimes = useRef<Record<RuntimeLang, RuntimeContext>>({} as never);
+  runtimes.current.python = pyodide;
+  runtimes.current.ruby = ruby;
+  runtimes.current.javascript = jsEval;
+  runtimes.current.typescript = typescript;
+  runtimes.current.cpp = wandboxCpp;
+  runtimes.current.rust = wandboxRust;
+
+  // initはしない。呼び出し側でする必要がある
+  return runtimes;
 }
 export function RuntimeProvider({ children }: { children: ReactNode }) {
   return (