Feat: Add a new user pref to display synonym counts in taxon tree

[CarolineDenis]

Fixes #3724

Checklist

• Self-review the PR after opening it to make sure the changes look good and
  self-explanatory (or properly documented)
• Add relevant issue to release milestone
• Add pr to documentation list
• Add automated tests
• Add a reverse migration if a migration is present in the PR
• Add migration function to

  specify7/specifyweb/specify/management/commands/run_key_migration_functions.py

  Line 50 in ea04665

  def fix_schema_config(stdout: WriteToStdOut | None = None):

Testing instructions

• Open the Taxon Tree Viewer.

• Verify that the counts are unchanged from the existing behavior: synonyms used as determinations for collection objects are not included.

• Go to User Preferences.

• Enable the Show counts for synonymized nodes preference in the Taxon Tree section.

• Open the Taxon Tree Viewer.

• Verify that, where applicable, the counts now include a third element showing the count of collection objects for which synonyms are used as determinations.

Summary by CodeRabbit

• New Features
  • Taxon tree statistics can now include counts from synonymized descendants.
  • Added preferences to display synonym counts and choose the taxon query field.
  • Synonym-aware usage details and tooltips are shown for tree and leaf nodes.
• Bug Fixes
  • Synonym-only nodes remain visible when empty nodes are hidden.
• Localization
  • Added English labels and descriptions for synonym counts and taxon query settings.
• Tests
  • Added coverage for tree statistics with and without synonym counts.

[github-actions]

Warning

One or more dependencies are approaching or past End-of-Life.
Please plan upgrades accordingly.

STATUS=OK
NODE_VERSION=24
NODE_CYCLE=24
EOL_DATE=2028-04-30
DAYS_REMAINING=614

--- Node.js ---
Version: 24
EOL: 2028-04-30
Status: OK

STATUS=OK
PYTHON_VERSION=3.12
PYTHON_CYCLE=3.12
EOL_DATE=2028-10-31
DAYS_REMAINING=798

--- Python ---
Version: 3.12
EOL: 2028-10-31
Status: OK

STATUS=WARNING
DJANGO_VERSION=4.2
DJANGO_CYCLE=4.2
EOL_DATE=2026-04-07
DAYS_REMAINING=-140

--- Django ---
Version: 4.2
EOL: 2026-04-07
Status: WARNING

[coderabbitai]

Warning

Review limit reached

Next included review available in 7 seconds.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 76bce973-d3c0-4a50-b7c1-1cf918296ee0

📥 Commits

Reviewing files that changed from the base of the PR and between a129ea0 and 40818c2.

📒 Files selected for processing (3)

• specifyweb/frontend/js_src/lib/components/TreeView/__tests__/formatTreeStats.test.ts
• specifyweb/frontend/js_src/lib/components/TreeView/helpers.ts
• specifyweb/frontend/js_src/lib/localization/preferences.ts

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b6c1606b-9f57-4372-8b71-a2c66e9372d9

📥 Commits

Reviewing files that changed from the base of the PR and between b8d2595 and a129ea0.

📒 Files selected for processing (10)

• specifyweb/backend/trees/stats.py
• specifyweb/backend/trees/views.py
• specifyweb/frontend/js_src/lib/components/Preferences/UserDefinitions.tsx
• specifyweb/frontend/js_src/lib/components/QueryBuilder/fromTree.ts
• specifyweb/frontend/js_src/lib/components/TreeView/Row.tsx
• specifyweb/frontend/js_src/lib/components/TreeView/Tree.tsx
• specifyweb/frontend/js_src/lib/components/TreeView/__tests__/formatTreeStats.test.ts
• specifyweb/frontend/js_src/lib/components/TreeView/helpers.ts
• specifyweb/frontend/js_src/lib/localization/preferences.ts
• specifyweb/frontend/js_src/lib/localization/tree.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Taxon tree statistics can now include counts for synonymized determinations. New preferences select synonym display and the Taxon query field. Tree rendering, empty-node handling, localization, and formatting tests support the new counts.

Changes

Taxon synonym count support

Layer / File(s)	Summary
Backend synonym statistics specifyweb/backend/trees/stats.py, specifyweb/backend/trees/views.py	The statistics endpoint accepts includeSynonymCount. When enabled, it aggregates synonymized determination counts across each child subtree.
Taxon query preferences specifyweb/frontend/js_src/lib/components/Preferences/UserDefinitions.tsx, specifyweb/frontend/js_src/lib/components/QueryBuilder/fromTree.ts	The Taxon tree editor adds showSynonymCounts and queryField preferences. Taxon queries use the selected preferredTaxon or taxon field.
Tree statistics display and validation specifyweb/frontend/js_src/lib/components/TreeView/Tree.tsx, specifyweb/frontend/js_src/lib/components/TreeView/helpers.ts, specifyweb/frontend/js_src/lib/components/TreeView/Row.tsx, specifyweb/frontend/js_src/lib/components/TreeView/__tests__/formatTreeStats.test.ts, specifyweb/frontend/js_src/lib/localization/*.ts	The tree requests, parses, and displays synonym counts. Synonym-only nodes remain visible, and formatting tests cover leaf and internal nodes.

Sequence Diagram(s)

sequenceDiagram
  participant Tree
  participant tree_stats
  participant get_tree_stats
  participant get_synonym_counts
  Tree->>tree_stats: Request taxon stats with includeSynonymCount=true
  tree_stats->>get_tree_stats: Pass include_synonym_count=true
  get_tree_stats->>get_synonym_counts: Aggregate synonym counts by child subtree
  get_synonym_counts-->>get_tree_stats: Return counts keyed by child ID
  get_tree_stats-->>Tree: Return statistics with synonym counts

Loading

Suggested reviewers: grantfitzsimmons

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Testing Instructions	⚠️ Warning	The PR's Testing instructions section contains only template comments; it gives no steps for the changed stats endpoint, preferences, query behavior, or taxon-tree display.	Add reproducible setup and verification steps for the Taxon tree, both preference modes, synonym counts, query-field selection, and the added frontend test command.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes implement accurate synonymized-node and preferred-term record counts in the taxon tree as required by [#3724].
Out of Scope Changes check	✅ Passed	All changes support synonym-aware taxon tree counts, query selection, display, endpoint behavior, or related tests for [#3724].
Automatic Tests	✅ Passed	The PR adds formatTreeStats.test.ts with five Jest cases for leaf/internal synonym counts and tooltips; Jest testMatch discovers this tests/*.test.ts file.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a user preference to display synonym counts in the taxon tree.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-3724-2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[grantfitzsimmons]

I made one minor tweak to improve legibility for the caption that shows when you hover over the counts:

I think the implementation is well-reasoned! Although I wish users could search by either preferred or legal name without configuring preferences, I believe this resolves most issues with a simple preference switch.

• Verify that the preferences appear
• Verify that the counts are accurate to what they claim
• Verify that the search preference is respected

[g1rly-c0d3r]

Testing instructions

• Verify that the counts are unchanged from the existing behavior: synonyms used as determinations for collection objects are not included.
• Verify that, where applicable, the counts now include a third element showing the count of collection objects for which synonyms are used as determinations.

---

Once checked, nodes now have an additional count for synonyms.

[kwhuber]

Testing instructions

• Verify that the counts are unchanged from the existing behavior: synonyms used as determinations for collection objects are not included.
• Verify that, where applicable, the counts now include a third element showing the count of collection objects for which synonyms are used as determinations.