Module clock_report 

OA.16: clocked time, rolled up an outline — the report scan-view-clockreport-mode renders over any scan view whose source reports clock spans. OA.16 — the clock report: clocked time, rolled up an outline.

Design: docs/dev/architecture/org-agenda.md §3. Slice plan: org-agenda.md.

Emacs calls this a clocktable, and org-agenda-clockreport-mode puts one at the top of the agenda. It answers “where did the week go”, which is a different question from “what should I do next” — and that is why it is a REPORT over the scan’s clock spans rather than a view of the agenda’s rows.

Totals roll UP, and that is the whole shape

A span is filed against the headline it was clocked on. A report that listed only those would answer “which leaf did I clock” and never “how long did the project take”, which is the question anyone opens a clocktable for. So every span contributes to each of its ancestors as well as to itself.

[ClockSpan::outline] carries the whole chain precisely because of this: an ancestor that logged no time of its own emits no span at all, so the chain is the only way to name it. Rebuilding the tree from leaf names plus levels would invent a parent for every orphan and mis-nest two projects that happen to share a child name.

Own time versus total time

Both are kept. total is what rolls up; own is what was clocked on that headline itself. A tree showing only totals cannot distinguish a project whose time is all in its children from one where half was spent on the parent, and that difference is usually the interesting part of the report.

The range is a display choice, not a scan

Spans are held per view unfiltered (see ScanViewState::clock), so switching the report between a day, a week and a year filters data already in hand. Re-walking the corpus to answer a question the data contains would make a toggle cost a scan.

Structs

ClockReport

A whole report: its rows in outline order, and the grand total.

ClockReportElementIds

The interned ids the report’s rows paint with, captured once when the mode activates so collect() is an array-index resolve rather than a name lookup per row.

ClockReportProvider

Renders a ClockReport as virtual rows above line 0 of a scan view.

ClockReportRegistration

Removes the view’s report when the mode deactivates.

ReportRow

One line of the report: a headline, its depth, and its two totals.

ScanViewClockReportMode

OA.16 — scan-view-clockreport-mode: the clock report, on a scan view.

Constants

ELEM_CLOCKREPORT

Element name: the clock report’s own rows.

ELEM_CLOCKREPORT_TOTAL

Element name: the report’s total line, which is the row people look at.

TOGGLE_ACTION

The keymap target cr fires.

Functions

build

Build a report from spans, keeping only those filed in days.

clock_report_provider_id

The ProviderId a view’s clock report registers under.

format_minutes

H:MM, org’s own clocktable spelling.

register_clock_report_actions

Register the cr target. Unlike refreshable-view-mode’s dead body, this one is the behaviour: the effect carries a mode name and nothing else, so there is no per-buffer state to read and no handler contribution to forget.

register_clock_report_theme_elements

Register the report’s two theme elements and return their interned ids.