Refresh report and template internals documentation
This commit is contained in:
@@ -1,143 +1,76 @@
|
||||
# Report Registry Internals
|
||||
|
||||
This document describes report identity, valid-period resolution, output
|
||||
naming, artifact grouping, batch command names, and comparison declarations in
|
||||
`internal/report`.
|
||||
`internal/report` owns the registry of report identities and the data declared
|
||||
for each one: resolution, generation mode, prompt identity, comparison policy,
|
||||
artifact group, output-copy name, default module composition, and Distributor
|
||||
path declarations. The public command syntax is owned by the
|
||||
[CLI reference](../cli.md); configuration aliases and overrides are owned by
|
||||
the [configuration reference](../config.md).
|
||||
|
||||
## Purpose
|
||||
## Definitions and resolution
|
||||
|
||||
`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.
|
||||
Each `Definition` declares a stable ID and display name, prompt ID, generation
|
||||
mode, optional template and generated-text schema IDs, valid-period resolver,
|
||||
comparison strategy, artifact group, batch-copy filename, Distributor path
|
||||
templates, generation eligibility, compatible prior IDs, default modules, and
|
||||
batch eligibility flags. `Resolved` combines that definition with the valid
|
||||
period and run metadata for one invocation.
|
||||
|
||||
## Definition Fields
|
||||
| Report ID | Mode | Period policy | Comparison | Registry batch flag | Output copy |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `daily` | Generated text + template | Explicit local civil day | Same valid date | Dynamic Daily inclusion is app-owned | `daily.md` |
|
||||
| `today` | Generated text + template | Selected or current local civil day | Same valid date | Morning | `today.md` |
|
||||
| `tomorrow` | Generated text + template | Next local civil day | Same valid date | Evening | `tomorrow.md` |
|
||||
| `hourly` | Generated text + template | Rolling six-hour interval | Rolling window | — | `hourly.md` |
|
||||
| `three_day` | Scriptorium Markdown | Generation time through the third following local midnight | Same valid date | Morning | `three-day.md` |
|
||||
| `weekend` | Scriptorium Markdown | Upcoming weekend window | Weekend window | Morning | `weekend.md` |
|
||||
| `storm` | Scriptorium Markdown | Caller-supplied event window | Explicit window | — | `storm.md` |
|
||||
|
||||
Each report definition declares:
|
||||
The four generated-text reports pair their report ID with matching template and
|
||||
schema IDs. The three direct-Markdown reports leave both IDs empty. Exact
|
||||
template fields and schema assets belong to [report templates](../templates.md)
|
||||
and [generated-text internals](generatedtext.md).
|
||||
|
||||
- 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
|
||||
All valid periods are half-open. Storm accepts local `YYYY-MM-DDTHH:MM` values
|
||||
in the effective report timezone or offset-bearing RFC3339 values; its end
|
||||
must follow its start. Resolving Weekend directly on Sunday is rejected.
|
||||
|
||||
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`.
|
||||
## Registry collaborators
|
||||
|
||||
`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.
|
||||
`DefaultRegistry` is the only source of the seven report definitions.
|
||||
`Lookup`, `Resolve`, and report-name helpers prevent callers from duplicating
|
||||
report identity rules. Registry overrides clone a definition and replace its
|
||||
module list only after the report ID is recognized.
|
||||
|
||||
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.
|
||||
The definition's `DistributorPathTemplates` are internal declarations consumed
|
||||
by app orchestration. Their rendered external bundle paths and compatibility
|
||||
contract are documented in the [Distributor bundle guide](../integrations/distributor/pkg-bundle.md), not repeated here.
|
||||
|
||||
## Reports
|
||||
`morning` and `evening` are registry-owned batch names. Registry flags declare
|
||||
fixed report eligibility; app orchestration determines data-dependent Daily
|
||||
membership and produces the actual batch plan.
|
||||
|
||||
| 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 |
|
||||
## Module composition and failures
|
||||
|
||||
All report definitions are eligible for generation.
|
||||
Each definition supplies an ordered `[]module.ConfigItem`; the complete
|
||||
report-to-module mapping is maintained in [module internals](module.md).
|
||||
`ArtifactGroup`, `BatchOutputName`, `Generated`, and comparison compatibility
|
||||
are likewise consumed by state and orchestration rather than recomputed there.
|
||||
|
||||
## Valid Periods
|
||||
Unknown report IDs or batch names, an invalid weekend resolution, and invalid
|
||||
storm windows return errors. The registry never collects weather data, builds
|
||||
modules, parses CLI flags, writes state, executes Scriptorium, or delivers a
|
||||
report.
|
||||
|
||||
- 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.
|
||||
## Verification and invariants
|
||||
|
||||
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.
|
||||
Focused tests cover definition completeness, command and alias lookup, period
|
||||
resolution, run IDs, path declarations, composition defaults, and override
|
||||
validation:
|
||||
|
||||
## Boundaries
|
||||
```sh
|
||||
go test ./internal/report
|
||||
```
|
||||
|
||||
`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.
|
||||
All report selection goes through the registry, and the registry is the source
|
||||
of truth for report identity—not rendered report text or app-local constants.
|
||||
|
||||
Reference in New Issue
Block a user