Add scenario sanitization utilities and docs

Author: EndoHizumi

README.md

@@ -13,6 +13,7 @@
 - [動作確認手順](#動作確認手順)
 - [Quick Start(デモゲームを弄ってみよう)](#quick-startデモゲームを弄ってみよう)
 - [開発コマンド](#開発コマンド)
+- [シナリオ検証API](#シナリオ検証api)
 - [現在の状況](#現在の状況)
 - [ロードマップ](#ロードマップ実装予定)
 - [できること](#アルファ版01x-02xでできること)
@@ -185,6 +186,35 @@ npm run play
 - `npm run docs:build` - ドキュメントをビルド
 - `npm run docs:preview` - ビルドしたドキュメントをプレビュー
 
+## シナリオ検証API
+
+WebTaleKit には、シナリオ配列を検証しつつ、HTML風の文字列を非破壊でサニタイズできる公開APIがあります。
+
+- `validateScenarioObjects` - 検証結果とサニタイズ済みシナリオを返します
+- `formatValidationOutput` - エラーと警告を表示用文字列へ整形します
+- `createScenarioValidationError` - 検証結果から Error を生成します
+- `assertScenarioValidation` - エラーがある場合に例外を送出します
+- `reportScenarioValidation` - logger 経由で警告とエラーを出力します
+
+これらのAPIは、エンジン実行時に自動で強制適用されません。シナリオの読み込み時、エディタ連携時、独自ビルド処理時などに、利用者が必要に応じて呼び出す想定です。
+
+```ts
+import {
+  assertScenarioValidation,
+  reportScenarioValidation,
+  validateScenarioObjects,
+} from './src/utils/validateScenario'
+
+const result = validateScenarioObjects(scenarioObjects, commandList)
+
+await reportScenarioValidation(result, 'Scene import')
+assertScenarioValidation(result, 'Scene import')
+
+const safeScenario = result.sanitizedScenario
+```
+
+`sanitizedScenario` は元の入力配列を破壊せずに返されます。`sanitized` が `true` の場合は、HTML風の文字列がエスケープされています。
+
 ## 現在の状況
 
 webTaleKitは、現在アルファ版です。

README_EN.md

@@ -13,6 +13,7 @@
 - [Testing Instructions](#testing-instructions)
 - [Quick Start](#quick-start)
 - [Development Commands](#development-commands)
+- [Scenario Validation API](#scenario-validation-api)
 - [Current Status](#current-status)
 - [Roadmap](#roadmap)
 - [Features](#features-available-in-alpha-01x-02x)
@@ -185,6 +186,35 @@ Choices are important elements that let players control game progression. You ca
 - `npm run docs:build` - Build documentation
 - `npm run docs:preview` - Preview built documentation
 
+## Scenario Validation API
+
+webTaleKit provides a public API for validating scenario arrays and non-destructively sanitizing HTML-like string content.
+
+- `validateScenarioObjects` returns validation results and a sanitized scenario
+- `formatValidationOutput` converts errors and warnings into display-friendly strings
+- `createScenarioValidationError` builds an `Error` from validation results
+- `assertScenarioValidation` throws when validation errors exist
+- `reportScenarioValidation` sends warnings and errors through the logger
+
+These APIs are not automatically enforced by the engine at runtime. They are intended to be called explicitly by the user from scene import flows, editor integrations, custom build steps, or server-side tooling.
+
+```ts
+import {
+  assertScenarioValidation,
+  reportScenarioValidation,
+  validateScenarioObjects,
+} from './src/utils/validateScenario'
+
+const result = validateScenarioObjects(scenarioObjects, commandList)
+
+await reportScenarioValidation(result, 'Scene import')
+assertScenarioValidation(result, 'Scene import')
+
+const safeScenario = result.sanitizedScenario
+```
+
+`sanitizedScenario` is returned without mutating the original input array. When `sanitized` is `true`, HTML-like text has been escaped.
+
 ## Current Status
 
 webTaleKit is currently in alpha.

documents/manual.md

@@ -105,5 +105,30 @@
 
 4. `dist`ディレクトリの内容をWebサーバーにデプロイすることで、ゲームを公開できます。
 
+## シナリオ検証とサニタイズ
+
+WebTaleKit では、シナリオ配列に対して検証とサニタイズを行う公開APIを利用できます。
+
+- `validateScenarioObjects` は `valid`、`errors`、`warnings` に加えて `sanitizedScenario` を返します
+- `sanitizedScenario` は非破壊で生成されるため、元のシナリオ配列は変更されません
+- `reportScenarioValidation` を使うと、既存 logger に合わせた警告・エラー出力ができます
+- `assertScenarioValidation` を使うと、エラーがある場合に呼び出し側で停止できます
+
+この機能は公開APIであり、エンジン本体が自動で適用するわけではありません。ツール、エディタ、ビルド処理、サーバー側変換など、必要な場所で明示的に呼び出してください。
+
+```ts
+import {
+  reportScenarioValidation,
+  validateScenarioObjects,
+} from '../src/utils/validateScenario'
+
+const result = validateScenarioObjects(scenarioObjects, commandList)
+await reportScenarioValidation(result, 'Manual validation')
+
+if (result.valid) {
+  const scenarioForRuntime = result.sanitizedScenario
+}
+```
+
 以上がWebTaleKitを使ってビジュアルノベルゲームを作成するための基本的な流れです。
 タグの詳細については、[WebTaleKit仕様](documents/spec.md)を参照してください。

src/utils/validateScenario.test.ts

@@ -1,4 +1,11 @@
-import { validateScenarioObjects } from '../utils/validateScenario'
+import * as logger from '../utils/logger'
+import {
+  assertScenarioValidation,
+  createScenarioValidationError,
+  formatValidationOutput,
+  reportScenarioValidation,
+  validateScenarioObjects,
+} from '../utils/validateScenario'
 
 const mockCommandList: Record<string, Function> = {
   text: () => {},
@@ -29,6 +36,8 @@ describe('validateScenarioObjects', () => {
     expect(result.valid).toBe(true)
     expect(result.errors).toHaveLength(0)
     expect(result.warnings).toHaveLength(0)
+    expect(result.sanitizedScenario).toEqual(scenario)
+    expect(result.sanitized).toBe(false)
   })
 
   test('空配列で valid: false + error が返ること', () => {
@@ -80,9 +89,26 @@ describe('validateScenarioObjects', () => {
 
   test('HTMLタグを含むテキストがエスケープされること', () => {
     const scenario = [{ type: 'text', content: ['<script>alert("xss")</script>'] }]
-    validateScenarioObjects(scenario, mockCommandList)
-    expect(scenario[0].content[0]).not.toContain('<script>')
-    expect(scenario[0].content[0]).toContain('&lt;script&gt;')
+    const result = validateScenarioObjects(scenario, mockCommandList)
+    expect(scenario[0].content[0]).toContain('<script>')
+    expect(result.sanitizedScenario[0].content[0]).not.toContain('<script>')
+    expect(result.sanitizedScenario[0].content[0]).toContain('&lt;script&gt;')
+    expect(result.sanitized).toBe(true)
+  })
+
+  test('ネストしたオブジェクトも非破壊でサニタイズされること', () => {
+    const scenario = [
+      {
+        type: 'choice',
+        content: [{ type: 'item', label: '<b>危険</b>', content: ['<i>text</i>'] }],
+      },
+    ]
+
+    const result = validateScenarioObjects(scenario, mockCommandList)
+
+    expect(scenario[0].content[0].label).toBe('<b>危険</b>')
+    expect(result.sanitizedScenario[0].content[0].label).toBe('&lt;b&gt;危険&lt;/b&gt;')
+    expect(result.sanitizedScenario[0].content[0].content[0]).toBe('&lt;i&gt;text&lt;/i&gt;')
   })
 
   test('index が正常範囲内の jump で warning が出ないこと', () => {
@@ -94,4 +120,44 @@ describe('validateScenarioObjects', () => {
     const result = validateScenarioObjects(scenario, mockCommandList)
     expect(result.warnings.filter((w) => w.type === 'jump')).toHaveLength(0)
   })
+
+  test('formatValidationOutput が warnings と errors を整形すること', () => {
+    const result = validateScenarioObjects([{ type: 'say', content: ['hello'] }], mockCommandList)
+    const formatted = formatValidationOutput(result)
+
+    expect(formatted.errors).toHaveLength(0)
+    expect(formatted.warnings[0]).toContain('[index:0]')
+    expect(formatted.warnings[0]).toContain('<say>')
+  })
+
+  test('createScenarioValidationError が error をまとめた Error を返すこと', () => {
+    const result = validateScenarioObjects([{ type: 'choice', content: [] }], mockCommandList)
+    const error = createScenarioValidationError(result, 'Custom context')
+
+    expect(error).toBeInstanceOf(Error)
+    expect(error?.message).toContain('Custom context')
+    expect(error?.message).toContain('choice コマンドに item が含まれていません')
+  })
+
+  test('assertScenarioValidation が invalid 時に throw すること', () => {
+    const result = validateScenarioObjects([{ type: 'choice', content: [] }], mockCommandList)
+    expect(() => assertScenarioValidation(result)).toThrow(/Scenario validation failed/)
+  })
+
+  test('reportScenarioValidation が warning と error を logger に流すこと', async () => {
+    const outputLogSpy = jest.spyOn(logger, 'outputLog').mockResolvedValue()
+    const logErrorSpy = jest.spyOn(logger, 'logError').mockResolvedValue()
+    const result = validateScenarioObjects([
+      { type: 'say', content: ['hello'] },
+      { type: 'choice', content: [] },
+    ], mockCommandList)
+
+    await reportScenarioValidation(result, 'Validation test')
+
+    expect(outputLogSpy).toHaveBeenCalled()
+    expect(logErrorSpy).toHaveBeenCalled()
+
+    outputLogSpy.mockRestore()
+    logErrorSpy.mockRestore()
+  })
 })