246 lines
8.6 KiB
Python
246 lines
8.6 KiB
Python
"""The scope spec (ADR-0008): read against the catalogue, with no model involved."""
|
|
|
|
import pytest
|
|
import yaml
|
|
|
|
from execution_engine.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
|