"""The scope spec (ADR-0008): read against the catalogue, with no model involved.""" from pathlib import Path import pytest import yaml from app.providers import load_provider from app.scope import ( APPROVED, ASK, DRAFT, ESSENTIAL, UNDER_REVIEW, Catalogue, FieldSpec, ScopeError, read_scope, render_reading, render_template, slug, ) CATALOGUE = Catalogue( schema_version=1, kinds=("workload", "platform_foundation"), fields={ spec.path: spec for spec in ( FieldSpec( "metadata.customer_case", tier=ESSENTIAL, aliases=("metadata.engagement_id",), ), FieldSpec( "engagement.kind", type="enum", values=("workload", "platform_foundation"), tier=ESSENTIAL, ), FieldSpec("intent.statement", type="text", tier=ESSENTIAL), FieldSpec( "intent.requirements", type="records", keys=("id", "statement"), optional_keys=("category",), ), FieldSpec( "users.count", type="integer", tier={"workload": ESSENTIAL}, question="How many users?", ), FieldSpec( "users.peak", type="integer", tier="important", question="How many at once?", default="a tenth of the users", affects="scaling limits", ), FieldSpec("estate.region", tier="important", question="Which region?"), FieldSpec("network.topology", type="enum", provider_values=True), FieldSpec("delivery.start", type="date"), FieldSpec("run.pre_approved", type="boolean"), ) }, ) COMPLETE = """ metadata: {customer_case: acme-bookings} engagement: {kind: workload} intent: statement: Staff book rooms. requirements: - {id: REQ-01, statement: Rooms can be booked.} users: {count: 400, peak: 40} estate: {region: europe-west2} """ def read(text: str, **options): return read_scope(text, CATALOGUE, **options) def test_a_complete_spec_has_nothing_to_ask(): scope = read(COMPLETE) assert scope.kind == "workload" and scope.customer_case == "acme-bookings" assert scope.statement == "Staff book rooms." assert scope.gaps(ESSENTIAL, "important") == [] assert scope.values["users.count"] == 400 assert ( scope.status() == UNDER_REVIEW and scope.status(pre_approved=True) == APPROVED ) def test_a_field_left_out_or_marked_ask_is_a_gap_with_its_question(): scope = read(COMPLETE.replace("count: 400, peak: 40", "peak: ask")) assert scope.gaps() == [ {"field": "users.count", "prompt": "How many users?", "severity": "HIGH"}, {"field": "users.peak", "prompt": "How many at once?", "severity": "MEDIUM"}, # Optional fields nobody filled are gaps too, the least pressing. *[gap for gap in scope.gaps() if gap["severity"] == "LOW"], ] assert scope.status(pre_approved=True) == DRAFT def test_decide_is_an_assumption_and_not_applicable_is_neither(): scope = read( COMPLETE.replace("peak: 40", "peak: decide").replace( "estate: {region: europe-west2}", "estate: not_applicable" ) ) (assumed,) = scope.assumptions() assert assumed["id"] == "ASSUMP-01" and assumed["field"] == "users.peak" assert "a tenth of the users" in assumed["statement"] assert assumed["impact_if_invalid"] == "Changes scaling limits." # A whole section marked at once covers every field in it. assert scope.states["estate.region"] == "not_applicable" assert all(gap["field"] != "estate.region" for gap in scope.gaps()) def test_which_fields_are_essential_depends_on_the_kind_of_engagement(): foundation = read( COMPLETE.replace("workload", "platform_foundation").replace( "users: {count: 400, peak: 40}", "" ) ) assert foundation.gaps(ESSENTIAL) == [] assert foundation.tier("users.count") == "optional" def test_an_unknown_field_is_named_never_ignored(): with pytest.raises(ScopeError) as refused: read(COMPLETE + "userz: {count: 1}\nestate: {regoin: x}\n") assert "userz is not a field of the scope spec" in refused.value.problems # The second estate key replaced the first; its typo is reported too. assert any("estate.regoin" in problem for problem in refused.value.problems) @pytest.mark.parametrize( ("change", "fault"), [ (("count: 400", "count: many"), "users.count: must be a whole number"), (("kind: workload", "kind: holiday"), "must be one of workload"), ( ("{id: REQ-01, statement: Rooms can be booked.}", "{id: REQ-01}"), "needs statement", ), (("estate: {region: europe-west2}", "estate: europe"), "estate is a section"), ], ) def test_a_value_of_the_wrong_kind_is_refused_with_the_reason(change, fault): with pytest.raises(ScopeError) as refused: read(COMPLETE.replace(*change)) assert any(fault in problem for problem in refused.value.problems) def test_text_that_is_not_yaml_is_refused(): with pytest.raises(ScopeError, match="not valid YAML"): read("intent: [unclosed") with pytest.raises(ScopeError, match="must be a mapping"): read("- just\n- a list\n") def test_a_provider_supplies_the_values_the_catalogue_leaves_to_it(): spec = COMPLETE + "network: {topology: hub_and_spoke}\n" with pytest.raises(ScopeError): read(spec, provider_values={"network.topology": ["flat"]}) allowed = read(spec, provider_values={"network.topology": ["hub_and_spoke"]}) assert allowed.values["network.topology"] == "hub_and_spoke" def test_an_engagement_reference_and_a_customer_case_name_the_same_thing(): by_engagement = read( COMPLETE.replace( "customer_case: acme-bookings", "engagement_id: ENG-2026-UK-084" ) ) assert by_engagement.customer_case == "eng-2026-uk-084" assert slug("ENG 2026/UK 084") == "eng-2026-uk-084" with pytest.raises(ScopeError, match="name the same thing and differ"): read( COMPLETE.replace( "{customer_case: acme-bookings}", "{customer_case: a, engagement_id: b}" ) ) def test_the_completed_copy_holds_every_field_and_the_agents_sections(): scope = read( COMPLETE.replace("peak: 40", "peak: decide") + "delivery: {start: 2026-11-01}\n" ) completed = scope.completed(DRAFT) assert completed["metadata"]["status"] == DRAFT assert completed["users"] == {"count": 400, "peak": "decide"} assert completed["delivery"]["start"] == "2026-11-01" # plain data, not a date assert completed["network"]["topology"] == ASK assert completed["provenance"]["users.count"] == "supplied" assert completed["provenance"]["users.peak"] == "assumed" assert completed["provenance"]["network.topology"] == "unknown" assert completed["readiness"]["supplied"] == len(scope.values) assert completed["inferred_assumptions"][0]["field"] == "users.peak" assert yaml.safe_load(yaml.safe_dump(completed)) == completed def test_a_completed_copy_can_be_read_back_as_a_spec(): """The agent's own sections are replaced, not rejected, on the way back in.""" scope = read(COMPLETE.replace("peak: 40", "peak: decide")) again = read(yaml.safe_dump(scope.completed(DRAFT))) assert again.values == scope.values and again.states == scope.states def test_a_specialist_is_shown_what_is_stated_and_what_is_open(): scope = read( COMPLETE.replace("peak: 40", "peak: decide") + "run: {pre_approved: true}\n" ) context = scope.for_context() assert context["kind"] == "workload" assert context["stated"]["users"] == {"count": 400} assert context["stated"]["intent"]["requirements"][0]["id"] == "REQ-01" assert context["to_decide"][0]["field"] == "users.peak" # How to run the agent, and the case's name, are not the Specialists' business. assert "run" not in context["stated"] and "metadata" not in context["stated"] def test_a_template_and_a_reading_are_written_for_a_person(): template = yaml.safe_load(render_template(CATALOGUE, "workload")) reading = render_reading(read(COMPLETE.replace("count: 400, peak: 40", "peak: 40"))) assert template["engagement"]["kind"] == "workload" assert template["users"] == {"count": ASK, "peak": ASK} assert "delivery" not in template # optional fields are left out of a template assert "Essential, needed before work can start:" in reading assert "users.count: How many users?" in reading # --- the real catalogue and the benchmark spec ------------------------------------------ def test_the_gcp_bundle_reads_the_benchmark_landing_zone_spec(): bundle = load_provider("gcp") text = ( Path(__file__).resolve().parent.parent / "eval" / "datasets" / "specs" / "landing-zone.yaml" ).read_text() scope = read_scope( text, bundle.scope_catalogue(), provider_values=bundle.scope_values ) assert scope.kind == "platform_foundation" assert scope.customer_case == "case-08-landing-zone" # Complete enough to start with nobody to ask. assert scope.gaps(ESSENTIAL) == [] assert scope.values["networking.topology"] == "shared_vpc_hub_and_spoke" assert scope.states["workload.users.count"] == "not_applicable" assert [item["id"] for item in scope.values["intent.requirements"]] == [ "REQ-01", "REQ-02", "REQ-03", "REQ-04", ] def test_every_essential_field_of_the_catalogue_has_a_question_to_ask(): catalogue = load_provider("gcp").scope_catalogue() for kind in catalogue.kinds: for path, spec in catalogue.fields.items(): if spec.tier_for(kind) != "optional": assert spec.question, ( f"{path} is {spec.tier_for(kind)} and has no question" )