====================================================================================
【任务】从 Cucumber 步骤定义文件中提取步骤信息，生成 JSON 配置
====================================================================================

分析 TypeScript/JavaScript 步骤定义文件，为每个步骤生成包含以下字段的 JSON 对象：
- text (步骤文本) 【必需】
- gherkin (步骤类型: 0-5) 【必需】
- def (位置信息) 【推荐】
- desc (简短描述) 【推荐】
- documentation (完整文档) 【推荐】



输出纯 JSON 数组，不包含 markdown 代码块标记。

====================================================================================
【核心规则】text 字段生成
====================================================================================

1. 识别步骤定义模式
   - Given('text', ...) / When('text', ...) / Then('text', ...)
   - Given(/^regex$/, ...) / When(/^regex$/, ...) / Then(/^regex$/, ...)
   - {pronoun} 替换为 "I"

2. 正则转换为文本
   移除: ^ $ \
   转换捕获组:
   - ([^"]+) 或 "(.*?)" → {string}
   - (\d+) → {int}
   - (\d+\.?\d*) → {float}
   
3. ⚠️ 关键：展开可选/替代模式为独立步骤
   
   模式              → 生成步骤数
   (not )?          → 2 (有 not / 无 not)
   (s)?             → 2 (单数 / 复数)
   \(s\)?           → 2 (有括号 / 无括号)
   (a|b|c)          → 3 (每个选项一个)
   
   示例 1:
   输入: /^I should (not )?see the following field\(s\):$/
   输出两个步骤:
   {
     "text": "I should see the following field(s):",
     "gherkin": 2,
     "def": {"loc": "shared-verify.steps.ts:394"},
     "desc": "...",
     "documentation": "..."
   },
   {
     "text": "I should not see the following field(s):",
     "gherkin": 2,
     "def": {"loc": "shared-verify.steps.ts:394"},
     "desc": "...",
     "documentation": "..."
   }
   
   示例 2:
   输入: Then(`{pronoun} should see the {string} page`, ...)
   输出一个步骤:
   {
     "text": "I should see the {string} page",
     "gherkin": 2
   }

4. 保持原样
   - {string} {int} {float} 等 Cucumber 表达式（不加引号！）
   - \(s\) 转换为 (s)
   - 末尾冒号 : (DataTable 标记)

====================================================================================
【其他字段规则】
====================================================================================

gherkin 字段 (数值)
  0 = Given    1 = When    2 = Then
  3 = And      4 = But     5 = Other

def 字段
  {"loc": "文件名:行号"}
  示例: {"loc": "shared-verify.steps.ts:60"}

desc 字段
  提取 JSDoc 第一行描述（去掉 @description 标签）
  示例: "Verify that the actor can see the specified page by checking the page title."

documentation 字段
  完整 JSDoc 格式化为 Markdown：
  - 描述段落
  - **Parameters:** 参数列表
  - **Example:** 示例代码
  - 使用 \n 换行
  
  示例:
  "documentation": "Verify that the actor can see the specified page.\n\n**Parameters:**\n- actor: the Serenity/JS actor\n- pageName: expected page title\n\n**Example:**\ngherkin\nThen he should see the \"Home\" page\n"

====================================================================================
【完整示例】基于真实代码
====================================================================================

示例 1: 简单步骤 + {pronoun}
───────────────────────────
Then(
    `{pronoun} should see the {string} page`,
    async (actor: Actor, pageName: string) => { ... }
)
→
{
  "text": "I should see the {string} page",
  "gherkin": 2,
  "def": {"loc": "shared-verify.steps.ts:60"},
  "desc": "Verify that the actor can see the specified page by checking the page title.",
  "documentation": "Verify that the actor can see the specified page by checking the page title.\n\n**Parameters:**\n- actor: the Serenity/JS actor performing the verification\n- pageName: expected page title to be visible\n\n**Example:**\ngherkin\nThen he should see the \"Home\" page\n"
}

示例 2: 可选模式 (not )?
─────────────────────────
Then(
    /^I should (not )?see the following field\(s\):$/,
    async (negation: string, fieldInfo: DataTable) => { ... }
)
→ 生成 2 个步骤:
[
  {
    "text": "I should see the following field(s):",
    "gherkin": 2,
    "def": {"loc": "shared-verify.steps.ts:394"},
    "desc": "Verify that specified form fields are present on the current page/section.",
    "documentation": "Verify that specified form fields are present (or absent) on the current page/section. The DataTable should list field identifiers expected to be shown or not shown.\n\n**Parameters:**\n- negation: when present indicates the fields should NOT be seen\n- fieldInfo: table listing expected field names\n\n**Example:**\ngherkin\nThen I should see the following field(s):\n| NYCDOT PIN | Solicitation Name |\n"
  },
  {
    "text": "I should not see the following field(s):",
    "gherkin": 2,
    "def": {"loc": "shared-verify.steps.ts:394"},
    "desc": "Verify that specified form fields are present on the current page/section.",
    "documentation": "Verify that specified form fields are present (or absent) on the current page/section. The DataTable should list field identifiers expected to be shown or not shown.\n\n**Parameters:**\n- negation: when present indicates the fields should NOT be seen\n- fieldInfo: table listing expected field names\n\n**Example:**\ngherkin\nThen I should not see the following field(s):\n| TemporaryField |\n"
  }
]

示例 3: 复杂正则 + 参数
───────────────────────
When(
    `{pronoun} click the {string} button`,
    async (actor: Actor, buttonName: string) => { ... }
)
→
{
  "text": "I click the {string} button",
  "gherkin": 1,
  "def": {"loc": "shared-click.steps.ts:33"},
  "desc": "Clicks a named button on the current page and waits briefly for UI updates.",
  "documentation": "Clicks a named button on the current page and waits briefly for UI updates.\n\n**Parameters:**\n- buttonName: the visible label of the button to click\n\n**Example:**\ngherkin\nWhen I click the \"Save\" button\n"
}

示例 4: 正则 + 替代组
─────────────────────
Then(/^I should see the "([^"]+)" icon, its tooltip, and a hyperlink in the (sub|grand) Total line of the following column\(s\):$/, ...)
→ 生成 2 个步骤:
[
  {
    "text": "I should see the {string} icon, its tooltip, and a hyperlink in the sub Total line of the following column(s):",
    "gherkin": 2,
    "def": {"loc": "..."},
	"desc": "",//根据其他字段规则补充
    "documentation": ""//根据其他字段规则补充

  },
  {
    "text": "I should see the {string} icon, its tooltip, and a hyperlink in the grand Total line of the following column(s):",
    "gherkin": 2,
    "def": {"loc": "..."},
	"desc": "",//根据其他字段规则补充
    "documentation": ""//根据其他字段规则补充
  }
]

====================================================================================
【验证清单】返回前必检查
====================================================================================

✓ JSON 格式有效（可被 JSON.parse 解析）
✓ 不包含 ```json 等 markdown 标记
✓ 每个对象都有 text 和 gherkin 字段
✓ text 不含未展开的正则: (not )? (s)? (a|b)
✓ text 中 {string} 不加引号
✓ {pronoun} 已替换为 "I"
✓ gherkin 是数值 (0-5)，不是字符串
✓ 每个步骤都尝试提取了 def, desc, documentation
✓ 可选模式已展开为多个独立步骤（共享相同的 desc/documentation）
✓ **已提取文件中的所有步骤定义（检查文件末尾确保没有遗漏）**

⚠️ **重要提醒**:
- 如果源文件很大（超过 50 个步骤定义），请确保处理到文件末尾
- 不要因为 token 限制而停止处理，必须覆盖所有步骤
- 在生成 JSON 时，优先保证完整性，描述字段可以简化

====================================================================================
【快速参考】
====================================================================================

输入模式                  → 输出步骤数
Given('text', ...)       → 1
/^(not )?text$/          → 2 (有not / 无not)
/^(a|b) text$/           → 2 (a版本 / b版本)
/^text\(s\)$/            → 1 (保留(s)不展开)
/^text\(s\)?$/           → 2 (有(s) / 无(s))
{pronoun}                → 替换为 "I"
([^"]+) 或 "(.*?)"       → {string}
(\d+)                    → {int}

输出纯 JSON 数组，不要任何解释性文字或代码块标记。
