# Jira example
def get_requirements_jira(project_key):
    jql = f'project = {project_key} AND issuetype = "User Story" AND status != Done'
    issues = jira_search(jql)
    return [
        {"id": i["key"], "title": i["fields"]["summary"],
         "status": i["fields"]["status"]["name"]}
        for i in issues
    ]

# Per platform
def get_cases_testrail(project_id):
    cases = []
    # Per testrail-case-management list_cases pattern
    for case in list_testrail_cases(project_id):
        refs = case.get("refs", "").split(",") if case.get("refs") else []
        cases.append({"id": f"C{case['id']}", "title": case["title"],
                      "refs": [r.strip() for r in refs if r.strip()]})
    return cases

def get_cases_xray(project_key):
    # Tests in Xray are Jira issues; links indicate requirement coverage
    tests = jira_search(f'project = {project_key} AND issuetype = Test')
    cases = []
    for t in tests:
        # Get linked requirement issues
        links = get_issue_links(t["key"])
        reqs = [l["outwardIssue"]["key"] for l in links
                if l.get("type", {}).get("name") in ("Tests", "TestedBy")]
        cases.append({"id": t["key"], "title": t["fields"]["summary"],
                      "refs": reqs})
    return cases

def coverage(requirements, cases):
    req_ids = {r["id"] for r in requirements}
    case_to_reqs = {c["id"]: set(c["refs"]) & req_ids for c in cases}
    reqs_to_cases = {r["id"]: [] for r in requirements}
    for c in cases:
        for r in c["refs"]:
            if r in reqs_to_cases:
                reqs_to_cases[r].append(c["id"])

    covered = {r for r, cs in reqs_to_cases.items() if cs}
    uncovered = req_ids - covered
    orphan_cases = {c["id"] for c in cases if not case_to_reqs[c["id"]]}
    over_tested = {r: len(cs) for r, cs in reqs_to_cases.items() if len(cs) > 5}

    return {
        "requirements_total": len(requirements),
        "requirements_covered": len(covered),
        "coverage_pct": len(covered) / len(requirements) * 100 if requirements else 0,
        "uncovered_requirements": sorted(uncovered),
        "orphan_cases": sorted(orphan_cases),
        "over_tested_requirements": over_tested,
        "matrix": reqs_to_cases,
    }

import csv

def write_matrix_csv(reqs_to_cases, requirements, path):
    with open(path, "w", newline="") as f:
        w = csv.writer(f)
        w.writerow(["Requirement ID", "Requirement Title", "Test Case IDs", "Count"])
        for r in requirements:
            cs = reqs_to_cases.get(r["id"], [])
            w.writerow([r["id"], r["title"], "; ".join(cs), len(cs)])

# Traceability matrix — <project> — <date>

**Requirement coverage:** 87 / 92 (94.6%)
**Orphan cases:** 14
**Over-tested requirements:** 3

## Matrix

| Requirement ID | Title | Test cases | Count |
|---|---|---|---|
| REQ-AUTH-001 | User logs in with valid credentials | C1234, C1235, C1240 | 3 |
| REQ-AUTH-002 | Password reset flow | C1241 | 1 |
| REQ-AUTH-003 | OAuth login (Google) | — | **0 (UNCOVERED)** |
| REQ-CHECKOUT-001 | Apply promo code | C2001, C2002, C2003, C2004, C2005, C2006 | **6 (OVER-TESTED)** |

## Uncovered requirements

- REQ-AUTH-003 — OAuth login (Google)
- REQ-AUTH-005 — Magic-link login
- ...

## Orphan cases

- C9999 — "Exploratory: cart edge cases"
- C9888 — "Smoke check — homepage renders"
- ...

## Traceability summary — <project> — <YYYY-MM-DD>

### Headline

**87 of 92 requirements covered (94.6%)** — 5 gaps require action
before the v1.4 release.

### Gaps requiring action

| Requirement | Status | Recommended action |
|---|---|---|
| REQ-AUTH-003 OAuth login (Google) | Uncovered | Add manual + automated case before sprint end |
| REQ-AUTH-005 Magic-link login | Uncovered | Add automated case |
| REQ-AUTH-006 SAML login | Uncovered | Defer to v1.5 — feature behind flag |
| REQ-CHECKOUT-008 Refund flow | Uncovered | Manual test exists in Confluence — migrate to TCM |
| REQ-API-014 Rate limit response | Uncovered | Add API test |

### Possible bloat (over-tested)

| Requirement | Cases | Recommendation |
|---|---|---|
| REQ-CHECKOUT-001 Apply promo code | 6 cases | Audit for duplicates; aim for ≤3 |
| REQ-AUTH-001 User login | 3 cases | Acceptable spread |

### Orphan cases

14 cases have no requirement reference. Of these:
- 8 are intentional (regression / smoke / exploratory)
- 6 should be linked to existing requirements (REQ-CHECKOUT-*)

### Next steps

1. Add the 5 missing cases for action requirements (4 person-days).
2. Audit REQ-CHECKOUT-001 for redundancy (½ person-day).
3. Link the 6 mis-categorised orphans (½ person-day).

# .github/workflows/traceability.yml
on:
  schedule:
    - cron: '0 9 * * MON'  # weekly Monday 09:00
  workflow_dispatch:

jobs:
  build-matrix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: python scripts/build-matrix.py > matrix.md
      - run: |
          gh issue create --title "Traceability matrix — $(date +%Y-%m-%d)" \
                          --body-file matrix.md \
                          --label coverage-report

reqs = get_requirements_jira("ENG")        # 92 requirements
cases = get_cases_testrail(project_id=42)  # 287 cases
cov = coverage(reqs, cases)
print(f"Coverage: {cov['coverage_pct']:.1f}%")
print(f"Uncovered: {cov['uncovered_requirements']}")
print(f"Orphans: {len(cov['orphan_cases'])}")
write_matrix_csv(cov["matrix"], reqs, "matrix.csv")

Coverage: 94.6%
Uncovered: ['REQ-AUTH-003', 'REQ-AUTH-005', 'REQ-AUTH-006',
            'REQ-CHECKOUT-008', 'REQ-API-014']
Orphans: 14