cobol-java-v3/AGENTS.md

COBOL → Java/Spark 迁移验证平台 V3

AI 辅助的自动化测试工具，用于验证 COBOL 程序向 Java/Spark 迁移的正确性。支持非 DB（flat file）和 DB（EXEC SQL → gixsql + SQLite）两条平行管道。

核心命令

# 安装依赖
pip install lark pathlib pyyaml

# 运行非 DB 回归测试
python test-data/s15_coverage_verification.py

# 运行 DB 端到端测试
python test-data/s30_db_e2e.py

# 单程序运行（自动路由）
python -m cobol_testgen ../cobol-tna-system/src/KIN01INP.cbl

# 带 gcov 覆盖率的单程序运行
python -m cobol_testgen --gcov <cobol_src> runtime/

# 诊断脚本
python diagnose_db2.py          # DB 全流程
python diagnose_kind8dbrun.py   # DB 编译运行

架构

CLI (main.py)
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│                   编排层 (Orchestrator)                       │
│  orchestrator.py (非DB)    orchestrator_db.py (DB)          │
└─────────────────────────────────────────────────────────────┘
    │
    ├──┬──────────┬──────────┬──────────┬──────────┐
    ▼  ▼          ▼          ▼          ▼          ▼
cobol_testgen   runners   comparator  agents     hina/
(数据生成)     (编译运行)  (比对验证)   (LLM)    (分类)
    │
    ├── config/
    │
    └── report/

目录结构

cobol-java-v3/
├── cobol_testgen/           # 核心引擎 (~8000行)
│   ├── __init__.py          # 公开 API 入口
│   ├── models.py            # 共享数据模型 (零依赖)
│   ├── read.py              # INPUT: 预处理 + DATA DIVISION 解析
│   ├── core.py              # CORE: 分支树构建
│   ├── cond.py              # CONDITION: 条件解析 + MC/DC
│   ├── design.py            # DESIGN: 路径枚举 + 值生成
│   ├── coverage.py          # COVERAGE: 覆盖标记 + HTML 报告
│   ├── output.py            # OUTPUT: JSON 输出
│   └── to_sql.py            # SQL 辅助: WHERE 约束解析
├── runners/                 # 编译运行引擎
│   ├── cobol_runner.py      # GnuCOBOL 编译运行
│   └── gixsql_runner.py     # DB 管道编译运行
├── agents/                  # LLM 代理
│   └── api_client.py        # DeepSeek API 调用
├── comparator/              # 字段比对
├── hina/                    # HINA 程序分类
├── config/                  # 配置管理
├── report/                  # 报告生成
├── test-data/               # 测试套件
├── tests/                   # 单元测试 (80+文件)
├── benchmark-programs/      # 43个基准 COBOL 程序
├── docs/                    # 文档
│   ├── detailed-design/     # V3 详细设计 (9个文档)
│   └── development-paradigm.md
└── sample/                  # 示例数据

测试命令

# 运行所有单元测试
python -m pytest tests/ -v

# 运行核心引擎测试
python -m pytest tests/cobol_testgen/ -v

# 运行覆盖率验证
python test-data/s15_coverage_verification.py

# 运行 DB 端到端测试
python test-data/s30_db_e2e.py

关键约束与注意事项

解析器

• Lark 语法 (grammar.lark): Earley parser, dynamic lexer
• 命名终端: 必须使用 USAGE_VAL 而非内联字符串
• 88 级限制: 目标程序无 88 级 VALUE 子句
• REDEFINES/FILLER: 捕获但跳过 (debug 日志警告)

路径枚举

• MC/DC 条件: 支持 AND/OR/NOT 复合条件
• 路径上限: 规则引擎 100 路径, LLM 模式 5000 路径
• O(N) 算法: 避免 O(2^N) 爆炸

DB 管道

• gixsql: 预处理 EXEC SQL → SQLite
• 种子键一致性: WHERE 宿主变量 MOVE 链解析到输入记录根字段
• 列名归一化: -/_ 容忍 (EMP-ID vs EMP_ID)

覆盖率

• 分支覆盖率目标: 75%
• 条件覆盖率: 75% (_FUNC_MOD 合成函数不可匹配)
• HTML 报告: 全中文 (标题、图例、徽章)

环境要求

• Python 3.12+ (lark, pyyaml)
• GnuCOBOL 3.2.0 (GC32-BDB-SP1)
• gixsql (已 vendored 在 gixsql/ 目录)
• DeepSeek API (可选, 用于 LLM 路径生成)

AI 使用规范

本项目使用 DeepSeek 作为 AI 辅助工具。使用时需注意:

1. API Key: 设置 DEEPSEEK_API_KEY 环境变量
2. 日志记录: 所有 AI 生成/修改的文件需记录在 _AI_USAGE_LOG.md
3. 审查流程: 代码变更需经过 code-review skill 审查
4. 硬编码禁止: 禁止硬编码绝对路径、API Key、密码

文档索引

文档	说明
SETUP.md	环境搭建、运行指南
docs/v3-理解文档.md	系统架构、组件说明
docs/detailed-design/	V3 详细设计 (9个文档)
docs/development-paradigm.md	开发范式流程图
docs/test-report.md	测试报告
_AI_USAGE_LOG.md	AI 使用日志