# issues: specs

Constants at the top of `issues.py`: `DAYS=30`, `PAGE=50`, `MAX_PAGES=20`, `PR_COMMITS=100`, `TYPE_LABELS`, `KEY_RX`, `REF_RX`, `BRANCH_RX`.

## I-repo: which repos
Each `--repo` is resolved with `realpath`; `repo_label = basename` (same as impact L-repo, so labels join). The GitHub slug comes from `git remote get-url origin` (ssh or https, `.git` optional). No GitHub origin, or `gh` fails for that repo (deleted, renamed, no access): a line on stderr, repo skipped, `repos_scanned` not incremented.

## I-fetch: reading GitHub
`gh api graphql`, `pullRequests` and `issues` (GitHub's `issues` excludes PRs) ordered by `UPDATED_AT DESC`, `PAGE` nodes per page. Kept: nodes with `updatedAt` ≥ now − `--days`. Paging stops at the first page holding an older node, at the last page, or after `MAX_PAGES`; in the last case `"<repo_label>:<kind>"` is added to the summary's `truncated`. Per PR at most `PR_COMMITS` commits and 20 labels and closing issues are read.

## I-keys: ticket keys without an API
From PR title and head branch: `KEY_RX` (`ABC-123`, Jira/Linear) → `keys`; `#N` in the title (`REF_RX`) and a leading number in a branch segment (`BRANCH_RX`: `fix/12-x`, `12-x`, `gh-12_x`) → issue numbers. Numbers count only if that issue is among the fetched issues of the repo (branch digits are often not issues). Title and branch are not stored.

## I-pr: PR record
`state` = `merged` if `mergedAt`, else `open`/`closed`. `issues` = sorted union of GitHub `closingIssuesReferences` and I-keys numbers. `commits` = PR commit shas; `merge_sha` = merge/squash commit or null. `author` = sha256(login)[:12] (impact hashes emails, so authors do not join across the two).

## I-issue: issue record
`state` `open`/`closed`, `state_reason` lowercased (`completed`, `not_planned`, ...) or null. `prs` = fetched PRs whose `issues` holds it; `session_ids` = union of those PRs' sessions.

## I-type: ticket type
First label (case-insensitive) in `TYPE_LABELS`; an untyped PR takes the type of its first typed closing issue; else null (`none` in the summary).

## I-join: PR to sessions
Index of linked impact records (`link_p` non-null; pending window candidates are ignored): `(repo_label, sha) → session_id`. A PR's sessions = sessions owning any of its commit shas or its merge sha (a squash commit pulled locally and linked by impact).

## I-cost: spend
PR cost = Σ over its sessions of session `cost.total` × (that session's commits matched in this PR / that session's linked commits across all impact records). An issue gets cost/k of each closing PR that closes k issues. Rounded to 6 decimals. Summing PR cost never counts a session twice; summing issue cost misses PRs without issues.

## I-summary: issues_summary.json
`prs`, `prs_merged`, `prs_with_session`, `prs_without_ticket` (no `issues` and no `keys`: the share the pitfall in `../issue-trackers.md` asks for), `issues`, `issues_closed_without_pr`, `cost_linked` = Σ PR cost, `truncated`, `by_type` = per type (null → `none`): PR count, issue count, distinct sessions and Σ cost of its PRs.

## I-ex: worked example (`../tests/test_issues.py`, `../tests/fixtures/issues/`)
Impact: s-a linked [a1, a2] ($2), s-b pending [b1] ($1), s-c linked [c1] ($0.50). PRs: #10 merged, label bug, title "(#3)", commit a1 → bug, issues [3], s-a, $1.0; #11 "PROJ-42", commits a2+b1, closes 4 and 5 → type feature from issue 4's label `Enhancement`, $1.0 (b1 pending, ignored); #12 closed, branch `12-wip` (no issue 12) → ticketless, $0; #13 merge sha c1 → s-c, $0.5, ticketless; #9 older than the window, paging stops before page 3. Issues: 3 ($1.0), 4 and 5 ($0.5 each), 6 not_planned with no PR, 7 open. Summary: 4 PRs, 3 merged, 3 with a session, 2 without ticket, 5 issues, 1 closed without PR, cost 2.5.