feat(scan): author identity resolution — one row per human

[cvetty]

Populates the long-empty author table, so per-developer queries stop reporting one person several times.

Implements plans/author-identity-plan.md rev 3.

Why

The obvious contributor query on this repo returns four rows that are all the same human — three emails, two display names:

author_name	author_email	on_default_branch
cvetty	tsvetoslav.nikolov@mtr-design.com	1
Tsvetoslav Nikolov	85567502+cvetty@users.noreply.github.com	1
cvetty	tsvetoslav.nikolov@mtr-design.com	0
cvetty	tsvetoslav.nikolov@pfizer.com	0

Any per-developer chart or ranking built on a bare GROUP BY is wrong, and looks authoritative while being wrong. The author table, both its indexes, and its intended design have shipped since the initial schema — db/models/author.py names whygraph.scan.authors as its producer, and that module simply did not exist. This adds it.

How

Resolution is evidence-driven, never heuristic, in descending order of authority:

0. git's mailmap — a human explicitly asserting "these contacts are me". Read via git check-mailmap rather than parsing ./.mailmap, so a mailmap kept outside a public repo (mailmap.file / mailmap.blob — what a developer who needs email privacy does, and what this repo does) still applies. It also canonicalizes the name, which is what makes primary_name implementable. Batched via argv: one subprocess for every identity.
1. GitHub's own triples — pull_request.commit_titles entries already carry author_login / author_name / author_email together. On this repo that single signal resolves all three emails and both names with no inference at all.
2. The noreply parse — 12345+login@users.noreply.github.com → login. Pure string work, so it still resolves identities under --no-remote.
3. Byte-equal emails — implicit; the same address is the same node by construction.

What it deliberately refuses to do matters as much: it never merges on display name ("Alex Kim" is not one person globally), never fuzzy-matches addresses, and never treats a shared (noreply@github.com) or bot address as evidence. A false merge silently attributes one person's work to another and has no symptom; a false split is merely untidy. Union–find runs over namespaced nodes (("email", …) / ("login", …)) so a login and an identical display name cannot merge by coincidence.

Two ordering invariants, both forced by data rather than taste:

• The phase runs after PR-origin recovery — @pfizer.com appears only in the on_default_branch=0 rows Phase 2 writes.
• commit_count / first_seen / last_seen cover on_default_branch=1 only, so squashed work is not double-counted.

The phase is local, token-free and millisecond-scale, so it always runs — including under --no-remote and in the auto-rescan git hooks. Output is fully deterministic (clusters sorted, JSON arrays sorted, ties lexicographic), so the rebuilt-per-scan table produces no diff noise.

Nothing reads the table yet — deliberately. author was already in the chat SQL allowlist, so it becomes useful the moment it has rows, and the algorithm's real failure modes are better learned from a second and third repo than from a reader built on day one.

Changes

NEW scan/authors.py	AuthorResolver + the resolution algorithm
services/git/commands.py, repository.py	GitCheckMailmapCmd + Repository.check_mailmap() (argv-batched, chunked at 500, ShellError → GitError)
cli/commands/scan.py	the 👥 phase between PR-origins and LLM descriptions, plus phase_total and the results-panel row
scan/__init__.py	export
NEW tests/test_scan_authors.py, tests/test_services_git_mailmap.py	38 tests
tests/test_cli_scan_phases.py, tests/test_mcp_resources.py	phase-numbering matrix; top_contributors regression

No new Alembic revision, no config key, no CLI flag, no new dependency.

Verified on this repo

1|cvetty|cvetty|tsvetoslav.nikolov@mtr-design.com
 |["85567502+cvetty@users.noreply.github.com", "…@mtr-design.com", "…@pfizer.com"]
 |["cvetty"]|["Tsvetoslav Nikolov", "cvetty"]|…|170|38|0

One row — the plan's §3.8 shape. Two consecutive scans produce byte-identical rows. Through the chat SQL surface, grouping via author now returns one developer where the raw author_email grouping still returns two.

commit_count read 170, not the plan's measured 169, because the scan indexed one new commit. The ACs assert an identity against the DB rather than a constant — commit_count == COUNT(*) WHERE on_default_branch = 1 AND author_email IN (emails) evaluates 170 == 170. That drift is the plan's risk 11 behaving as designed, not a regression.

Two deviations from the plan, both forced

1. _to_author_row assigns author.id explicitly (1..n in sorted cluster order) instead of leaving it to the DB. Not anticipated by the plan, and a real defect: SQLAlchemy's insertmanyvalues path rejects a multi-row insert whose nullable autoincrement PK is unset. This repo resolves to one row, so the live smoke passed — only the multi-row fixtures exposed it. It also makes the determinism guarantee true by construction rather than by relying on SQLite reusing rowids after the DELETE. id stays ephemeral; nothing references it.
2. The results-panel row uses _optional_phase_cells, not the plan's bare _status_glyph. The plan's reasoning ("resolution always runs, so it is never None") holds for the CLI, but _render_results_panel is also called directly by an existing test with a ran list that omits it — a bare resolver.error would crash there, breaking that function's documented promise that it can never turn a successful crawl into a crash. Renders identically in every real scan.

One design point also needed a clause the plan lacked: a denied shared address is both a cluster attribute and a node, which would leave a phantom singleton row beside the two clusters the shared-email test expects. It is now dropped once some cluster has claimed it, and kept when none has.

Gates

ruff check src/ tests/ scripts/ ✓ · ruff format --check src/ tests/ scripts/ ✓ · pytest — 832 passed