Composite merchant keys for same-name multi-category rules [5/6]

[terryaney]

[5/6] Based on feature/charts-reimagined (#101).
Merging this PR into main also lands #98, #99, #100, and #101 if not already merged.
This layer only: feature/charts-reimagined...feature/merchant-composite-keys

Fixes #88 — same-named merchant rules with different categories now work:

[Costco]
match: contains("COSTCO") and amount <= 200
category: Food
subcategory: Grocery

[Costco]
match: contains("COSTCO") and amount > 200
category: Shopping
subcategory: Wholesale

Changes

• analyzer.py — by_merchant uses a composite (merchant, category, subcategory) key so same-named merchants with different categories appear as separate report rows
• spending_report.js — filteredViewTotals and chartAggregations now use per-transaction txn.tags instead of the merchant-level tag union, fixing misclassification when one transaction's tags don't apply to all transactions at that merchant
• commands/explain.py — follows by_merchant to composite keys, so a name that now resolves to several entries can return all of them

Behavior change — tally explain --format json output shape

Intentional, and required by the fix: one merchant name can now legitimately resolve to more than one entry, which a single object cannot express. Merchant queries now emit a wrapper:

{
  "query": "Costco",
  "match_mode": "exact",
  "matched_names": ["Costco"],
  "merchants": [ { "name": "Costco", "category": "Food", ... } ]
}

where it previously emitted a bare merchant object. match_mode is exact, case_insensitive, or partial.

This also repairs output that was already invalid: the pre-existing partial-match path printed a human-readable Merchants matching 'x': header followed by several concatenated JSON objects, even under --format json, which no parser could consume. That path now emits one well-formed document.

Nothing persisted changes — explain computes from config and data files at run time and reads no output of tally up, so there is no mixed-version concern. The only thing that breaks is a script parsing the old single-object shape from a previous release, and the wrapper is deliberately uniform rather than switching shape on match count, so such a script has one form to move to rather than two.

Stack

#	Branch	PR	Description	Diff
1	feature/globbing-documentation	#98	Glob pattern docs and CLI tests	from main
2	feature/report-json-determinism	#99	Deterministic report JSON	from PR98 · from main
3	feature/ui-tweaks	#100	Date filter, transaction details, per-txn tags	from PR99 · from main
4	feature/charts-reimagined	#101	Reimagined charts and KPIs	from PR100 · from main
5	feature/merchant-composite-keys	#102	Composite merchant keys	from PR101 · from main
6	feature/categorization	#103	Categorization review file	from PR102 · from main

Independent: feature/ci-repair — #97 — fixes fork PR builds.

[Copilot]

Pull request overview

Introduces composite merchant identities so same-name merchants remain distinct across categories, alongside stacked report enhancements.

Changes:

• Groups merchants by name, category, and subcategory with stable report IDs.
• Adds per-transaction tag classification, recurrence analysis, new charts, and date filtering.
• Adds report_fields, deterministic output, glob tests/docs, and chart documentation.

Reviewed changes

Copilot reviewed 28 out of 41 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/tally/analyzer.py	Adds composite keys and recurrence inference.
src/tally/report.py	Generates stable merchant IDs and report data.
src/tally/spending_report.html	Adds report controls, charts, and details UI.
src/tally/spending_report.css	Styles the redesigned report.
src/tally/spending_report.js	Implements filtering, charts, and UI state.
src/tally/parsers.py	Surfaces configured report fields.
src/tally/format_parser.py	Adds report_fields metadata.
src/tally/config_loader.py	Resolves global and per-source report fields.
src/tally/merchant_engine.py	Suppresses empty computed fields.
src/tally/merchant_utils.py	Adds rule provenance metadata.
src/tally/templates.py	Updates starter configuration.
src/tally/cli_utils.py	Updates starter title generation.
src/tally/commands/run.py	Deduplicates report source names.
src/tally/commands/explain.py	Supports composite merchants in explanations.
src/tally/commands/diag.py	Documents additional special tags.
src/tally/commands/reference.py	Documents fields and recurrence tags.
src/tally/commands/workflow.py	Shows recurrence tags in workflow help.
tests/test_report.py	Tests stable, unambiguous merchant IDs.
tests/test_cli.py	Tests globs and composite explain output.
tests/test_analyzer.py	Tests determinism, fields, keys, and recurrence.
config/settings.yaml.example	Documents globs, fields, and recurrence tags.
docs/charts.html	Adds the chart guide.
docs/formats.html	Documents globs and report fields.
docs/reference.html	Documents report-field behavior.
docs/index.html	Updates assets and chart navigation.
docs/guide.html	Adds chart navigation.
docs/quickstart.html	Links the chart guide.
docs/sitemap.xml	Adds chart documentation and image URLs.

Suppressed comments (3)

src/tally/spending_report.html:90

• Each month is implemented as a click-only <div>, making month selection unavailable from the keyboard. Render these cells as buttons with an accessible selected state, or provide equivalent focus and Enter/Space handling.
  src/tally/spending_report.html:151
• This element declares role="button" but has neither a tab stop nor keyboard activation; only a JavaScript click listener clears peek mode. Add tabindex="0" plus Enter/Space handling, or use a real button.
  src/tally/spending_report.html:260
• The Transaction Details collapse header is a clickable <div> with no focus or keyboard handling. Use a semantic button, or make it focusable and support Enter/Space while exposing the expanded state.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.