version: 1
metadata:
  key: "functional-testing"
interface:
  display_name: "Functional Testing (English)"
  short_description: "Use this skill when you need to design functional test plans or cases for business flows, UI, data, and integrations; triggers include functional testing and f…"
  default_prompt: "Use the functional-testing skill to complete this testing task with structured outputs and practical next steps."
policy:
  allow_implicit_invocation: true

schema_version: v1alpha1

environment:
  type: none

skills:
  - source: local_path
    path: .

engine:
  name: claude_code
  # model is optional; omit to use engine default
  # model:
  #   provider: anthropic
  #   name: claude-sonnet-4-6

cases:
  files:
    - evals/cases/basic-success.yaml
    - evals/cases/edge-incomplete-input.yaml
    - evals/cases/edge-risk-priority.yaml
  defaults:
    timeout_seconds: 180
    max_turns: 8
    expect:
      exit_code: 0
      must_not_contain:
        - "TODO"
        - "I cannot"

report:
  formats: [json]

{
  "meta": {
    "skill": "",
    "scope": "",
    "environment": "",
    "priority": ""
  },
  "inputs": {
    "requirement": "",
    "constraints": [],
    "risks": []
  },
  "execution": [
    { "step": 1, "action": "", "expected": "" }
  ],
  "results": {
    "status": "",
    "evidence": [],
    "defects": []
  },
  "next_actions": [
    { "owner": "", "eta": "", "action": "" }
  ]
}

# QA Output Template

## Summary
- Skill:
- Scope:
- Environment:
- Priority:

## Inputs
- Requirement:
- Constraints:
- Risks:

## Execution
1. Step 1
2. Step 2
3. Step 3

## Results
- Status:
- Evidence:
- Defects:

## Next Actions
- Owner:
- ETA:

QA Report
=========

1. Basic Information
- Skill:
- Scope:
- Environment:
- Priority:

2. Requirement and Constraints
- Requirement:
- Constraints:
- Risks:

3. Test/Review Process
- Step 1:
- Step 2:
- Step 3:

4. Outcome
- Status:
- Evidence:
- Defects:

5. Follow-up Plan
- Owner:
- ETA:
- Action:

# QA Output Mindmap

- QA Output
  - Meta
    - Skill
    - Scope
    - Environment
    - Priority
  - Inputs
    - Requirement
    - Constraints
    - Risks
  - Execution
    - Step 1
    - Step 2
    - Step 3
  - Results
    - Status
    - Evidence
    - Defects
  - Next Actions
    - Owner
    - ETA
    - Action

# Functional Testing Prompt

Design functional testing coverage for the features that matter most and make the result ready for execution.

## Role

- Act as a senior QA and functional testing expert who focuses on business-critical behavior and realistic failure risk.


## Input

- requirements, user stories, flows, UI designs, or release notes
- in-scope modules, target users, environments, and constraints
- existing defects, known weak areas, and current test assets

## What to do

1. Understand the core business flows and expected outcomes.
2. Prioritize high-value and failure-prone scenarios first.
3. Turn the scope into a practical testing plan or case list.

## Execution Rules

- Cover normal, abnormal, and boundary behavior when relevant.
- Group scenarios by user flow or business objective instead of random feature lists.
- Call out areas that still need clarification before execution.

## Minimum Coverage Checklist

Unless the user explicitly narrows the scope, make sure the result addresses these items:
- scope
- core flows
- positive scenarios
- negative scenarios
- boundary scenarios
- role or permission differences
- data conditions
- integration points
- priority by risk
- out-of-scope or unclear items

## Output

Return the result in this order:

### 1. Task Understanding
### 2. Risk and Priority
### 3. Core Functional Coverage
### 4. Key Scenario List
### 5. Execution Notes
### 6. Open Questions

## Quality Bar

- Be specific about scenarios.
- Do not produce a flat checklist with no prioritization.
- Avoid generic filler.

# Output Formats

Describe recommended output formats for functional testing deliverables.

## Troubleshooting

### Issue 1: Code Examples Won't Run

**Symptoms:** Error `Cannot find module` or `Command not found` when running examples

**Solution:**
1. Ensure dependencies are installed:
   ```bash
   cd examples/playwright-login
   npm install
   ```
2. Check Node.js version (requires >= 16):
   ```bash
   node --version
   ```
3. If using Playwright, install browsers:
   ```bash
   npx playwright install
   ```

### Issue 2: Incomplete Test Case Design

**Symptoms:** Low test coverage, missing important scenarios

**Solution:**
1. Use requirements-analysis skill first to analyze requirements
2. Refer to "Test Coverage Dimensions" section in the prompt
3. Use test design methods:
   - Equivalence partitioning
   - Boundary value analysis
   - Decision table testing
   - State transition testing
4. Checklist:
   - [ ] Normal scenarios
   - [ ] Exception scenarios
   - [ ] Boundary values
   - [ ] Error handling
   - [ ] Accessibility
   - [ ] Security

### Issue 3: Output Format Not as Expected

**Symptoms:** Generated test cases have wrong format or missing fields

**Solution:**
1. Clearly specify format requirements at the end of request:
   ```
   Please output as tab-separated table for pasting into Excel
   ```
2. Refer to examples in [output-formats.md](output-formats.md)
3. Use format conversion tool (to be implemented):
   ```bash
   ./tools/format-converter.sh input.md --to=excel
   ```

### Issue 4: Unstable Test Execution

**Symptoms:** Tests sometimes pass, sometimes fail

**Solution:**
1. Use explicit waits instead of fixed delays:
   ```typescript
   // ✅ Recommended
   await expect(element).toBeVisible();
   
   // ❌ Not recommended
   await page.waitForTimeout(3000);
   ```
2. Wait for network requests to complete:
   ```typescript
   await page.waitForResponse(resp => resp.url().includes('/api'));
   ```
3. Use retry mechanism (Playwright config):
   ```typescript
   retries: 2
   ```

### Issue 5: Cannot Locate Element

**Symptoms:** Test error `Element not found` or `Timeout`

**Solution:**
1. Check if element is in iframe:
   ```typescript
   const frame = page.frameLocator('iframe');
   await frame.locator('[data-testid="element"]').click();
   ```
2. Wait for element to appear:
   ```typescript
   await page.waitForSelector('[data-testid="element"]');
   ```
3. Use more reliable locators:
   ```typescript
   // ✅ Recommended: data-testid
   page.locator('[data-testid="login-button"]')
   
   // ✅ Recommended: role
   page.getByRole('button', { name: 'Login' })
   
   // ❌ Not recommended: CSS class
   page.locator('.btn-primary')
   ```

### Issue 6: Slow Test Execution

**Symptoms:** Test suite takes too long to execute

**Solution:**
1. Enable parallel execution:
   ```typescript
   // playwright.config.ts
   fullyParallel: true,
   workers: 4,
   ```
2. Optimize wait strategies, avoid unnecessary waits
3. Use test data caching
4. Consider using API to set up test preconditions

### Issue 7: CI/CD Environment Test Failures

**Symptoms:** Tests pass locally but fail in CI

**Solution:**
1. Check environment differences (browser version, screen resolution)
2. Increase timeout for CI environment
3. Enable failure retry:
   ```typescript
   retries: process.env.CI ? 2 : 0
   ```
4. Review CI logs, screenshots, and videos
5. Use Docker containers to ensure environment consistency

### Get More Help

If the issue persists:
1. Check [FAQ.md](local/FAQ.md)
2. Check example README.md files
3. Search [GitHub Issues](https://github.com/naodeng/awesome-qa-skills/issues)
4. Submit a new Issue with detailed information

**Related:** api-testing, test-case-writing, test-strategy, automation-testing.

#!/usr/bin/env python3
import argparse
import subprocess
import sys
from pathlib import Path


def detect_from(file: Path) -> str:
    ext = file.suffix.lower()
    if file.name.endswith('.word.md'):
        return 'markdown'
    return {
        '.md': 'markdown',
        '.markdown': 'markdown',
        '.json': 'json',
        '.csv': 'csv',
        '.tsv': 'excel',
        '.docx': 'word',
        '.xlsx': 'excel',
        '.xmind': 'xmind',
    }.get(ext, 'markdown')


def run_convert(convert_script: Path, src: Path, to_fmt: str, out: Path) -> int:
    cmd = [sys.executable, str(convert_script), str(src), '--from', detect_from(src), '--to', to_fmt, '--output', str(out)]
    return subprocess.call(cmd)


def main() -> None:
    parser = argparse.ArgumentParser(description='Batch convert all template files into target formats.')
    parser.add_argument('--templates-dir', type=Path, default=Path('output-templates'))
    parser.add_argument('--artifacts-dir', type=Path, default=Path('artifacts'))
    parser.add_argument('--targets', default='word,excel,xmind,json,csv,markdown', help='comma-separated target formats')
    parser.add_argument('--skip-same', action='store_true', help='skip conversion when source format equals target format')
    args = parser.parse_args()

    cwd = Path.cwd()
    templates_dir = (cwd / args.templates_dir).resolve()
    artifacts_dir = (cwd / args.artifacts_dir).resolve()
    artifacts_dir.mkdir(parents=True, exist_ok=True)

    local_convert = (Path(__file__).resolve().parent / 'convert_formats.py').resolve()
    targets = [t.strip() for t in args.targets.split(',') if t.strip()]

    if not templates_dir.exists():
        raise SystemExit(f'templates directory not found: {templates_dir}')

    files = [p for p in sorted(templates_dir.iterdir()) if p.is_file()]
    total = 0
    failed = 0

    for src in files:
        src_fmt = detect_from(src)
        for to_fmt in targets:
            if args.skip_same and src_fmt == to_fmt:
                continue
            out_ext = {
                'json': '.json',
                'csv': '.csv',
                'excel': '.tsv',
                'markdown': '.md',
                'word': '.word.md',
                'xmind': '.xmind.md',
            }[to_fmt]
            out = artifacts_dir / f"{src.stem}.to-{to_fmt}{out_ext}"
            total += 1
            rc = run_convert(local_convert, src, to_fmt, out)
            if rc != 0:
                failed += 1
                print(f'[FAILED] {src.name} -> {to_fmt}')
            else:
                print(f'[OK] {src.name} -> {out.name}')

    print(f'\nDone. total={total}, failed={failed}, artifacts={artifacts_dir}')
    if failed:
        raise SystemExit(1)


if __name__ == '__main__':
    main()

#!/usr/bin/env python3
import argparse
import csv
import json
import re
import zipfile
from pathlib import Path
from typing import Any
from xml.etree import ElementTree as ET


# ---- parsing ----
def parse_markdown(path: Path) -> dict[str, Any]:
    text = path.read_text(encoding="utf-8", errors="ignore")
    lines = text.splitlines()
    headings: list[dict[str, Any]] = []
    for line in lines:
        m = re.match(r"^(#{1,6})\s+(.*)$", line.strip())
        if m:
            headings.append({"level": len(m.group(1)), "title": m.group(2).strip()})
    return {"title": headings[0]["title"] if headings else path.stem, "headings": headings, "text": text}


def parse_json(path: Path) -> dict[str, Any]:
    data = json.loads(path.read_text(encoding="utf-8", errors="ignore"))
    return {"title": path.stem, "data": data}


def parse_csv_file(path: Path) -> dict[str, Any]:
    with path.open("r", encoding="utf-8", errors="ignore", newline="") as f:
        reader = csv.DictReader(f)
        rows = list(reader)
    return {"title": path.stem, "columns": reader.fieldnames or [], "rows": rows}


def parse_docx(path: Path) -> dict[str, Any]:
    paragraphs: list[str] = []
    with zipfile.ZipFile(path) as zf:
        with zf.open("word/document.xml") as f:
            root = ET.fromstring(f.read())
    ns = {"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"}
    for p in root.findall(".//w:p", ns):
        texts = [t.text for t in p.findall(".//w:t", ns) if t.text]
        s = "".join(texts).strip()
        if s:
            paragraphs.append(s)
    return {"title": path.stem, "paragraphs": paragraphs}


def _shared_strings(zf: zipfile.ZipFile) -> list[str]:
    out: list[str] = []
    try:
        with zf.open("xl/sharedStrings.xml") as f:
            root = ET.fromstring(f.read())
        ns = {"a": "http://schemas.openxmlformats.org/spreadsheetml/2006/main"}
        for si in root.findall(".//a:si", ns):
            out.append("".join((t.text or "") for t in si.findall(".//a:t", ns)))
    except KeyError:
        pass
    return out


def parse_xlsx(path: Path) -> dict[str, Any]:
    rows: list[list[str]] = []
    with zipfile.ZipFile(path) as zf:
        shared = _shared_strings(zf)
        with zf.open("xl/worksheets/sheet1.xml") as f:
            root = ET.fromstring(f.read())
    ns = {"a": "http://schemas.openxmlformats.org/spreadsheetml/2006/main"}
    for row in root.findall(".//a:sheetData/a:row", ns):
        vals = []
        for c in row.findall("a:c", ns):
            t = c.attrib.get("t")
            v = c.find("a:v", ns)
            if v is None or v.text is None:
                vals.append("")
            elif t == "s":
                idx = int(v.text)
                vals.append(shared[idx] if 0 <= idx < len(shared) else "")
            else:
                vals.append(v.text)
        rows.append(vals)
    return {"title": path.stem, "rows": rows}


def parse_xmind(path: Path) -> dict[str, Any]:
    with zipfile.ZipFile(path) as zf:
        names = set(zf.namelist())
        topics: list[str] = []
        if "content.json" in names:
            data = json.loads(zf.read("content.json").decode("utf-8", errors="ignore"))

            def walk(node: Any):
                if isinstance(node, dict):
                    t = node.get("title")
                    if isinstance(t, str) and t.strip():
                        topics.append(t.strip())
                    for k in ("children", "topics", "rootTopic", "attached"):
                        walk(node.get(k))
                elif isinstance(node, list):
                    for i in node:
                        walk(i)

            walk(data)
        elif "content.xml" in names:
            root = ET.fromstring(zf.read("content.xml"))
            topics = [e.text.strip() for e in root.findall(".//title") if e.text and e.text.strip()]
        else:
            raise ValueError("Unsupported XMind package structure")
    return {"title": topics[0] if topics else path.stem, "topics": topics}


def detect_in_format(path: Path, forced: str | None) -> str:
    if forced and forced != "auto":
        return forced
    return {
        ".md": "markdown",
        ".markdown": "markdown",
        ".json": "json",
        ".csv": "csv",
        ".docx": "word",
        ".xlsx": "excel",
        ".xmind": "xmind",
        ".tsv": "excel",
    }.get(path.suffix.lower(), "markdown")


def normalize(parsed: dict[str, Any]) -> dict[str, Any]:
    title = parsed.get("title") or "QA Output"
    sections: list[dict[str, Any]] = []

    if "text" in parsed:
        sections.append({"name": "content", "items": [{"key": "text", "value": parsed["text"]}]})
    if "headings" in parsed:
        sections.append({"name": "headings", "items": [{"key": "heading", "value": h.get("title", "")} for h in parsed["headings"]]})
    if "data" in parsed:
        data = parsed["data"]
        if isinstance(data, dict):
            items = [{"key": k, "value": v} for k, v in list(data.items())[:100]]
            sections.append({"name": "json_object", "items": items})
        elif isinstance(data, list):
            sections.append({"name": "json_array", "items": [{"key": "row", "value": v} for v in data[:200]]})
        else:
            sections.append({"name": "json_value", "items": [{"key": "value", "value": data}]})
    if "rows" in parsed:
        rows = parsed["rows"]
        sections.append({"name": "rows", "items": [{"key": f"row_{i+1}", "value": r} for i, r in enumerate(rows[:200])]})
    if "columns" in parsed:
        sections.append({"name": "columns", "items": [{"key": "column", "value": c} for c in parsed["columns"]]})
    if "paragraphs" in parsed:
        sections.append({"name": "paragraphs", "items": [{"key": f"p{i+1}", "value": p} for i, p in enumerate(parsed["paragraphs"][:200])]})
    if "topics" in parsed:
        sections.append({"name": "topics", "items": [{"key": "topic", "value": t} for t in parsed["topics"][:300]]})

    return {"title": title, "sections": sections}


# ---- writers ----
def write_json(model: dict[str, Any], output: Path) -> None:
    output.write_text(json.dumps(model, ensure_ascii=False, indent=2), encoding="utf-8")


def _scalar(v: Any) -> str:
    if isinstance(v, (dict, list)):
        return json.dumps(v, ensure_ascii=False)
    return str(v)


def write_csv(model: dict[str, Any], output: Path) -> None:
    with output.open("w", encoding="utf-8", newline="") as f:
        writer = csv.writer(f)
        writer.writerow(["section", "key", "value"])
        for s in model.get("sections", []):
            for item in s.get("items", []):
                writer.writerow([s.get("name", ""), item.get("key", ""), _scalar(item.get("value", ""))])


def write_excel_tsv(model: dict[str, Any], output: Path) -> None:
    lines = ["Section\tKey\tValue"]
    for s in model.get("sections", []):
        for item in s.get("items", []):
            lines.append(f"{s.get('name','')}\t{item.get('key','')}\t{_scalar(item.get('value','')).replace(chr(9), ' ')}")
    output.write_text("\n".join(lines) + "\n", encoding="utf-8")


def write_markdown(model: dict[str, Any], output: Path) -> None:
    lines = [f"# {model.get('title', 'QA Output')}", ""]
    for s in model.get("sections", []):
        lines.append(f"## {s.get('name', 'section')}")
        for item in s.get("items", []):
            lines.append(f"- **{item.get('key','key')}**: {_scalar(item.get('value',''))}")
        lines.append("")
    output.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")


def write_word_md(model: dict[str, Any], output: Path) -> None:
    lines = [model.get("title", "QA Output"), "=" * len(model.get("title", "QA Output")), ""]
    idx = 1
    for s in model.get("sections", []):
        lines.append(f"{idx}. {s.get('name', 'section').replace('_', ' ').title()}")
        for item in s.get("items", []):
            lines.append(f"- {item.get('key','key')}: {_scalar(item.get('value',''))}")
        lines.append("")
        idx += 1
    output.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")


def write_xmind_md(model: dict[str, Any], output: Path) -> None:
    lines = [f"# {model.get('title', 'QA Output')}", "", f"- {model.get('title', 'QA Output')}"]
    for s in model.get("sections", []):
        lines.append(f"  - {s.get('name', 'section')}")
        for item in s.get("items", []):
            lines.append(f"    - {item.get('key','key')}: {_scalar(item.get('value',''))}")
    output.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")


def default_output(input_path: Path, to_fmt: str) -> Path:
    ext = {
        "json": ".json",
        "csv": ".csv",
        "excel": ".tsv",
        "markdown": ".md",
        "word": ".word.md",
        "xmind": ".xmind.md",
    }[to_fmt]
    return input_path.with_name(input_path.stem + ".converted" + ext)


def main() -> None:
    parser = argparse.ArgumentParser(description="Convert QA output files between common formats")
    parser.add_argument("input", type=Path, help="Input file path")
    parser.add_argument("--from", dest="from_fmt", default="auto", choices=["auto", "word", "excel", "xmind", "json", "csv", "markdown"])
    parser.add_argument("--to", required=True, choices=["word", "excel", "xmind", "json", "csv", "markdown"])
    parser.add_argument("--output", type=Path, help="Output file path")
    args = parser.parse_args()

    in_fmt = detect_in_format(args.input, args.from_fmt)
    if in_fmt == "word":
        parsed = parse_docx(args.input)
    elif in_fmt == "excel":
        if args.input.suffix.lower() == ".tsv":
            rows = [line.rstrip("\n").split("\t") for line in args.input.read_text(encoding="utf-8", errors="ignore").splitlines() if line]
            parsed = {"title": args.input.stem, "rows": rows}
        else:
            parsed = parse_xlsx(args.input)
    elif in_fmt == "xmind":
        parsed = parse_xmind(args.input)
    elif in_fmt == "json":
        parsed = parse_json(args.input)
    elif in_fmt == "csv":
        parsed = parse_csv_file(args.input)
    else:
        parsed = parse_markdown(args.input)

    model = normalize(parsed)
    output = args.output or default_output(args.input, args.to)

    if args.to == "json":
        write_json(model, output)
    elif args.to == "csv":
        write_csv(model, output)
    elif args.to == "excel":
        write_excel_tsv(model, output)
    elif args.to == "markdown":
        write_markdown(model, output)
    elif args.to == "word":
        write_word_md(model, output)
    else:
        write_xmind_md(model, output)

    print(str(output))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'convert_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'convert_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--to', 'csv'] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'convert_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--to', 'excel'] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'convert_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--to', 'json'] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'convert_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--to', 'markdown'] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'convert_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--to', 'word'] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'convert_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--to', 'xmind'] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'parse_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--format', 'csv'] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'parse_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--format', 'excel'] + sys.argv[1:]))

#!/usr/bin/env python3
import argparse
import csv
import json
import re
import zipfile
from pathlib import Path
from typing import Any
from xml.etree import ElementTree as ET


def parse_markdown(path: Path) -> dict[str, Any]:
    text = path.read_text(encoding="utf-8", errors="ignore")
    headings = []
    for line in text.splitlines():
        m = re.match(r"^(#{1,6})\s+(.*)$", line.strip())
        if m:
            headings.append({"level": len(m.group(1)), "title": m.group(2).strip()})
    return {"format": "markdown", "headings": headings, "preview": text[:500]}


def parse_json(path: Path) -> dict[str, Any]:
    data = json.loads(path.read_text(encoding="utf-8", errors="ignore"))
    if isinstance(data, dict):
        shape = {"type": "object", "keys": list(data.keys())[:50]}
    elif isinstance(data, list):
        shape = {"type": "array", "size": len(data)}
    else:
        shape = {"type": type(data).__name__}
    return {"format": "json", "shape": shape, "data": data}


def parse_csv_file(path: Path) -> dict[str, Any]:
    with path.open("r", encoding="utf-8", errors="ignore", newline="") as f:
        reader = csv.DictReader(f)
        rows = list(reader)
    return {
        "format": "csv",
        "columns": reader.fieldnames or [],
        "row_count": len(rows),
        "sample_rows": rows[:10],
    }


def parse_docx(path: Path) -> dict[str, Any]:
    paragraphs = []
    with zipfile.ZipFile(path) as zf:
        with zf.open("word/document.xml") as f:
            root = ET.fromstring(f.read())
    ns = {"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"}
    for p in root.findall(".//w:p", ns):
        texts = [t.text for t in p.findall(".//w:t", ns) if t.text]
        joined = "".join(texts).strip()
        if joined:
            paragraphs.append(joined)
    return {"format": "word", "paragraph_count": len(paragraphs), "paragraphs": paragraphs[:100]}


def _read_shared_strings(zf: zipfile.ZipFile) -> list[str]:
    strings = []
    try:
        with zf.open("xl/sharedStrings.xml") as f:
            root = ET.fromstring(f.read())
        ns = {"a": "http://schemas.openxmlformats.org/spreadsheetml/2006/main"}
        for si in root.findall(".//a:si", ns):
            parts = [t.text or "" for t in si.findall(".//a:t", ns)]
            strings.append("".join(parts))
    except KeyError:
        pass
    return strings


def parse_xlsx(path: Path) -> dict[str, Any]:
    rows_out: list[list[str]] = []
    with zipfile.ZipFile(path) as zf:
        shared = _read_shared_strings(zf)
        with zf.open("xl/worksheets/sheet1.xml") as f:
            root = ET.fromstring(f.read())
    ns = {"a": "http://schemas.openxmlformats.org/spreadsheetml/2006/main"}
    for row in root.findall(".//a:sheetData/a:row", ns):
        vals = []
        for c in row.findall("a:c", ns):
            cell_type = c.attrib.get("t")
            v = c.find("a:v", ns)
            if v is None or v.text is None:
                vals.append("")
                continue
            if cell_type == "s":
                idx = int(v.text)
                vals.append(shared[idx] if 0 <= idx < len(shared) else "")
            else:
                vals.append(v.text)
        rows_out.append(vals)
    return {"format": "excel", "row_count": len(rows_out), "sample_rows": rows_out[:20]}


def parse_xmind(path: Path) -> dict[str, Any]:
    with zipfile.ZipFile(path) as zf:
        names = set(zf.namelist())
        if "content.json" in names:
            data = json.loads(zf.read("content.json").decode("utf-8", errors="ignore"))
            titles: list[str] = []

            def walk(node: Any):
                if isinstance(node, dict):
                    title = node.get("title")
                    if isinstance(title, str) and title.strip():
                        titles.append(title.strip())
                    for k in ("children", "topics", "rootTopic", "attached"):
                        walk(node.get(k))
                elif isinstance(node, list):
                    for i in node:
                        walk(i)

            walk(data)
            return {"format": "xmind", "topic_count": len(titles), "topics": titles[:200]}
        if "content.xml" in names:
            root = ET.fromstring(zf.read("content.xml"))
            titles = [el.text.strip() for el in root.findall(".//title") if el.text and el.text.strip()]
            return {"format": "xmind", "topic_count": len(titles), "topics": titles[:200]}
    raise ValueError("Unsupported XMind package structure")


def detect_format(path: Path, forced: str | None) -> str:
    if forced and forced != "auto":
        return forced
    ext = path.suffix.lower()
    return {
        ".md": "markdown",
        ".markdown": "markdown",
        ".json": "json",
        ".csv": "csv",
        ".docx": "word",
        ".xlsx": "excel",
        ".xmind": "xmind",
    }.get(ext, "markdown")


def main() -> None:
    parser = argparse.ArgumentParser(description="Parse common QA output formats into normalized JSON")
    parser.add_argument("input", type=Path, help="Input file path")
    parser.add_argument("--format", default="auto", choices=["auto", "word", "excel", "xmind", "json", "csv", "markdown"])
    parser.add_argument("--output", type=Path, help="Output JSON path (default: stdout)")
    args = parser.parse_args()

    fmt = detect_format(args.input, args.format)
    if fmt == "word":
        result = parse_docx(args.input)
    elif fmt == "excel":
        result = parse_xlsx(args.input)
    elif fmt == "xmind":
        result = parse_xmind(args.input)
    elif fmt == "json":
        result = parse_json(args.input)
    elif fmt == "csv":
        result = parse_csv_file(args.input)
    else:
        result = parse_markdown(args.input)

    result["source"] = str(args.input)
    out = json.dumps(result, ensure_ascii=False, indent=2)
    if args.output:
        args.output.write_text(out, encoding="utf-8")
    else:
        print(out)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'parse_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--format', 'json'] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'parse_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--format', 'markdown'] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'parse_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'parse_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--format', 'word'] + sys.argv[1:]))

#!/usr/bin/env python3
import os
import subprocess
import sys
LOCAL = os.path.normpath(os.path.join(os.path.dirname(__file__), 'parse_formats.py'))
if __name__ == '__main__':
    raise SystemExit(subprocess.call([sys.executable, LOCAL, '--format', 'xmind'] + sys.argv[1:]))