144 lines
6.2 KiB
Markdown
144 lines
6.2 KiB
Markdown
# Report Registry Internals
|
|
|
|
This document describes report identity, valid-period resolution, output
|
|
naming, artifact grouping, batch command names, and comparison declarations in
|
|
`internal/report`.
|
|
|
|
## Purpose
|
|
|
|
`internal/report` is the canonical source for report definitions, public
|
|
command names, config-key aliases, and batch command names. App, config, state,
|
|
module building, and CLI wiring consume report-owned helpers and resolved
|
|
definitions instead of owning report identity policy themselves.
|
|
|
|
## Definition Fields
|
|
|
|
Each report definition declares:
|
|
|
|
- report ID and display name
|
|
- Scriptorium prompt ID
|
|
- generation mode
|
|
- valid-period resolver
|
|
- comparison strategy
|
|
- managed artifact group
|
|
- batch output copy filename
|
|
- generated-report eligibility
|
|
- prior-report compatibility list
|
|
- default ordered module composition
|
|
|
|
Report-owned helpers map public command names and config keys to report IDs.
|
|
The generate command names are `daily`, `today`, `tomorrow`, `hourly`,
|
|
`three-day`, `weekend`, and `storm`. Config keys also accept selected
|
|
underscore and descriptive aliases such as `three_day_outlook`,
|
|
`weekend_outlook`, and `storm_report`.
|
|
|
|
`daily` resolves to the dated Daily Report ID `daily`. `today` resolves to the
|
|
independent Today report ID `today`. `reports.today` is not an alias for
|
|
`reports.daily`, and retired report keys are not supported.
|
|
|
|
Markdown report definitions use the `scriptorium_markdown` generation mode.
|
|
Their template and structured-text schema identifiers are empty. Daily Report,
|
|
Today Report, Tomorrow Report, and Hourly Report declare
|
|
`generated_text_template`; the app uses their template and schema identifiers
|
|
to validate generated text and render embedded Markdown templates.
|
|
|
|
## Reports
|
|
|
|
| Report | ID | Prompt | Generation mode | Artifact group | Batch copy | Prior compatibility |
|
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
| Daily Report | `daily` | `weather.daily_generated_text` | `generated_text_template` | `daily` | `daily.md` | Daily Report |
|
|
| Today Report | `today` | `weather.today_generated_text` | `generated_text_template` | `today` | `today.md` | Today Report |
|
|
| Tomorrow Report | `tomorrow` | `weather.tomorrow_generated_text` | `generated_text_template` | `tomorrow` | `tomorrow.md` | Tomorrow Report |
|
|
| Hourly Report | `hourly` | `weather.hourly_generated_text` | `generated_text_template` | `hourly` | `hourly.md` | Hourly Report |
|
|
| 3-Day Outlook | `three_day` | `weather.three_day_outlook` | `scriptorium_markdown` | `three-day` | `three-day.md` | 3-Day Outlook |
|
|
| Weekend Outlook | `weekend` | `weather.weekend_outlook` | `scriptorium_markdown` | `weekend` | `weekend.md` | Weekend Outlook |
|
|
| Storm Report | `storm` | `weather.storm_report` | `scriptorium_markdown` | `storm` | `storm.md` | Storm Report |
|
|
|
|
All report definitions are eligible for generation.
|
|
|
|
## Valid Periods
|
|
|
|
- Daily Report covers the selected local civil day and requires an explicit
|
|
date.
|
|
- Today Report covers the selected local civil day, or the current local civil
|
|
day when no date override is supplied.
|
|
- Tomorrow Report covers the next local civil day from generation time.
|
|
- Hourly Report covers the half-open six-hour period from generation time in
|
|
the effective report timezone. The duration is an internal report constant,
|
|
not a configuration field.
|
|
- 3-Day Outlook covers the interval from generation time through local midnight
|
|
three days later.
|
|
- Weekend Outlook covers the upcoming weekend window.
|
|
- Storm Report covers an explicit event window supplied by the caller.
|
|
|
|
Storm event windows can be parsed from local `YYYY-MM-DDTHH:MM` timestamps in
|
|
the configured timezone or RFC3339 timestamps with explicit offsets. End time
|
|
must be after start time.
|
|
|
|
## Boundaries
|
|
|
|
`internal/report` defines report metadata, public report names, batch command
|
|
names, output naming, and time coverage. It does not collect weather data, plan
|
|
batch membership, build module values, compare snapshot contents, write state,
|
|
parse CLI flags, or invoke Scriptorium.
|
|
|
|
The CLI parses flags and command structure, then uses report-owned helpers for
|
|
report and batch command names. Config loading uses report-owned helpers for
|
|
report override keys.
|
|
|
|
## Config Fields Used
|
|
|
|
The app supplies `weather_api.timezone` as a loaded `time.Location`. Batch
|
|
output path copying uses batch output names from report definitions. Report
|
|
module overrides can use short keys such as `daily`, `today`, `tomorrow`, and
|
|
`hourly`, or descriptive names such as `three_day_outlook`.
|
|
|
|
## Batch Commands
|
|
|
|
`internal/report` owns the public batch command names `morning` and `evening`
|
|
and validates them through `BatchForCommandName`. Data-dependent batch
|
|
membership is owned by `internal/app`, because it depends on collected hourly
|
|
forecast coverage.
|
|
|
|
Report definitions still declare default batch output copy filenames. App
|
|
batch planning uses those filenames for fixed report entries and supplies
|
|
date-qualified names for dynamic Daily entries.
|
|
|
|
## State And App Usage
|
|
|
|
- State paths use `ArtifactGroup`.
|
|
- Batch output copies use `BatchOutputName`.
|
|
- Generation checks `Generated`.
|
|
- Module composition defaults use `Modules`.
|
|
- Prior lookup checks `CompatiblePriorIDs` and the comparison strategy.
|
|
- RunIDs include the resolved report ID.
|
|
|
|
## Failure Behavior
|
|
|
|
- Unknown report IDs and batch names return actionable errors.
|
|
- Weekend Outlook resolution returns an error when resolved directly on Sunday.
|
|
- Storm Report resolution requires start and end, with end after start.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/report/period_test.go`
|
|
- `internal/app/app_test.go`
|
|
- `internal/cli/root_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Report selection goes through the registry.
|
|
- Public command names, config-key aliases, and batch command names are owned
|
|
by `internal/report`.
|
|
- Direct Markdown reports have empty template and generated-text schema IDs.
|
|
- Generated-text-template reports declare prompt, template, and schema IDs in
|
|
their report definition.
|
|
- Valid periods are half-open intervals independent of rendered report text.
|
|
- Artifact grouping, batch output filenames, generated-report eligibility,
|
|
default module composition, comparison compatibility, and comparison strategy
|
|
are declared by report definition.
|
|
- App-owned batch planning uses report definitions but does not live in the
|
|
report registry.
|