opencroc 0.1.6 → 0.1.7

package/README.en.md

@@ -0,0 +1,286 @@
+<p align="center">
+  <img src="assets/banner.png" alt="OpenCroc banner" width="820" />
+</p>
+
+<h1 align="center">OpenCroc</h1>
+
+<p align="center">
+  <strong>AI-native E2E testing framework that reads your source code, generates tests, and self-heals failures.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencroc"><img src="https://img.shields.io/npm/v/opencroc?color=green" alt="npm version" /></a>
+  <a href="https://github.com/opencroc/opencroc/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opencroc/opencroc" alt="MIT License" /></a>
+  <a href="https://opencroc.com"><img src="https://img.shields.io/badge/docs-opencroc.com-blue" alt="Documentation" /></a>
+</p>
+
+<p align="center">
+  <a href="README.en.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a>
+</p>
+
+---
+
+## What is OpenCroc?
+
+OpenCroc is an **AI-native end-to-end testing framework** built on top of [Playwright](https://playwright.dev). Instead of writing test scripts by hand, OpenCroc **reads your backend source code** (models, controllers, DTOs) and automatically generates complete E2E test suites, including API chains, seed data, request bodies, and assertions.
+
+When tests fail, OpenCroc does not just report errors. It **traces the root cause** through the full request chain, **generates fix patches**, and **re-runs tests to verify the fix** autonomously.
+
+### Key Capabilities
+
+| Capability | Description |
+|---|---|
+| **Source-Aware Test Generation** | Parses Sequelize/TypeORM models, Express/NestJS controllers, and DTO decorators via [ts-morph](https://ts-morph.com) to understand your API surface |
+| **AI-Driven Configuration** | LLM generates request body templates, seed data, parameter mappings, validated by 3-layer verification (schema -> semantic -> dry-run) |
+| **Intelligent Chain Planning** | Builds API dependency DAGs, performs topological sorting, and plans test chains with greedy coverage optimization |
+| **Log-Driven Completion Detection** | Goes beyond `networkidle`; verifies request completion by matching backend execution logs (`api_exec end`) |
+| **Failure Chain Attribution** | Traces failures through the full call chain: network errors -> slow APIs -> backend logs -> root cause |
+| **Controlled Self-Healing** | `backup -> AI patch -> dry-run -> apply -> re-run -> verify -> rollback`, with safety gates at every step |
+| **Impact Analysis** | BFS traversal of foreign key relations to map blast radius and auto-generate Mermaid diagrams |
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js >= 18
+- A backend project with Express/NestJS + Sequelize/TypeORM
+
+### Installation
+
+```bash
+npm install opencroc --save-dev
+```
+
+### Initialize
+
+```bash
+npx opencroc init
+```
+
+This will:
+1. Scan your project structure
+2. Detect your ORM and framework
+3. Create `opencroc.config.ts` with sensible defaults
+4. Generate a sample test suite
+
+### Generate Tests
+
+```bash
+# Generate tests for a single module
+npx opencroc generate --module=knowledge-base
+
+# Generate tests for all detected modules
+npx opencroc generate --all
+
+# Dry-run (preview without writing files)
+npx opencroc generate --all --dry-run
+```
+
+### Run Tests
+
+```bash
+# Run all generated tests
+npx opencroc test
+
+# Run specific module
+npx opencroc test --module=knowledge-base
+
+# Run with self-healing enabled
+npx opencroc test --self-heal
+```
+
+### Validate AI Configs
+
+```bash
+# Validate generated configurations
+npx opencroc validate --all
+
+# Compare AI-generated vs baseline results
+npx opencroc compare --baseline=report-a.json --current=report-b.json
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     CLI / Orchestrator                       │
+├──────────┬──────────┬──────────┬──────────┬─────────────────┤
+│  Source   │  Chain   │  Test    │ Execution│   Self-Healing  │
+│  Parser   │ Planner  │Generator │  Engine  │     Engine      │
+│           │          │          │          │                 │
+│ ts-morph  │ DAG +    │ Template │Playwright│ AI Attribution  │
+│ Model     │ Topo     │ + AI     │ + Log    │ + Controlled    │
+│ Controller│ Sort +   │ Config   │ Driven   │ Fix + Verify    │
+│ DTO       │ Greedy   │ Merge    │ Assert   │ + Rollback      │
+├──────────┴──────────┴──────────┴──────────┴─────────────────┤
+│              Observation Bus (Network + Backend Logs)         │
+├──────────────────────────────────────────────────────────────┤
+│              Report Engine (HTML / JSON / Markdown)           │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 6-Stage Pipeline
+
+```
+Source Scan -> ER Diagram -> API Analysis -> Chain Planning -> Test Generation -> Failure Analysis
+     │            │             │              │                │                  │
+  ts-morph    Mermaid      Dependency       Topological     Playwright +      Root Cause +
+  parsing     erDiagram    DAG builder      + greedy        AI body/seed      Impact map
+```
+
+## How It Works
+
+### 1. Source Parsing
+
+OpenCroc uses [ts-morph](https://ts-morph.com) to statically analyze your backend:
+
+- **Models**: Extracts table names, column types, indexes, and foreign keys from Sequelize `Model.init()` / TypeORM `@Entity()`
+- **Controllers**: Extracts routes, HTTP methods, and path parameters from Express `router.get/post/put/delete`
+- **DTOs**: Extracts validation rules from `@IsString()`, `@IsNumber()`, `@IsOptional()` decorators
+
+### 2. AI Configuration Generation
+
+For each module, OpenCroc calls an LLM (OpenAI / ZhiPu / any OpenAI-compatible API) to generate:
+
+- **Request body templates**: Field-accurate POST/PUT payloads
+- **Seed data**: `beforeAll` setup steps with correct API sequences
+- **Parameter mappings**: Path parameter aliases (`/:id` -> `categoryId`)
+- **ID aliases**: Preventing ID conflicts across multi-resource chains
+
+Each config is validated through **3 layers**:
+1. **Schema validation**: JSON structure completeness
+2. **Semantic validation**: Field values match source code metadata
+3. **Dry-run validation**: TypeScript compilation check
+
+Failed configs are automatically fixed (up to 3 rounds) before being written.
+
+### 3. Log-Driven Completion
+
+Instead of relying on fragile `networkidle` signals:
+
+```
+Frontend Request -> Backend api_exec start log -> Backend processing -> api_exec end log
+                                                                          ↓
+                                              OpenCroc polls end logs to confirm completion
+```
+
+This catches cases where the frontend appears idle but the backend is still processing.
+
+### 4. Self-Healing Loop
+
+```
+Test Failure
+  -> AI Attribution (LLM + heuristic fallback)
+  -> Generate Fix Patch
+  -> Dry-Run Validation
+  -> Apply Patch (with backup)
+  -> Re-run Failed Tests
+  -> Verify Fix
+  -> Commit or Rollback
+```
+
+## Configuration
+
+```typescript
+// opencroc.config.ts
+import { defineConfig } from 'opencroc';
+
+export default defineConfig({
+  // Backend source paths
+  backend: {
+    modelsDir: 'src/models',
+    controllersDir: 'src/controllers',
+    servicesDir: 'src/services',
+  },
+
+  // Target application
+  baseUrl: 'http://localhost:3000',
+  apiBaseUrl: 'http://localhost:3000/api',
+
+  // AI configuration
+  ai: {
+    provider: 'openai',        // 'openai' | 'zhipu' | 'custom'
+    apiKey: process.env.AI_API_KEY,
+    model: 'gpt-4o-mini',
+  },
+
+  // Test execution
+  execution: {
+    workers: 4,
+    timeout: 30_000,
+    retries: 1,
+  },
+
+  // Log-driven completion (requires backend instrumentation)
+  logCompletion: {
+    enabled: true,
+    endpoint: '/internal/test-logs',
+    pollIntervalMs: 500,
+    timeoutMs: 10_000,
+  },
+
+  // Self-healing
+  selfHealing: {
+    enabled: false,
+    fixScope: 'config-only',   // 'config-only' | 'config-and-source'
+    maxFixRounds: 3,
+    dryRunFirst: true,
+  },
+});
+```
+
+## Supported Tech Stacks
+
+| Layer | Supported | Planned |
+|---|---|---|
+| **ORM** | Sequelize | TypeORM, Prisma, Drizzle |
+| **Framework** | Express | NestJS, Fastify, Koa |
+| **Test Runner** | Playwright | — |
+| **LLM** | OpenAI, ZhiPu (GLM) | Anthropic, Ollama (local) |
+| **Database** | MySQL, PostgreSQL | SQLite, MongoDB |
+
+## Comparison
+
+| Feature | OpenCroc | Playwright | Metersphere | auto-playwright |
+|---|---|---|---|---|
+| Source-aware generation | ✅ | ❌ | ❌ | ❌ |
+| AI config generation + validation | ✅ | ❌ | ❌ | ❌ |
+| Log-driven completion | ✅ | ❌ | ❌ | ❌ |
+| Failure chain attribution | ✅ | ❌ | Partial | ❌ |
+| Self-healing with rollback | ✅ | ❌ | ❌ | ❌ |
+| API dependency DAG | ✅ | ❌ | ❌ | ❌ |
+| Zero-config test generation | ✅ | Codegen only | Manual | NL->action |
+| Impact blast radius analysis | ✅ | ❌ | ❌ | ❌ |
+
+## Roadmap
+
+- [x] 6-stage source-to-test pipeline
+- [x] AI configuration generation with 3-layer validation
+- [x] Controlled self-healing loop
+- [x] Log-driven completion detection
+- [x] Failure chain attribution + impact analysis
+- [ ] TypeORM / Prisma adapter
+- [ ] NestJS controller parser
+- [ ] Visual dashboard (opencroc.com)
+- [ ] GitHub Actions integration
+- [ ] VS Code extension
+- [ ] Ollama local LLM support
+
+## Documentation
+
+Visit **[opencroc.com](https://opencroc.com)** for full documentation, or browse:
+
+- [Architecture Guide](docs/architecture.md)
+- [Configuration Reference](docs/configuration.md)
+- [Backend Instrumentation Guide](docs/backend-instrumentation.md)
+- [AI Provider Setup](docs/ai-providers.md)
+- [Self-Healing Guide](docs/self-healing.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+## Contributing
+
+We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[MIT](LICENSE) © 2026 OpenCroc Contributors

package/README.ja.md

@@ -0,0 +1,286 @@
+<p align="center">
+  <img src="assets/banner.png" alt="OpenCroc バナー" width="820" />
+</p>
+
+<h1 align="center">OpenCroc</h1>
+
+<p align="center">
+  <strong>ソースコードを読み取り、テストを自動生成し、失敗を自己修復する AI ネイティブ E2E テストフレームワーク。</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencroc"><img src="https://img.shields.io/npm/v/opencroc?color=green" alt="npm version" /></a>
+  <a href="https://github.com/opencroc/opencroc/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opencroc/opencroc" alt="MIT License" /></a>
+  <a href="https://opencroc.com"><img src="https://img.shields.io/badge/docs-opencroc.com-blue" alt="Documentation" /></a>
+</p>
+
+<p align="center">
+  <a href="README.en.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a>
+</p>
+
+---
+
+## OpenCroc とは
+
+OpenCroc は [Playwright](https://playwright.dev) 上に構築された **AI ネイティブ E2E テストフレームワーク** です。手作業で大量のテストスクリプトを書く代わりに、OpenCroc は**バックエンドのソースコード**（モデル、コントローラー、DTO）を解析し、API チェーン、シードデータ、リクエストボディ、アサーションを含む E2E テストスイートを自動生成します。
+
+テストが失敗した場合、単なるエラー出力で終わりません。リクエストチェーン全体をたどって**根本原因を特定**し、**修正パッチを生成**し、**再実行で修正を検証**します。
+
+### 主な機能
+
+| 機能 | 説明 |
+|---|---|
+| **ソースコード認識型テスト生成** | [ts-morph](https://ts-morph.com) で Sequelize/TypeORM モデル、Express/NestJS コントローラー、DTO デコレーターを解析し API 面を把握 |
+| **AI 駆動の設定生成** | LLM がリクエストテンプレート、シードデータ、パラメータマッピングを生成し、3層検証（schema -> semantic -> dry-run）で確認 |
+| **インテリジェントなチェーン計画** | API 依存 DAG を構築し、トポロジカルソートと貪欲最適化でテストチェーンを設計 |
+| **ログ駆動の完了判定** | `networkidle` を超えて、バックエンド実行ログ（`api_exec end`）で完了を検証 |
+| **失敗チェーンの原因追跡** | ネットワークエラー -> 遅延 API -> バックエンドログの順で追跡し根因特定 |
+| **制御された自己修復** | `backup -> AI patch -> dry-run -> apply -> re-run -> verify -> rollback` を安全ゲート付きで実行 |
+| **影響範囲分析** | 外部キー関係を BFS でたどり、影響範囲を可視化し Mermaid 図を生成 |
+
+## クイックスタート
+
+### 前提条件
+
+- Node.js >= 18
+- Express/NestJS + Sequelize/TypeORM を利用するバックエンドプロジェクト
+
+### インストール
+
+```bash
+npm install opencroc --save-dev
+```
+
+### 初期化
+
+```bash
+npx opencroc init
+```
+
+このコマンドで以下を実行します:
+1. プロジェクト構成をスキャン
+2. ORM とフレームワークを検出
+3. `opencroc.config.ts` を初期生成
+4. サンプルテストを生成
+
+### テスト生成
+
+```bash
+# 単一モジュールのテスト生成
+npx opencroc generate --module=knowledge-base
+
+# 全モジュールのテスト生成
+npx opencroc generate --all
+
+# ドライラン（ファイルを書き込まない）
+npx opencroc generate --all --dry-run
+```
+
+### テスト実行
+
+```bash
+# 生成済みテストをすべて実行
+npx opencroc test
+
+# 特定モジュールのみ実行
+npx opencroc test --module=knowledge-base
+
+# 自己修復モードで実行
+npx opencroc test --self-heal
+```
+
+### AI 設定の検証
+
+```bash
+# 生成設定を検証
+npx opencroc validate --all
+
+# AI 生成結果とベースラインを比較
+npx opencroc compare --baseline=report-a.json --current=report-b.json
+```
+
+## アーキテクチャ
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     CLI / Orchestrator                       │
+├──────────┬──────────┬──────────┬──────────┬─────────────────┤
+│  Source   │  Chain   │  Test    │ Execution│   Self-Healing  │
+│  Parser   │ Planner  │Generator │  Engine  │     Engine      │
+│           │          │          │          │                 │
+│ ts-morph  │ DAG +    │ Template │Playwright│ AI Attribution  │
+│ Model     │ Topo     │ + AI     │ + Log    │ + Controlled    │
+│ Controller│ Sort +   │ Config   │ Driven   │ Fix + Verify    │
+│ DTO       │ Greedy   │ Merge    │ Assert   │ + Rollback      │
+├──────────┴──────────┴──────────┴──────────┴─────────────────┤
+│              Observation Bus (Network + Backend Logs)         │
+├──────────────────────────────────────────────────────────────┤
+│              Report Engine (HTML / JSON / Markdown)           │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 6 段階パイプライン
+
+```
+Source Scan -> ER Diagram -> API Analysis -> Chain Planning -> Test Generation -> Failure Analysis
+     │            │             │              │                │                  │
+  ts-morph    Mermaid      Dependency       Topological     Playwright +      Root Cause +
+  parsing     erDiagram    DAG builder      + greedy        AI body/seed      Impact map
+```
+
+## 仕組み
+
+### 1. ソース解析
+
+OpenCroc は [ts-morph](https://ts-morph.com) を使ってバックエンドを静的解析します。
+
+- **Models**: Sequelize `Model.init()` / TypeORM `@Entity()` からテーブル名、列型、インデックス、外部キーを抽出
+- **Controllers**: Express `router.get/post/put/delete` からルート、HTTP メソッド、パスパラメータを抽出
+- **DTOs**: `@IsString()`、`@IsNumber()`、`@IsOptional()` からバリデーションルールを抽出
+
+### 2. AI 設定生成
+
+各モジュールごとに、OpenCroc は LLM（OpenAI / ZhiPu / OpenAI 互換 API）を呼び出して以下を生成します。
+
+- **リクエストボディテンプレート**: フィールド精度の高い POST/PUT ペイロード
+- **シードデータ**: 正しい API 順序を持つ `beforeAll` セットアップ
+- **パラメータマッピング**: パスパラメータ別名（`/:id` -> `categoryId`）
+- **ID エイリアス**: 複数リソースチェーンでの ID 衝突防止
+
+各設定は **3 層検証** を通過します。
+1. **Schema 検証**: JSON 構造の完全性
+2. **Semantic 検証**: フィールド値がソースメタデータに一致するか
+3. **Dry-run 検証**: TypeScript コンパイル確認
+
+失敗した設定は書き込み前に自動修正（最大 3 ラウンド）されます。
+
+### 3. ログ駆動の完了判定
+
+壊れやすい `networkidle` に依存せず、以下で判定します。
+
+```
+Frontend Request -> Backend api_exec start log -> Backend processing -> api_exec end log
+                                                                          ↓
+                                              OpenCroc polls end logs to confirm completion
+```
+
+フロントが待機状態でもバックエンドが継続処理中のケースを検出できます。
+
+### 4. 自己修復ループ
+
+```
+Test Failure
+  -> AI Attribution (LLM + heuristic fallback)
+  -> Generate Fix Patch
+  -> Dry-Run Validation
+  -> Apply Patch (with backup)
+  -> Re-run Failed Tests
+  -> Verify Fix
+  -> Commit or Rollback
+```
+
+## 設定例
+
+```typescript
+// opencroc.config.ts
+import { defineConfig } from 'opencroc';
+
+export default defineConfig({
+  // バックエンドソースのパス
+  backend: {
+    modelsDir: 'src/models',
+    controllersDir: 'src/controllers',
+    servicesDir: 'src/services',
+  },
+
+  // 対象アプリケーション
+  baseUrl: 'http://localhost:3000',
+  apiBaseUrl: 'http://localhost:3000/api',
+
+  // AI 設定
+  ai: {
+    provider: 'openai',        // 'openai' | 'zhipu' | 'custom'
+    apiKey: process.env.AI_API_KEY,
+    model: 'gpt-4o-mini',
+  },
+
+  // テスト実行
+  execution: {
+    workers: 4,
+    timeout: 30_000,
+    retries: 1,
+  },
+
+  // ログ駆動完了判定（バックエンド側の計測が必要）
+  logCompletion: {
+    enabled: true,
+    endpoint: '/internal/test-logs',
+    pollIntervalMs: 500,
+    timeoutMs: 10_000,
+  },
+
+  // 自己修復
+  selfHealing: {
+    enabled: false,
+    fixScope: 'config-only',   // 'config-only' | 'config-and-source'
+    maxFixRounds: 3,
+    dryRunFirst: true,
+  },
+});
+```
+
+## 対応技術スタック
+
+| レイヤー | 対応済み | 予定 |
+|---|---|---|
+| **ORM** | Sequelize | TypeORM, Prisma, Drizzle |
+| **Framework** | Express | NestJS, Fastify, Koa |
+| **Test Runner** | Playwright | — |
+| **LLM** | OpenAI, ZhiPu (GLM) | Anthropic, Ollama (local) |
+| **Database** | MySQL, PostgreSQL | SQLite, MongoDB |
+
+## 比較
+
+| 機能 | OpenCroc | Playwright | Metersphere | auto-playwright |
+|---|---|---|---|---|
+| ソース認識生成 | ✅ | ❌ | ❌ | ❌ |
+| AI 設定生成 + 検証 | ✅ | ❌ | ❌ | ❌ |
+| ログ駆動完了判定 | ✅ | ❌ | ❌ | ❌ |
+| 失敗チェーン帰属分析 | ✅ | ❌ | Partial | ❌ |
+| 自己修復 + ロールバック | ✅ | ❌ | ❌ | ❌ |
+| API 依存 DAG | ✅ | ❌ | ❌ | ❌ |
+| ゼロ設定テスト生成 | ✅ | Codegen only | Manual | NL->action |
+| 影響範囲分析 | ✅ | ❌ | ❌ | ❌ |
+
+## Roadmap
+
+- [x] 6-stage source-to-test pipeline
+- [x] AI configuration generation with 3-layer validation
+- [x] Controlled self-healing loop
+- [x] Log-driven completion detection
+- [x] Failure chain attribution + impact analysis
+- [ ] TypeORM / Prisma adapter
+- [ ] NestJS controller parser
+- [ ] Visual dashboard (opencroc.com)
+- [ ] GitHub Actions integration
+- [ ] VS Code extension
+- [ ] Ollama local LLM support
+
+## ドキュメント
+
+詳細は **[opencroc.com](https://opencroc.com)** を参照してください。あわせて以下も確認できます。
+
+- [Architecture Guide](docs/architecture.md)
+- [Configuration Reference](docs/configuration.md)
+- [Backend Instrumentation Guide](docs/backend-instrumentation.md)
+- [AI Provider Setup](docs/ai-providers.md)
+- [Self-Healing Guide](docs/self-healing.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+## コントリビュート
+
+貢献を歓迎します。ガイドラインは [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
+
+## ライセンス
+
+[MIT](LICENSE) © 2026 OpenCroc Contributors

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/logo-placeholder.png" alt="OpenCroc" width="200" />
+  <img src="assets/banner.png" alt="OpenCroc banner" width="820" />
 </p>
 
 <h1 align="center">OpenCroc</h1>
@@ -14,6 +14,10 @@
   <a href="https://opencroc.com"><img src="https://img.shields.io/badge/docs-opencroc.com-blue" alt="Documentation" /></a>
 </p>
 
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a>
+</p>
+
 ---
 
 ## What is OpenCroc?

package/README.zh-CN.md

@@ -0,0 +1,286 @@
+<p align="center">
+  <img src="assets/banner.png" alt="OpenCroc 横幅" width="820" />
+</p>
+
+<h1 align="center">OpenCroc</h1>
+
+<p align="center">
+  <strong>AI 原生 E2E 测试框架：读取你的源码、自动生成测试、并可自愈失败。</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencroc"><img src="https://img.shields.io/npm/v/opencroc?color=green" alt="npm version" /></a>
+  <a href="https://github.com/opencroc/opencroc/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opencroc/opencroc" alt="MIT License" /></a>
+  <a href="https://opencroc.com"><img src="https://img.shields.io/badge/docs-opencroc.com-blue" alt="Documentation" /></a>
+</p>
+
+<p align="center">
+  <a href="README.en.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a>
+</p>
+
+---
+
+## OpenCroc 是什么？
+
+OpenCroc 是一个构建在 [Playwright](https://playwright.dev) 之上的 **AI 原生端到端测试框架**。你不需要手写大量脚本，OpenCroc 会**读取后端源码**（模型、控制器、DTO），并自动生成完整 E2E 测试套件，包括 API 调用链、种子数据、请求体与断言。
+
+当测试失败时，OpenCroc 不只是报错，而是会沿完整请求链路**定位根因**、**生成修复补丁**，并**自动回归验证**修复结果。
+
+### 核心能力
+
+| 能力 | 说明 |
+|---|---|
+| **源码感知测试生成** | 通过 [ts-morph](https://ts-morph.com) 解析 Sequelize/TypeORM 模型、Express/NestJS 控制器、DTO 装饰器，识别 API 面 |
+| **AI 配置生成** | 使用 LLM 生成请求模板、种子数据、参数映射，并通过三层校验（schema -> semantic -> dry-run） |
+| **智能调用链规划** | 构建 API 依赖 DAG，做拓扑排序并以贪心策略提升覆盖率 |
+| **日志驱动完成判定** | 超越 `networkidle`，通过后端日志（`api_exec end`）确认请求真正完成 |
+| **失败链路归因** | 从网络异常 -> 慢接口 -> 后端日志逐层追踪，定位根因 |
+| **可控自愈机制** | `backup -> AI patch -> dry-run -> apply -> re-run -> verify -> rollback`，每步有安全闸门 |
+| **影响面分析** | 基于外键关系做 BFS 传播分析，自动输出 Mermaid 图 |
+
+## 快速开始
+
+### 前置要求
+
+- Node.js >= 18
+- 使用 Express/NestJS + Sequelize/TypeORM 的后端项目
+
+### 安装
+
+```bash
+npm install opencroc --save-dev
+```
+
+### 初始化
+
+```bash
+npx opencroc init
+```
+
+该命令会：
+1. 扫描项目结构
+2. 识别 ORM 与后端框架
+3. 生成默认 `opencroc.config.ts`
+4. 生成一套示例测试
+
+### 生成测试
+
+```bash
+# 为单个模块生成测试
+npx opencroc generate --module=knowledge-base
+
+# 为所有模块生成测试
+npx opencroc generate --all
+
+# 仅预览，不落盘
+npx opencroc generate --all --dry-run
+```
+
+### 运行测试
+
+```bash
+# 运行全部生成的测试
+npx opencroc test
+
+# 运行指定模块
+npx opencroc test --module=knowledge-base
+
+# 启用自愈运行
+npx opencroc test --self-heal
+```
+
+### 校验 AI 配置
+
+```bash
+# 校验所有生成配置
+npx opencroc validate --all
+
+# 比较两份报告差异
+npx opencroc compare --baseline=report-a.json --current=report-b.json
+```
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     CLI / Orchestrator                       │
+├──────────┬──────────┬──────────┬──────────┬─────────────────┤
+│  Source   │  Chain   │  Test    │ Execution│   Self-Healing  │
+│  Parser   │ Planner  │Generator │  Engine  │     Engine      │
+│           │          │          │          │                 │
+│ ts-morph  │ DAG +    │ Template │Playwright│ AI Attribution  │
+│ Model     │ Topo     │ + AI     │ + Log    │ + Controlled    │
+│ Controller│ Sort +   │ Config   │ Driven   │ Fix + Verify    │
+│ DTO       │ Greedy   │ Merge    │ Assert   │ + Rollback      │
+├──────────┴──────────┴──────────┴──────────┴─────────────────┤
+│              Observation Bus (Network + Backend Logs)         │
+├──────────────────────────────────────────────────────────────┤
+│              Report Engine (HTML / JSON / Markdown)           │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 6 阶段流水线
+
+```
+Source Scan -> ER Diagram -> API Analysis -> Chain Planning -> Test Generation -> Failure Analysis
+     │            │             │              │                │                  │
+  ts-morph    Mermaid      Dependency       Topological     Playwright +      Root Cause +
+  parsing     erDiagram    DAG builder      + greedy        AI body/seed      Impact map
+```
+
+## 工作原理
+
+### 1. 源码解析
+
+OpenCroc 基于 [ts-morph](https://ts-morph.com) 做静态分析：
+
+- **Models**：从 Sequelize `Model.init()` / TypeORM `@Entity()` 提取表名、字段类型、索引、外键
+- **Controllers**：从 Express `router.get/post/put/delete` 提取路由、HTTP 方法、路径参数
+- **DTOs**：从 `@IsString()`、`@IsNumber()`、`@IsOptional()` 装饰器提取校验规则
+
+### 2. AI 配置生成
+
+每个模块都会调用 LLM（OpenAI / 智谱 / 任意 OpenAI 兼容 API）生成：
+
+- **请求体模板**：字段级精确的 POST/PUT payload
+- **种子数据**：`beforeAll` 的初始化步骤与正确调用顺序
+- **参数映射**：路径参数别名（`/:id` -> `categoryId`）
+- **ID 别名**：避免多资源链路中的 ID 冲突
+
+每份配置都要通过 **3 层校验**：
+1. **Schema 校验**：JSON 结构完整性
+2. **语义校验**：字段值是否与源码元数据一致
+3. **Dry-run 校验**：TypeScript 编译检查
+
+若校验失败，会在落盘前自动修复（最多 3 轮）。
+
+### 3. 日志驱动完成判定
+
+不依赖脆弱的 `networkidle`：
+
+```
+Frontend Request -> Backend api_exec start log -> Backend processing -> api_exec end log
+                                                                          ↓
+                                              OpenCroc polls end logs to confirm completion
+```
+
+这能覆盖“前端看起来空闲、后端仍在处理”的场景。
+
+### 4. 自愈闭环
+
+```
+Test Failure
+  -> AI Attribution (LLM + heuristic fallback)
+  -> Generate Fix Patch
+  -> Dry-Run Validation
+  -> Apply Patch (with backup)
+  -> Re-run Failed Tests
+  -> Verify Fix
+  -> Commit or Rollback
+```
+
+## 配置示例
+
+```typescript
+// opencroc.config.ts
+import { defineConfig } from 'opencroc';
+
+export default defineConfig({
+  // 后端源码路径
+  backend: {
+    modelsDir: 'src/models',
+    controllersDir: 'src/controllers',
+    servicesDir: 'src/services',
+  },
+
+  // 目标应用
+  baseUrl: 'http://localhost:3000',
+  apiBaseUrl: 'http://localhost:3000/api',
+
+  // AI 配置
+  ai: {
+    provider: 'openai',        // 'openai' | 'zhipu' | 'custom'
+    apiKey: process.env.AI_API_KEY,
+    model: 'gpt-4o-mini',
+  },
+
+  // 测试执行
+  execution: {
+    workers: 4,
+    timeout: 30_000,
+    retries: 1,
+  },
+
+  // 日志驱动完成判定（需后端埋点）
+  logCompletion: {
+    enabled: true,
+    endpoint: '/internal/test-logs',
+    pollIntervalMs: 500,
+    timeoutMs: 10_000,
+  },
+
+  // 自愈
+  selfHealing: {
+    enabled: false,
+    fixScope: 'config-only',   // 'config-only' | 'config-and-source'
+    maxFixRounds: 3,
+    dryRunFirst: true,
+  },
+});
+```
+
+## 支持的技术栈
+
+| 层级 | 已支持 | 规划中 |
+|---|---|---|
+| **ORM** | Sequelize | TypeORM, Prisma, Drizzle |
+| **Framework** | Express | NestJS, Fastify, Koa |
+| **Test Runner** | Playwright | — |
+| **LLM** | OpenAI, ZhiPu (GLM) | Anthropic, Ollama (local) |
+| **Database** | MySQL, PostgreSQL | SQLite, MongoDB |
+
+## 对比
+
+| 功能 | OpenCroc | Playwright | Metersphere | auto-playwright |
+|---|---|---|---|---|
+| 源码感知生成 | ✅ | ❌ | ❌ | ❌ |
+| AI 配置生成 + 校验 | ✅ | ❌ | ❌ | ❌ |
+| 日志驱动完成判定 | ✅ | ❌ | ❌ | ❌ |
+| 失败链路归因 | ✅ | ❌ | 部分 | ❌ |
+| 自愈 + 回滚 | ✅ | ❌ | ❌ | ❌ |
+| API 依赖 DAG | ✅ | ❌ | ❌ | ❌ |
+| 零配置测试生成 | ✅ | 仅 codegen | 手工 | NL->action |
+| 影响面分析 | ✅ | ❌ | ❌ | ❌ |
+
+## Roadmap
+
+- [x] 6-stage source-to-test pipeline
+- [x] AI configuration generation with 3-layer validation
+- [x] Controlled self-healing loop
+- [x] Log-driven completion detection
+- [x] Failure chain attribution + impact analysis
+- [ ] TypeORM / Prisma adapter
+- [ ] NestJS controller parser
+- [ ] Visual dashboard (opencroc.com)
+- [ ] GitHub Actions integration
+- [ ] VS Code extension
+- [ ] Ollama local LLM support
+
+## 文档
+
+访问 **[opencroc.com](https://opencroc.com)** 查看完整文档，或阅读：
+
+- [Architecture Guide](docs/architecture.md)
+- [Configuration Reference](docs/configuration.md)
+- [Backend Instrumentation Guide](docs/backend-instrumentation.md)
+- [AI Provider Setup](docs/ai-providers.md)
+- [Self-Healing Guide](docs/self-healing.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+## 贡献
+
+欢迎贡献代码与文档。请查看 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## License
+
+[MIT](LICENSE) © 2026 OpenCroc Contributors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencroc",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "AI-native E2E testing framework — source-aware test generation, intelligent validation, and self-healing",
   "keywords": [
     "e2e",
@@ -17,7 +17,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/opencroc/opencroc.git"
+    "url": "git+https://github.com/opencroc/opencroc.git"
   },
   "license": "MIT",
   "author": "OpenCroc Contributors",
@@ -25,7 +25,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "opencroc": "./dist/cli/index.js"
+    "opencroc": "dist/cli/index.js"
   },
   "files": [
     "dist",