Feature/project summary view

[loganthomas]

Thank you to the maintainers for creating and maintaining this wonderful package! I've been using utt for time tracking and found myself frequently wanting a quick overview of project time allocation without the full report details. This PR adds that functionality.

Add project-summary command for quick project time overview

Summary

This PR adds a new project-summary command that displays projects sorted by time spent (most time first) with a clean, aligned format. This provides a quick way to see time allocation across projects without the full detail of the standard report command.

Motivation

I often want a quick overview of how much time I've spent on each project without needing to see all the activities, breaks, and detailed breakdowns. The project-summary command fills this gap by showing only:

• Project names
• Total time per project
• Overall total time
• Projects sorted by duration (most time first)

Usage Examples

I tried to mirror report as much as possilble so the same functionality should exit with project-summary

$ poetry run utt project-summary --help                        
usage: utt project-summary [-h] [--show-perc] [--current-activity CURRENT_ACTIVITY] [--no-current-activity] [--from FROM_DATE] [--to TO_DATE] [--project PROJECT] [--month [MONTH]] [--week [WEEK]] [date]

Show projects sorted by time spent

positional arguments:
  date

options:
  -h, --help            show this help message and exit
  --show-perc           Show percentage of total time for each project
  --current-activity CURRENT_ACTIVITY
                        Set the current activity
  --no-current-activity
                        Do not display the current activity
  --from FROM_DATE      Specify an inclusive start date to report.
  --to TO_DATE          Specify an inclusive end date to report. If this is a day of the week, then it is the next occurrence from the start date of the report, including the start date itself.
  --project PROJECT     Show activities only for the specified project.
  --month [MONTH]       Specify a month. Allowed formats include, '2019-10', 'Oct', 'this' 'prev'. The report will start on the first day of the month and end on the last. '--from' or '--to' if present will override start and end, respectively. If the
                        month is the current month, 'today' will be the last day of the report.
  --week [WEEK]         Specify a week. Allowed formats include, 'this' 'prev', or week number. The report will start on the first day of the week (Monday) and end on the last (Sunday). '--from' or '--to' if present will override start and end,
                        respectively. If the week is the current week, 'today' will be the last day of the report.

Basic usage (today's projects)

$ utt project-summary

------------------------------- Project Summary --------------------------------

backend : 5h30
frontend: 3h15
devops  : 1h45

Total   : 10h30

Specific date

$ utt project-summary 2014-03-19

------------------------------- Project Summary --------------------------------

asd : 3h15
    : 1h00
qwer: 0h45
A   : 0h30

Total: 5h30

With current activity

$ utt project-summary

------------------------------- Project Summary --------------------------------

backend : 5h30
frontend: 3h15
devops  : 1h45
-- Current Activity --: 2h15

Total   : 12h45

Date range

$ utt project-summary --from 2025-01-15 --to 2025-01-19

------------------------------- Project Summary --------------------------------

backend : 18h45
frontend: 12h30
devops  : 8h15
meetings: 3h00

Total   : 42h30

Show percentages

$ utt project-summary --from 2024-01-15 --to 2024-01-19 --show-perc

------------------------------- Project Summary --------------------------------

backend : 18h45 ( 44.1%)
frontend: 12h30 ( 29.4%)
devops  : 8h15  ( 19.4%)
meetings: 3h00  (  7.1%)

Total   : 42h30 (100.0%)

Testing Notes

I've done my best to test this thoroughly:

• Created 9 unit tests covering various scenarios and edge cases
• Added an integration test using existing test data
• Verified all existing tests still pass
• Manually tested with real usage scenarios

Please let me know if you'd like me to add any additional tests or make any changes!

[larose]

Hi @loganthomas, thanks for the contribution!

My first question is: could this be a plugin you publish externally? (I'd be happy to link to it.)

You'd likely need to inject ReportModel and process the projects from there (though it's been a while since I looked at the code in detail). The project duration is currently only available as a string, but we could update it to expose a timedelta if needed.

My goal is to keep utt lightweight, while allowing users to extend it through plugins for their particular use cases (like yours).

What do you think?

[loganthomas]

Sure thing. Sorry, I misunderstood that plugins are external. I'll work on moving this out and let you know when complete. Thanks!

[loganthomas]

Closing for #136