opencroc 1.8.3 → 1.8.5

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 (6) hide show
  1. package/README.ja.md +383 -386
  2. package/README.md +383 -417
  3. package/README.zh-CN.md +383 -414
  4. package/dist/cli/index.js +24 -8
  5. package/dist/cli/index.js.map +1 -1
  6. package/package.json +1 -1
package/README.ja.md CHANGED
@@ -1,386 +1,383 @@
1
- <p align="center">
2
- <img src="assets/banner.png" alt="OpenCroc バナー" width="820" />
3
- </p>
4
-
5
- <h1 align="center">OpenCroc</h1>
6
-
7
- <p align="center">
8
- <strong>ソースコードを読み取り、テストを自動生成し、失敗を自己修復する AI ネイティブ E2E テストフレームワーク。</strong>
9
- </p>
10
-
11
- <p align="center">
12
- <a href="https://www.npmjs.com/package/opencroc"><img src="https://img.shields.io/npm/v/opencroc?color=green" alt="npm version" /></a>
13
- <a href="https://github.com/opencroc/opencroc/actions/workflows/ci.yml"><img src="https://github.com/opencroc/opencroc/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
14
- <a href="https://github.com/opencroc/opencroc/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opencroc/opencroc" alt="MIT License" /></a>
15
- <a href="https://opencroc.com"><img src="https://img.shields.io/badge/docs-opencroc.com-blue" alt="Documentation" /></a>
16
- </p>
17
-
18
- <p align="center">
19
- <a href="README.en.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a>
20
- </p>
21
-
22
- ---
23
-
24
- ## OpenCroc とは
25
-
26
- OpenCroc は [Playwright](https://playwright.dev) 上に構築された **AI ネイティブ E2E テストフレームワーク** です。手作業で大量のテストスクリプトを書く代わりに、OpenCroc は**バックエンドのソースコード**（モデル、コントローラー、DTO）を解析し、API チェーン、シードデータ、リクエストボディ、アサーションを含む E2E テストスイートを自動生成します。
27
-
28
- テストが失敗した場合、単なるエラー出力で終わりません。リクエストチェーン全体をたどって**根本原因を特定**し、**修正パッチを生成**し、**再実行で修正を検証**します。
29
-
30
- ### 主な機能
31
-
32
- | 機能 | 説明 |
33
- |---|---|
34
- | **ソースコード認識型テスト生成** | [ts-morph](https://ts-morph.com) で Sequelize/TypeORM モデル、Express/NestJS コントローラー、DTO デコレーターを解析し API 面を把握 |
35
- | **AI 駆動の設定生成** | LLM がリクエストテンプレート、シードデータ、パラメータマッピングを生成し、3層検証（schema -> semantic -> dry-run）で確認 |
36
- | **インテリジェントなチェーン計画** | API 依存 DAG を構築し、トポロジカルソートと貪欲最適化でテストチェーンを設計 |
37
- | **ログ駆動の完了判定** | `networkidle` を超えて、バックエンド実行ログ（`api_exec end`）で完了を検証 |
38
- | **失敗チェーンの原因追跡** | ネットワークエラー -> 遅延 API -> バックエンドログの順で追跡し根因特定 |
39
- | **制御された自己修復** | `backup -> AI patch -> dry-run -> apply -> re-run -> verify -> rollback` を安全ゲート付きで実行 |
40
- | **影響範囲分析** | 外部キー関係を BFS でたどり、影響範囲を可視化し Mermaid 図を生成 |
41
-
42
- ## クイックスタート
43
-
44
- ### 前提条件
45
-
46
- - Node.js >= 18
47
- - Express/NestJS + Sequelize/TypeORM を利用するバックエンドプロジェクト
48
-
49
- ### インストール
50
-
51
- ```bash
52
- npm install opencroc --save-dev
53
- ```
54
-
55
- ### 初期化
56
-
57
- ```bash
58
- npx opencroc init
59
- ```
60
-
61
- このコマンドで以下を実行します:
62
- 1. プロジェクト構成をスキャン
63
- 2. ORM とフレームワークを検出
64
- 3. `opencroc.config.ts` を初期生成
65
- 4. サンプルテストを生成
66
-
67
- ### テスト生成
68
-
69
- ```bash
70
- # 単一モジュールのテスト生成
71
- npx opencroc generate --module=knowledge-base
72
-
73
- # 全モジュールのテスト生成
74
- npx opencroc generate --all
75
-
76
- # ドライラン（ファイルを書き込まない）
77
- npx opencroc generate --all --dry-run
78
- ```
79
-
80
- ### テスト実行
81
-
82
- ```bash
83
- # 生成済みテストをすべて実行
84
- npx opencroc test
85
-
86
- # 特定モジュールのみ実行
87
- npx opencroc test --module=knowledge-base
88
-
89
- # 自己修復モードで実行
90
- npx opencroc test --self-heal
91
- ```
92
-
93
- ### AI 設定の検証
94
-
95
- ```bash
96
- # 生成設定を検証
97
- npx opencroc validate --all
98
-
99
- # AI 生成結果とベースラインを比較
100
- npx opencroc compare --baseline=report-a.json --current=report-b.json
101
- ```
102
-
103
- ### OpenCroc Studio の起動
104
-
105
- OpenCroc Studio は**ピクセルアート風ワニオフィス** + リアルタイム**ナレッジグラフ** UI です。ローカル Web サーバーとして起動し、プロジェクト構造・Agent ステータス・テスト結果を可視化します。
106
-
107
- ```bash
108
- # Studio を起動（http://localhost:8765 をブラウザで自動オープン）
109
- npx opencroc serve
110
-
111
- # カスタムポート
112
- npx opencroc serve --port 3000
113
-
114
- # ブラウザ自動オープンを無効化
115
- npx opencroc serve --no-open
116
-
117
- # ホスト指定（リモートアクセス用）
118
- npx opencroc serve --host 0.0.0.0 --port 8765
119
- ```
120
-
121
- Studio の機能：
122
- - **ナレッジグラフキャンバス** — モデル・コントローラー・API 関係のインタラクティブグラフ（ドラッグ、ズーム、ホバー）
123
- - **ピクセルワニオフィス** — 6 体の AI Agent（パーサー 🐊、アナライザー 🐊、テスター 🐊、ヒーラー 🐊、プランナー 🐊、レポーター 🐊）、リアルタイムステータスアニメーション付き
124
- - **リアルタイム WebSocket** — Agent ステータスとグラフ変更を即座にブラウザへ配信
125
- - **モジュールサイドバー** — 検出されたモジュールと Agent ステータスをひと目で確認
126
- - **REST API** — `GET /api/project`（グラフデータ）、`GET /api/agents`（Agent ステータス）、`POST /api/project/refresh`（再スキャン）
127
-
128
- ### フルパイプライン（ワンコマンド）
129
-
130
- ```bash
131
- # すべてを実行：generate → execute → analyze → heal → report
132
- npx opencroc run
133
-
134
- # オプション付き
135
- npx opencroc run --module=users --self-heal --report html,json
136
- ```
137
-
138
- ### CI/CD 統合
139
-
140
- ```bash
141
- # GitHub Actions ワークフローを生成
142
- npx opencroc ci --platform github
143
-
144
- # GitLab CI パイプラインを生成
145
- npx opencroc ci --platform gitlab --self-heal
146
- ```
147
-
148
- ### Dashboard とレポート
149
-
150
- ```bash
151
- # ビジュアル Dashboard を生成
152
- npx opencroc dashboard
153
-
154
- # 複数形式のレポートを生成
155
- npx opencroc report --format html,json,markdown
156
- ```
157
-
158
- ## アーキテクチャ
159
-
160
- ```
161
- ┌─────────────────────────────────────────────────────────────┐
162
- │ OpenCroc Studio (localhost:8765) │
163
- │ ピクセルワニオフィス + ナレッジグラフ + WebSocket │
164
- ├─────────────────────────────────────────────────────────────┤
165
- │ CLI / Orchestrator │
166
- ├──────────┬──────────┬──────────┬──────────┬─────────────────┤
167
- │ Source │ Chain │ Test │ Execution│ Self-Healing │
168
- │ Parser │ Planner │Generator │ Engine │ Engine │
169
- │ │ │ │ │ │
170
- │ ts-morph │ DAG + │ Template │Playwright│ AI Attribution │
171
- │ Model │ Topo │ + AI │ + Log │ + Controlled │
172
- │ Controller│ Sort + │ Config │ Driven │ Fix + Verify │
173
- │ DTO │ Greedy │ Merge │ Assert │ + Rollback │
174
- ├──────────┴──────────┴──────────┴──────────┴─────────────────┤
175
- │ Observation Bus (Network + Backend Logs) │
176
- ├──────────────────────────────────────────────────────────────┤
177
- │ Report Engine (HTML / JSON / Markdown) │
178
- └──────────────────────────────────────────────────────────────┘
179
- ```
180
-
181
- ### 6 段階パイプライン
182
-
183
- ```
184
- Source Scan -> ER Diagram -> API Analysis -> Chain Planning -> Test Generation -> Failure Analysis
185
- │ │ │ │ │ │
186
- ts-morph Mermaid Dependency Topological Playwright + Root Cause +
187
- parsing erDiagram DAG builder + greedy AI body/seed Impact map
188
- ```
189
-
190
- ## 仕組み
191
-
192
- ### 1. ソース解析
193
-
194
- OpenCroc は [ts-morph](https://ts-morph.com) を使ってバックエンドを静的解析します。
195
-
196
- - **Models**: Sequelize `Model.init()` / TypeORM `@Entity()` からテーブル名、列型、インデックス、外部キーを抽出
197
- - **Controllers**: Express `router.get/post/put/delete` からルート、HTTP メソッド、パスパラメータを抽出
198
- - **DTOs**: `@IsString()`、`@IsNumber()`、`@IsOptional()` からバリデーションルールを抽出
199
-
200
- ### 2. AI 設定生成
201
-
202
- 各モジュールごとに、OpenCroc は LLM（OpenAI / ZhiPu / OpenAI 互換 API）を呼び出して以下を生成します。
203
-
204
- - **リクエストボディテンプレート**: フィールド精度の高い POST/PUT ペイロード
205
- - **シードデータ**: 正しい API 順序を持つ `beforeAll` セットアップ
206
- - **パラメータマッピング**: パスパラメータ別名（`/:id` -> `categoryId`）
207
- - **ID エイリアス**: 複数リソースチェーンでの ID 衝突防止
208
-
209
- 各設定は **3 層検証** を通過します。
210
- 1. **Schema 検証**: JSON 構造の完全性
211
- 2. **Semantic 検証**: フィールド値がソースメタデータに一致するか
212
- 3. **Dry-run 検証**: TypeScript コンパイル確認
213
-
214
- 失敗した設定は書き込み前に自動修正（最大 3 ラウンド）されます。
215
-
216
- ### 3. ログ駆動の完了判定
217
-
218
- 壊れやすい `networkidle` に依存せず、以下で判定します。
219
-
220
- ```
221
- Frontend Request -> Backend api_exec start log -> Backend processing -> api_exec end log
222
- ↓
223
- OpenCroc polls end logs to confirm completion
224
- ```
225
-
226
- フロントが待機状態でもバックエンドが継続処理中のケースを検出できます。
227
-
228
- ### 4. 自己修復ループ
229
-
230
- ```
231
- Test Failure
232
- -> AI Attribution (LLM + heuristic fallback)
233
- -> Generate Fix Patch
234
- -> Dry-Run Validation
235
- -> Apply Patch (with backup)
236
- -> Re-run Failed Tests
237
- -> Verify Fix
238
- -> Commit or Rollback
239
- ```
240
-
241
- ## 実プロジェクト検証
242
-
243
- OpenCroc は**本番規模の RBAC システム**（マルチテナント企業権限管理）で検証済みです。100+ の Sequelize モデル、75+ の Express コントローラー、モデルファイル内埋め込みアソシエーションを含みます：
244
-
245
- ```
246
- $ npx tsx examples/rbac-system/smoke-test.ts
247
-
248
- Modules : 5 (default, aigc, data-platform, integration, workflow)
249
- ER Diagrams : 5
250
- [default] 102 tables, 65 relations
251
- [aigc] 6 tables, 0 relations
252
- [data-platform] 4 tables, 0 relations
253
- [integration] 14 tables, 0 relations
254
- [workflow] 2 tables, 0 relations
255
- Chain Plans : 5
256
- [aigc] 78 chains, 150 steps
257
- Generated Files: 78
258
- Duration : 1153ms
259
- ```
260
-
261
- 主な結果：
262
- - フラットモデルレイアウトから **102 テーブル** と **65 の外部キー関係** を正確に抽出
263
- - 専用の association ファイル不要 — モデルファイル内の**埋め込みアソシエーション**（`.belongsTo()` / `.hasMany()`）を検出
264
- - 5 モジュールで **78 テストファイル** を約1秒で生成
265
- - フラット（`models/*.ts`）とネスト（`models/module/*.ts`）の両ディレクトリ構造に対応
266
-
267
- ## 設定例
268
-
269
- ```typescript
270
- // opencroc.config.ts
271
- import { defineConfig } from 'opencroc';
272
-
273
- export default defineConfig({
274
- // バックエンドソースのパス
275
- backend: {
276
- modelsDir: 'src/models',
277
- controllersDir: 'src/controllers',
278
- servicesDir: 'src/services',
279
- },
280
-
281
- // 対象アプリケーション
282
- baseUrl: 'http://localhost:3000',
283
- apiBaseUrl: 'http://localhost:3000/api',
284
-
285
- // AI 設定
286
- ai: {
287
- provider: 'openai', // 'openai' | 'zhipu' | 'custom'
288
- apiKey: process.env.AI_API_KEY,
289
- model: 'gpt-4o-mini',
290
- },
291
-
292
- // テスト実行
293
- execution: {
294
- workers: 4,
295
- timeout: 30_000,
296
- retries: 1,
297
- },
298
-
299
- // ログ駆動完了判定（バックエンド側の計測が必要）
300
- logCompletion: {
301
- enabled: true,
302
- endpoint: '/internal/test-logs',
303
- pollIntervalMs: 500,
304
- timeoutMs: 10_000,
305
- },
306
-
307
- // 自己修復
308
- selfHealing: {
309
- enabled: false,
310
- fixScope: 'config-only', // 'config-only' | 'config-and-source'
311
- maxFixRounds: 3,
312
- dryRunFirst: true,
313
- },
314
- });
315
- ```
316
-
317
- ## 対応技術スタック
318
-
319
- | レイヤー | 対応済み | 予定 |
320
- |---|---|---|
321
- | **ORM** | Sequelize, TypeORM, Prisma, Drizzle | — |
322
- | **Framework** | Express | NestJS, Fastify, Koa |
323
- | **Test Runner** | Playwright | — |
324
- | **LLM** | OpenAI, ZhiPu (GLM), Ollama (local) | Anthropic |
325
- | **Database** | MySQL, PostgreSQL | SQLite, MongoDB |
326
-
327
- ## 比較
328
-
329
- | 機能 | OpenCroc | Playwright | Metersphere | auto-playwright |
330
- |---|---|---|---|---|
331
- | ソース認識生成 | ✅ | ❌ | ❌ | ❌ |
332
- | AI 設定生成 + 検証 | ✅ | ❌ | ❌ | ❌ |
333
- | ログ駆動完了判定 | ✅ | ❌ | ❌ | ❌ |
334
- | 失敗チェーン帰属分析 | ✅ | ❌ | Partial | ❌ |
335
- | 自己修復 + ロールバック | ✅ | ❌ | ❌ | ❌ |
336
- | API 依存 DAG | ✅ | ❌ | ❌ | ❌ |
337
- | ゼロ設定テスト生成 | ✅ | Codegen only | Manual | NL->action |
338
- | 影響範囲分析 | ✅ | ❌ | ❌ | ❌ |
339
-
340
- ## Roadmap
341
-
342
- - [x] 6-stage source-to-test pipeline
343
- - [x] AI configuration generation with 3-layer validation
344
- - [x] Controlled self-healing loop
345
- - [x] Log-driven completion detection
346
- - [x] Failure chain attribution + impact analysis
347
- - [x] TypeORM / Prisma adapter
348
- - [x] Ollama local LLM support
349
- - [x] Real-world validation (102 tables, 65 relations, 78 generated tests)
350
- - [x] GitHub Actions / GitLab CI integration
351
- - [x] VS Code extension scaffold
352
- - [x] Plugin system
353
- - [x] HTML / JSON / Markdown report generation
354
- - [x] NestJS controller parser
355
- - [x] Visual dashboard (opencroc.com)
356
- - [x] Drizzle ORM adapter
357
- - [x] AI Config Suggester + Enhanced DTO-aware Suggester
358
- - [x] Auto-Fixer (4 strategies: interface-path, DTO field, seed dependency, param mapping)
359
- - [x] 3-layer config validation (schema → semantic → dry-run)
360
- - [x] DTO Parser (ts-morph interface + express-validator extraction)
361
- - [x] Baseline Comparator (Playwright report diff + regression detection)
362
- - [x] Module config preset loader
363
- - [x] LLM-enhanced chain planner
364
- - [x] Runtime infrastructure (Playwright config, auth setup, teardown, network monitor)
365
- - [x] Full orchestration pipeline
366
- - [x] Advanced reporters (checklist, workorder, token tracking)
367
- - [x] OpenCroc Studio — ピクセルワニオフィス + ナレッジグラフ UI（`opencroc serve`）
368
-
369
- ## ドキュメント
370
-
371
- 詳細は **[opencroc.com](https://opencroc.com)** を参照してください。あわせて以下も確認できます。
372
-
373
- - [Architecture Guide](docs/architecture.md)
374
- - [Configuration Reference](docs/configuration.md)
375
- - [Backend Instrumentation Guide](docs/backend-instrumentation.md)
376
- - [AI Provider Setup](docs/ai-providers.md)
377
- - [Self-Healing Guide](docs/self-healing.md)
378
- - [Troubleshooting](docs/troubleshooting.md)
379
-
380
- ## コントリビュート
381
-
382
- 貢献を歓迎します。ガイドラインは [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
383
-
384
- ## ライセンス
385
-
386
- [MIT](LICENSE) © 2026 OpenCroc Contributors
1
+ <p align="center">
2
+ <img src="assets/banner.png" alt="OpenCroc バナー" width="820" />
3
+ </p>
4
+
5
+ <h1 align="center">OpenCroc</h1>
6
+
7
+ <p align="center">
8
+ <strong>ソースコードを読み取り、テストを生成し、失敗を自己修復する AI ネイティブな E2E テストフレームワーク。</strong>
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/opencroc"><img src="https://img.shields.io/npm/v/opencroc?color=green" alt="npm version" /></a>
13
+ <a href="https://github.com/opencroc/opencroc/actions/workflows/ci.yml"><img src="https://github.com/opencroc/opencroc/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
14
+ <a href="https://github.com/opencroc/opencroc/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opencroc/opencroc" alt="MIT License" /></a>
15
+ <a href="https://opencroc.com"><img src="https://img.shields.io/badge/docs-opencroc.com-blue" alt="Documentation" /></a>
16
+ </p>
17
+
18
+ <p align="center">
19
+ <a href="README.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a>
20
+ </p>
21
+
22
+ ---
23
+
24
+ ## OpenCroc とは
25
+
26
+ OpenCroc は [Playwright](https://playwright.dev) を土台にした AI ネイティブなエンドツーエンドテストフレームワークです。大量のテストスクリプトを手書きする代わりに、OpenCroc はバックエンドのソースコードを読み取り、モデル、コントローラ、DTO、関連を理解したうえで、シードデータ、リクエストボディ、API チェーン、アサーションを含む E2E スイートを自動生成します。
27
+
28
+ テストが失敗した場合も、単にエラーを表示するだけではありません。リクエストチェーンを横断して原因を追跡し、根本原因の候補を整理し、修正案を生成し、制御されたフローの中で再検証できます。
29
+
30
+ ## 主な機能
31
+
32
+ | 機能 | 説明 |
33
+ | --- | --- |
34
+ | ソースコード認識型生成 | Sequelize、TypeORM、Prisma、Drizzle の構造を解析し、モジュール、モデル、ルート、DTO を把握 |
35
+ | AI 設定生成 | リクエストテンプレート、シード計画、パラメータマッピング、テスト雛形を生成し、検証ゲートを通過 |
36
+ | チェーン計画 | 依存 DAG を構築し、より高い API カバレッジの実行順を計画 |
37
+ | ログ駆動完了判定 | `networkidle` だけに頼らず、バックエンドの完了シグナルでも判定 |
38
+ | 失敗の帰属分析 | フロントの要求、バックエンドログ、依存チェーンを結びつけて原因を追跡 |
39
+ | 制御された自己修復 | backup、patch、dry-run、re-run、verify、rollback のループを提供 |
40
+ | 可視化 Studio | グラフ探索、Agent 状態確認、ピクセルオフィス表示のためのローカル Web UI を提供 |
41
+
42
+ ## クイックスタート
43
+
44
+ ### 前提条件
45
+
46
+ - Node.js 18 以上
47
+ - Express または NestJS を使うバックエンドプロジェクト
48
+ - サポート対象の ORM またはスキーマ構造
49
+
50
+ ### インストール
51
+
52
+ ```bash
53
+ npm install opencroc --save-dev
54
+ ```
55
+
56
+ ### 初期化
57
+
58
+ ```bash
59
+ npx opencroc init
60
+ ```
61
+
62
+ このコマンドは次を実行します。
63
+
64
+ 1. プロジェクト構造のスキャン
65
+ 2. フレームワークと ORM パターンの検出
66
+ 3. `opencroc.config.ts` の生成
67
+ 4. 初期出力構成の生成
68
+
69
+ ### テスト生成
70
+
71
+ ```bash
72
+ # 単一モジュールのテスト生成
73
+ npx opencroc generate --module=knowledge-base
74
+
75
+ # すべての検出モジュールのテスト生成
76
+ npx opencroc generate --all
77
+
78
+ # 書き込みなしのプレビュー
79
+ npx opencroc generate --all --dry-run
80
+ ```
81
+
82
+ ### テスト実行
83
+
84
+ ```bash
85
+ # 生成済みテストをすべて実行
86
+ npx opencroc test
87
+
88
+ # 単一モジュールのみ実行
89
+ npx opencroc test --module=knowledge-base
90
+
91
+ # headed モードで実行
92
+ npx opencroc test --headed
93
+
94
+ # CLI からフックを上書き
95
+ npx opencroc test --setup-hook="npm run e2e:setup" --auth-hook="node scripts/auth.js" --teardown-hook="npm run e2e:cleanup"
96
+ ```
97
+
98
+ ### AI 設定の検証
99
+
100
+ ```bash
101
+ npx opencroc validate --all
102
+ npx opencroc compare --baseline=report-a.json --current=report-b.json
103
+ ```
104
+
105
+ ## OpenCroc Studio
106
+
107
+ OpenCroc Studio は OpenCroc のローカル可視化ワークスペースです。知識グラフ、ピクセルオフィス運用ビュー、3D オフィスランタイムを、CLI から起動する 1 つの Web 体験にまとめています。
108
+
109
+ ### Studio の起動
110
+
111
+ ```bash
112
+ # Studio を起動し、ブラウザを開く
113
+ npx opencroc serve
114
+
115
+ # カスタムポート
116
+ npx opencroc serve --port 3000
117
+
118
+ # ブラウザ自動起動を無効化
119
+ npx opencroc serve --no-open
120
+
121
+ # 公開 host にバインド
122
+ npx opencroc serve --host 0.0.0.0 --port 8765
123
+ ```
124
+
125
+ ### 現在の Web アーキテクチャ
126
+
127
+ - Fastify がローカル Studio アプリと API を配信
128
+ - フロントエンドは単一エントリの Vite SPA
129
+ - 主要ルートは `/`、`/studio`、`/pixel`
130
+ - Web ソースは `src/web` 配下で `app`、`pages`、`features`、`shared`、`styles`、`public` に整理
131
+ - 旧 URL である `/index-studio.html` と `/index-v2-pixel.html` は SPA ルートへリダイレクト
132
+
133
+ ### Studio の機能
134
+
135
+ - モジュール、API、関連を可視化する知識グラフキャンバス
136
+ - Agent の稼働状況を見せるピクセルオフィスダッシュボード
137
+ - 没入感のある監視用 3D オフィスランタイムビュー
138
+ - WebSocket によるリアルタイム更新
139
+ - ルート切替対応のサイドナビゲーション
140
+ - `GET /api/project`、`GET /api/agents`、`POST /api/project/refresh` などの REST API
141
+
142
+ ## フルパイプライン
143
+
144
+ ```bash
145
+ # フルパイプラインを実行
146
+ npx opencroc run
147
+
148
+ # 単一モジュールに自己修復とレポートを付けて実行
149
+ npx opencroc run --module=users --self-heal --report html,json
150
+ ```
151
+
152
+ ## CI/CD 統合
153
+
154
+ ```bash
155
+ npx opencroc ci --platform github
156
+ npx opencroc ci --platform gitlab --self-heal
157
+ ```
158
+
159
+ ## ダッシュボードとレポート
160
+
161
+ ```bash
162
+ npx opencroc dashboard
163
+ npx opencroc report --format html,json,markdown
164
+ ```
165
+
166
+ ## アーキテクチャ
167
+
168
+ ```text
169
+ +-------------------------------------------------------------------+
170
+ | OpenCroc Studio |
171
+ | Fastify サーバー + 単一エントリ Vite SPA + WebSocket 更新 |
172
+ | ルート: /, /studio, /pixel |
173
+ +-------------------------------------------------------------------+
174
+ | CLI / Orchestrator |
175
+ +--------------+--------------+---------------+----------------------+
176
+ | ソース解析 | チェーン計画 | テスト生成 | 実行 / 観測 |
177
+ +--------------+--------------+---------------+----------------------+
178
+ | 自己修復 | 影響分析 | レポート | Dashboard / Studio |
179
+ +--------------+--------------+---------------+----------------------+
180
+ ```
181
+
182
+ ### 6 段階パイプライン
183
+
184
+ ```text
185
+ Source Scan -> ER Diagram -> API Analysis -> Chain Planning -> Test Generation -> Failure Analysis
186
+ ```
187
+
188
+ ## 仕組み
189
+
190
+ ### 1. ソース解析
191
+
192
+ OpenCroc は [ts-morph](https://ts-morph.com) とフレームワーク認識型パーサを使って次を解析します。
193
+
194
+ - モデルと関連
195
+ - コントローラとルート
196
+ - DTO フィールドとバリデーションルール
197
+ - モジュール境界と依存面
198
+
199
+ ### 2. AI 設定生成
200
+
201
+ 各モジュールに対して OpenCroc は次を生成できます。
202
+
203
+ - リクエストボディテンプレート
204
+ - シードデータ計画
205
+ - パラメータマッピング
206
+ - ID エイリアス規則
207
+
208
+ 各設定は以下の検証を通過します。
209
+
210
+ 1. Schema 検証
211
+ 2. Semantic 検証
212
+ 3. Dry-run 検証
213
+
214
+ ### 3. ログ駆動完了判定
215
+
216
+ ブラウザのアイドル状態だけに頼らず、バックエンドの完了シグナルも使ってリクエストが本当に終了したかを判定します。
217
+
218
+ ### 4. 自己修復ループ
219
+
220
+ ```text
221
+ Test Failure
222
+ -> Attribution
223
+ -> Proposed Fix
224
+ -> Dry-Run Validation
225
+ -> Apply Patch
226
+ -> Re-run
227
+ -> Verify
228
+ -> Rollback if needed
229
+ ```
230
+
231
+ ## 実プロジェクト検証
232
+
233
+ OpenCroc は 100 を超える Sequelize モデル、数十のコントローラ、埋め込み関連定義を含む本番スタイルの RBAC システムで検証されています。
234
+
235
+ ```bash
236
+ $ npx tsx examples/rbac-system/smoke-test.ts
237
+
238
+ Modules : 5
239
+ ER Diagrams : 5
240
+ Chain Plans : 5
241
+ Generated Files: 78
242
+ Duration : 1153ms
243
+ ```
244
+
245
+ 主な結果:
246
+
247
+ - フラットなモデル構成から 102 テーブルと 65 外部キー関連を抽出
248
+ - 専用 association ファイルなしで埋め込み関連を検出
249
+ - 5 モジュールに対して 78 テストファイルを生成
250
+ - フラット構成とネスト構成の両方に対応
251
+
252
+ ## 設定例
253
+
254
+ ```typescript
255
+ import { defineConfig } from 'opencroc';
256
+
257
+ export default defineConfig({
258
+ backend: {
259
+ modelsDir: 'src/models',
260
+ controllersDir: 'src/controllers',
261
+ servicesDir: 'src/services',
262
+ },
263
+
264
+ baseUrl: 'http://localhost:3000',
265
+ apiBaseUrl: 'http://localhost:3000/api',
266
+
267
+ ai: {
268
+ provider: 'openai',
269
+ apiKey: process.env.AI_API_KEY,
270
+ model: 'gpt-4o-mini',
271
+ },
272
+
273
+ execution: {
274
+ workers: 4,
275
+ timeout: 30_000,
276
+ retries: 1,
277
+ },
278
+
279
+ logCompletion: {
280
+ enabled: true,
281
+ endpoint: '/internal/test-logs',
282
+ pollIntervalMs: 500,
283
+ timeoutMs: 10_000,
284
+ },
285
+
286
+ selfHealing: {
287
+ enabled: false,
288
+ fixScope: 'config-only',
289
+ maxFixRounds: 3,
290
+ dryRunFirst: true,
291
+ },
292
+ });
293
+ ```
294
+
295
+ ## サポート技術スタック
296
+
297
+ | レイヤー | 対応済み | 今後 |
298
+ | --- | --- | --- |
299
+ | ORM | Sequelize, TypeORM, Prisma, Drizzle | 必要に応じて拡張 |
300
+ | Framework | Express | NestJS, Fastify, Koa |
301
+ | Test Runner | Playwright | 追加ランナー |
302
+ | LLM | OpenAI, ZhiPu, Ollama | Anthropic |
303
+ | Database | MySQL, PostgreSQL | SQLite, MongoDB |
304
+
305
+ ## 比較
306
+
307
+ | 機能 | OpenCroc | Playwright | Metersphere | auto-playwright |
308
+ | --- | --- | --- | --- | --- |
309
+ | ソース認識型生成 | Yes | No | No | No |
310
+ | AI 設定生成と検証 | Yes | No | No | No |
311
+ | ログ駆動完了判定 | Yes | No | No | No |
312
+ | 失敗帰属分析 | Yes | No | Partial | No |
313
+ | 自己修復とロールバック | Yes | No | No | No |
314
+ | API 依存 DAG | Yes | No | No | No |
315
+ | ゼロ設定テスト生成 | Yes | Limited | Manual | Prompt-driven |
316
+ | 影響分析 | Yes | No | No | No |
317
+
318
+ ## ロードマップ
319
+
320
+ - [x] 6 段階ソースからテストへのパイプライン
321
+ - [x] AI 設定生成と検証
322
+ - [x] 制御された自己修復ループ
323
+ - [x] ログ駆動完了判定
324
+ - [x] 失敗帰属分析と影響分析
325
+ - [x] Prisma と Drizzle への対応
326
+ - [x] Ollama ローカルモデル対応
327
+ - [x] CI 統合
328
+ - [x] VS Code 拡張スキャフォールド
329
+ - [x] プラグインシステム
330
+ - [x] HTML、JSON、Markdown レポート
331
+ - [x] 可視化 Studio ダッシュボード
332
+ - [x] Runtime 基盤
333
+ - [x] フルオーケストレーション
334
+ - [x] 高度なレポーター
335
+ - [x] OpenCroc Studio のルートベース Web アプリ化
336
+
337
+ ## リリーススナップショット
338
+
339
+ - この README が対象とする製品スナップショット: `1.8.3`
340
+ - Studio アーキテクチャスナップショット: Fastify + 単一エントリ Vite SPA + ルートベースビュー
341
+ - 主な Studio ルート: `/`、`/studio`、`/pixel`
342
+ - フルスイート品質ゲート: 41 テストファイル、414 テスト通過
343
+
344
+ ### バージョンの流れ
345
+
346
+ - `0.3.x`: プラグインシステム、CI テンプレート、レポーター、VS Code スキャフォールド
347
+ - `0.4.x`: NestJS コントローラパーサ
348
+ - `0.5.x`: Drizzle ORM アダプタ
349
+ - `0.6.x`: 可視化ダッシュボードと Windows Vitest 安定化
350
+ - `0.7.x - 0.9.x`: runtime 基盤、認証、ログ駆動検出、ルールエンジン
351
+ - `1.0.0`: フルオーケストレーション
352
+ - `1.1.0`: 高度な自己修復
353
+ - `1.2.0`: 高度なレポーターと移行作業
354
+ - `1.3.0`: OpenCroc Studio M1
355
+ - `1.8.3`: Vite SPA ルーティング、Web アーキテクチャ整理、配布パッケージ軽量化
356
+
357
+ ### リリース検証
358
+
359
+ ```bash
360
+ npm run lint
361
+ npm run typecheck
362
+ npm test
363
+ npm view opencroc version dist-tags --json
364
+ ```
365
+
366
+ ## ドキュメント
367
+
368
+ 詳細は **[opencroc.com](https://opencroc.com)** を参照してください。あわせて次も確認できます。
369
+
370
+ - [Architecture Guide](docs/architecture.md)
371
+ - [Configuration Reference](docs/configuration.md)
372
+ - [Backend Instrumentation Guide](docs/backend-instrumentation.md)
373
+ - [AI Provider Setup](docs/ai-providers.md)
374
+ - [Self-Healing Guide](docs/self-healing.md)
375
+ - [Troubleshooting](docs/troubleshooting.md)
376
+
377
+ ## コントリビュート
378
+
379
+ コントリビューションを歓迎します。詳細は [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
380
+
381
+ ## ライセンス
382
+
383
+ [MIT](LICENSE) Copyright 2026 OpenCroc Contributors