1414import types
1515from datetime import datetime , timedelta , timezone
1616from decimal import Decimal
17- from pathlib import Path
1817from typing import Annotated , Any , Literal , Union , get_args , get_origin , get_type_hints
1918
2019import pyarrow as pa
2726from vgi .reporting import CONTRACT_MODULES , PROTOCOLS
2827from vgi .reporting ._metadata import FetchedColumn , SqlRead , read_annotation
2928from vgi .reporting .alerts import Instance
30- from vgi .reporting .common import Delegation , DelegationRecord , Trigger
29+ from vgi .reporting .common import Delegation , DelegationRecord , Notification , Trigger
30+ from vgi .reporting .notify import ChannelInfo
3131from vgi .reporting .reports import FolderRecord , ReportEnvelope , ReportRow , ReportsProtocol , RevisionRow
32+ from vgi .reporting .schedules import Schedule , ScheduleRecord , SchedulerInfo
3233from vgi .reporting .sql_tasks import SqlTask
3334
3435_RECORDS = [
4142 and issubclass (obj , ArrowSerializableDataclass )
4243]
4344_NAMES = {
44- "vgi.reports.v1" : 17 ,
45- "vgi.reports.ownership.v1" : 1 ,
46- "vgi.report_render.v1" : 4 ,
47- "vgi.schedules.v1" : 16 ,
48- "vgi.sql_tasks.v1" : 17 ,
49- "vgi.alerts.v1" : 18 ,
50- "vgi.notify.v1" : 4 ,
51- "vgi.delegations.v1" : 3 ,
45+ "vgi.reports.v1" : 19 ,
46+ "vgi.objects.v1" : 19 ,
47+ "vgi.ownership.v1" : 3 ,
48+ "vgi.resource_identity.v1" : 5 ,
49+ "vgi.schedules.v2" : 24 ,
50+ "vgi.reports.ownership.v1" : 2 ,
51+ "vgi.report_render.v1" : 5 ,
52+ "vgi.schedules.v1" : 24 ,
53+ "vgi.sql_tasks.v1" : 25 ,
54+ "vgi.alerts.v1" : 25 ,
55+ "vgi.notify.v1" : 7 ,
56+ "vgi.delegations.v1" : 5 ,
5257}
53- _ROOT = Path (__file__ ).resolve ().parents [1 ]
5458
5559
5660def _sample (annotation : Any , * , nulls : bool ) -> Any :
@@ -112,7 +116,7 @@ def test_protocol_inventory_and_envelopes() -> None:
112116 """All seven independent interfaces are recognized by the actual RPC framework."""
113117 assert {p .protocol_name : len (rpc_methods (p )) for p in PROTOCOLS } == _NAMES
114118 for protocol in PROTOCOLS :
115- assert protocol .protocol_version == " 1.0.0"
119+ assert protocol .protocol_version == ( "2.0.0" if protocol . protocol_name . endswith ( ".v2" ) else " 1.0.0")
116120 for name , method in rpc_methods (protocol ).items ():
117121 assert method .protocol_name == protocol .protocol_name
118122 assert method .params_schema .names == list (method .param_types )
@@ -126,11 +130,43 @@ def test_protocol_inventory_and_envelopes() -> None:
126130 assert len (annotation .row_type .ARROW_SCHEMA ) > 0
127131
128132
133+ def test_html_body_extension_reads_older_records () -> None :
134+ """Absent optional fields keep old persisted notifications and capabilities readable."""
135+ original = _sample (Notification , nulls = True )
136+ batch , metadata = deserialize_record_batch (original .serialize_to_bytes ())
137+ legacy = batch .select ([name for name in batch .schema .names if name != "body_html" ])
138+ assert Notification .deserialize_from_batch (legacy , metadata ) == original
139+ channel = ChannelInfo (kind = "email" , enabled = True , images = False , threads = False , limits = [])
140+ batch , metadata = deserialize_record_batch (channel .serialize_to_bytes ())
141+ legacy = batch .select ([name for name in batch .schema .names if name != "html_body" ])
142+ assert ChannelInfo .deserialize_from_batch (legacy , metadata ).html_body is False
143+
144+
145+ def test_schedule_alert_extension_reads_older_records () -> None :
146+ """Existing saved schedules and replay results survive the additive alert fields."""
147+ original = dataclasses .replace (_sample (ScheduleRecord , nulls = True ), issues = [])
148+ batch , metadata = deserialize_record_batch (original .serialize_to_bytes ())
149+ legacy = batch .select (
150+ [name for name in batch .schema .names if name not in {"issues" , "last_successful_at" , "last_delivery_at" }]
151+ )
152+ index = legacy .schema .get_field_index ("definition" )
153+ old_type = pa .struct ([f for f in Schedule .ARROW_SCHEMA if f .name != "alerts" ])
154+ definitions = legacy .column (index ).to_pylist ()
155+ for definition in definitions :
156+ del definition ["alerts" ]
157+ legacy = legacy .set_column (index , pa .field ("definition" , old_type , nullable = False ), pa .array (definitions , old_type ))
158+ assert ScheduleRecord .deserialize_from_batch (legacy , metadata ) == original
159+ info = dataclasses .replace (_sample (SchedulerInfo , nulls = True ), alert_events = [])
160+ batch , metadata = deserialize_record_batch (info .serialize_to_bytes ())
161+ legacy = batch .select ([name for name in batch .schema .names if name != "alert_events" ])
162+ assert SchedulerInfo .deserialize_from_batch (legacy , metadata ) == info
163+
164+
129165def test_every_effectful_request_has_a_request_id () -> None :
130166 """Mutation admission always has a stable ID, including transfer and recovery methods."""
131167 for protocol in PROTOCOLS :
132168 for name , method in rpc_methods (protocol ).items ():
133- if name .startswith (("get_" , "list_" , "check_" , "preview_" , "test_" , "find_" )):
169+ if name .startswith (("get_" , "list_" , "check_" , "preview_" , "test_" , "find_" , "scan_" , "validate_" )):
134170 continue
135171 schema = method .params_schema
136172 assert schema .field ("request_id" ) == pa .field ("request_id" , pa .string (), nullable = False )
@@ -141,7 +177,9 @@ def test_sql_annotations_exclude_mutations_and_tests() -> None:
141177 for protocol in PROTOCOLS :
142178 for name in rpc_methods (protocol ):
143179 annotation = read_annotation (getattr (protocol , name ))
144- assert (annotation is not None ) == name .startswith (("get_" , "list_" , "check_" , "preview_" ))
180+ assert (annotation is not None ) == name .startswith (
181+ ("get_" , "list_" , "check_" , "preview_" , "find_" , "scan_" )
182+ )
145183 annotation = read_annotation (ReportsProtocol .list_reports )
146184 assert annotation is not None
147185 assert annotation .fetched_columns == (
@@ -213,7 +251,7 @@ def test_direct_arguments_and_required_nullable_fields() -> None:
213251
214252
215253def test_folder_placement_and_browsing_contract () -> None :
216- """Root is nullable, location is not revisioned, and recursive defaults retain whole-library SQL views ."""
254+ """Browsing selects direct children while explicit SQL scans retain whole-library semantics ."""
217255 assert ReportRow .ARROW_SCHEMA .field ("folder_id" ) == pa .field ("folder_id" , pa .string (), nullable = True )
218256 assert FolderRecord .ARROW_SCHEMA .field ("parent_folder_id" ) == pa .field (
219257 "parent_folder_id" , pa .string (), nullable = True
@@ -225,10 +263,13 @@ def test_folder_placement_and_browsing_contract() -> None:
225263 for method_name , selector in (("list_reports" , "folder_id" ), ("list_folders" , "parent_folder_id" )):
226264 method = methods [method_name ]
227265 assert method .param_defaults [selector ] is None
228- assert method .param_defaults ["recursive" ] is True
266+ assert method .param_defaults ["recursive" ] is False
229267 assert method .params_schema .field (selector ) == pa .field (selector , pa .string (), nullable = True )
230268 annotation = read_annotation (ReportsProtocol .list_folders )
231- assert annotation is not None and annotation .table == "folders" and annotation .row_type is FolderRecord
269+ assert annotation is not None and annotation .table is None and annotation .row_type is FolderRecord
270+ scan = read_annotation (ReportsProtocol .scan_folders )
271+ assert scan is not None and scan .table == "folders"
272+ assert methods ["scan_folders" ].param_defaults ["recursive" ] is True
232273 # Moving to root must be explicit; omitting a nullable destination cannot silently move an object.
233274 for method_name , selector in (("move_report" , "folder_id" ), ("update_folder" , "parent_folder_id" )):
234275 method = methods [method_name ]
@@ -241,11 +282,15 @@ def test_folder_placement_and_browsing_contract() -> None:
241282
242283
243284@pytest .mark .parametrize (("record" , "relative" ), targets ())
244- def test_generated_reference_is_current_and_deterministic (record : str , relative : str ) -> None :
245- """Checking in changed Python without its generated reference fails locally and in CI ."""
285+ def test_generated_reference_is_complete_and_deterministic (record : str , relative : str ) -> None :
286+ """Validate generation without requiring draft design artifacts in the commit ."""
246287 expected = render (record )
247288 assert expected == render (record )
248- assert (_ROOT / relative ).read_text () == expected
289+ assert expected .startswith ("# " )
290+ assert "Generated by vgi.codegen.reporting_docs" in expected
291+ assert relative .endswith (".md" )
292+ if record != "index" :
293+ assert "## Python definitions" in expected
249294
250295
251296def test_invalid_fetched_column_mapping_fails_generation (monkeypatch : pytest .MonkeyPatch ) -> None :
0 commit comments