241 lines
9.4 KiB
Python
241 lines
9.4 KiB
Python
"""The data files along the chain, and what each must hold.
|
|
|
|
operational-requirements.json what running the solution must achieve, each
|
|
traced to what the customer stated
|
|
capabilities.json what the operating organisation must be able to
|
|
do, each serving requirements and covering Items
|
|
target-operating-model.json who does it (see graph.py)
|
|
verdicts.json the verdict on each Check
|
|
|
|
Each checker returns what is wrong, one entry per fault, so a Specialist can fix it
|
|
and submit again. `upstream` is the Deliverables a submission builds on, by kind.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
from collections.abc import Callable, Mapping, Sequence
|
|
from typing import Any
|
|
|
|
from app.operating_model import spec
|
|
from app.operating_model.catalogue import Catalogue
|
|
from app.operating_model.names import (
|
|
CAPABILITIES_FILE,
|
|
CAPABILITY_MODEL,
|
|
CUSTOM,
|
|
HOURS,
|
|
OPERATIONAL_REQUIREMENTS,
|
|
REQUIREMENTS_FILE,
|
|
wider,
|
|
)
|
|
from app.operating_model.spec import Upstream
|
|
|
|
REQUIREMENT_KINDS = (
|
|
"service_level",
|
|
"process",
|
|
"organisation",
|
|
"tooling",
|
|
"compliance",
|
|
)
|
|
DataCheck = Callable[[Mapping[str, str], Upstream | None], list[str]]
|
|
|
|
|
|
def objects(text: str, name: str) -> tuple[list[dict[str, Any]], list[str]]:
|
|
"""The file's entries, and what is wrong with it as a list of objects with ids."""
|
|
try:
|
|
data = json.loads(text)
|
|
except ValueError as exc:
|
|
return [], [f"{name}: not valid JSON ({exc})"]
|
|
if not isinstance(data, list):
|
|
return [], [f"{name}: must be a JSON list"]
|
|
problems = [
|
|
f"{name}[{index}]: must be an object with an id"
|
|
for index, item in enumerate(data)
|
|
if not isinstance(item, dict) or not str(item.get("id") or "").strip()
|
|
]
|
|
accepted = [
|
|
item
|
|
for item in data
|
|
if isinstance(item, dict) and str(item.get("id") or "").strip()
|
|
]
|
|
seen = [str(item["id"]) for item in accepted]
|
|
problems += [
|
|
f"{name}: id {identifier} is used more than once"
|
|
for identifier in sorted({i for i in seen if seen.count(i) > 1})
|
|
]
|
|
return accepted, problems
|
|
|
|
|
|
def read(upstream: Upstream | None, kind: str, name: str) -> list[dict[str, Any]]:
|
|
"""An upstream data file's entries; none when it is absent or unreadable."""
|
|
text = ((upstream or {}).get(kind) or {}).get("attachments", {}).get(name, "")
|
|
return objects(text, name)[0] if text else []
|
|
|
|
|
|
def requirements(upstream: Upstream | None) -> list[dict[str, Any]]:
|
|
return read(upstream, OPERATIONAL_REQUIREMENTS, REQUIREMENTS_FILE)
|
|
|
|
|
|
def capabilities(upstream: Upstream | None) -> list[dict[str, Any]]:
|
|
return read(upstream, CAPABILITY_MODEL, CAPABILITIES_FILE)
|
|
|
|
|
|
def _strings(item: Mapping[str, Any], field: str) -> list[str]:
|
|
found = item.get(field)
|
|
return [str(entry) for entry in found] if isinstance(found, list) else []
|
|
|
|
|
|
def check_requirements(
|
|
attachments: Mapping[str, str], upstream: Upstream | None
|
|
) -> list[str]:
|
|
"""Every Operational requirement is traced to what the customer stated, and
|
|
everything they stated that binds is carried by one."""
|
|
name = REQUIREMENTS_FILE
|
|
entries, problems = objects(attachments[name], name)
|
|
if not entries and not problems:
|
|
return [f"{name}: lists no Operational requirements"]
|
|
scope = spec.agreed(upstream)
|
|
stated = set(spec.ids(spec.stated_requirements(scope)))
|
|
# A business outcome may be what a requirement comes from. It need not be: what
|
|
# shows each outcome is served is a Measure, checked on the operating model.
|
|
outcomes = set(spec.ids(spec.business_outcomes(scope)))
|
|
kept_true = set(spec.ids(spec.conditions(scope)))
|
|
named: set[str] = set()
|
|
for entry in entries:
|
|
where = f"{name}: {entry['id']}"
|
|
if not str(entry.get("statement") or "").strip():
|
|
problems.append(f"{where} needs a statement")
|
|
if entry.get("kind") not in REQUIREMENT_KINDS:
|
|
problems.append(
|
|
f"{where}: kind must be one of {', '.join(REQUIREMENT_KINDS)}"
|
|
)
|
|
sources = _strings(entry, "source")
|
|
if not sources:
|
|
problems.append(
|
|
f"{where} has no source: name the stated requirement, the Condition "
|
|
"or the field of the operating spec it comes from"
|
|
)
|
|
for source in sources:
|
|
named.add(source)
|
|
known = (
|
|
source in stated
|
|
or source in outcomes
|
|
or source in kept_true
|
|
or spec.settled(scope, source)
|
|
)
|
|
if scope and not known:
|
|
problems.append(
|
|
f"{where}: source {source} is not a stated requirement, a "
|
|
"Condition or a settled field of the operating spec"
|
|
)
|
|
if scope:
|
|
problems += [
|
|
f"{name}: the customer's requirement {identifier} is carried by no "
|
|
"Operational requirement"
|
|
for identifier in sorted(stated - named)
|
|
]
|
|
problems += [
|
|
f"{name}: the customer stated {path}, and no Operational requirement "
|
|
"names it as a source"
|
|
for path in spec.binding(scope)
|
|
if path not in named
|
|
]
|
|
return problems
|
|
|
|
|
|
def check_capabilities(catalogue: Catalogue) -> DataCheck:
|
|
"""Every Capability comes from the catalogue, serves a requirement and covers
|
|
Items; every Item is covered and every requirement served."""
|
|
|
|
def check(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]:
|
|
name = CAPABILITIES_FILE
|
|
entries, problems = objects(attachments[name], name)
|
|
if not entries and not problems:
|
|
return [f"{name}: lists no Capabilities"]
|
|
scope = spec.agreed(upstream)
|
|
known_items = set(spec.ids(spec.items(scope)))
|
|
known_requirements = {str(r["id"]) for r in requirements(upstream)}
|
|
support = spec.value(scope, "operations.support_hours")
|
|
covered: set[str] = set()
|
|
served: set[str] = set()
|
|
for entry in entries:
|
|
where = f"{name}: {entry['id']}"
|
|
entry_id = entry.get("catalogue")
|
|
listed = catalogue.entries.get(str(entry_id))
|
|
if entry_id == CUSTOM:
|
|
if not str(entry.get("reason") or "").strip():
|
|
problems.append(f"{where} is custom and gives no reason")
|
|
if not str(entry.get("name") or "").strip():
|
|
problems.append(f"{where} is custom and needs a name")
|
|
elif listed is None:
|
|
problems.append(
|
|
f"{where}: {entry_id!r} is not in the capability catalogue; "
|
|
f"use an entry's id, or {CUSTOM} with a reason"
|
|
)
|
|
serves, on = _strings(entry, "serves"), _strings(entry, "items")
|
|
if not serves:
|
|
problems.append(f"{where} serves no Operational requirement")
|
|
served.update(serves)
|
|
covered.update(on)
|
|
if upstream is not None:
|
|
problems += [
|
|
f"{where} serves {identifier}, which is not an Operational requirement"
|
|
for identifier in serves
|
|
if identifier not in known_requirements
|
|
]
|
|
problems += [
|
|
f"{where} covers {identifier}, which is not an Item of the operating spec"
|
|
for identifier in on
|
|
if identifier not in known_items
|
|
]
|
|
hours = entry.get("hours")
|
|
if hours not in HOURS:
|
|
problems.append(f"{where}: hours must be one of {', '.join(HOURS)}")
|
|
elif (
|
|
listed is not None
|
|
and listed.follows_support_hours
|
|
and support in HOURS
|
|
and wider(str(support), str(hours))
|
|
):
|
|
problems.append(
|
|
f"{where}: faults are responded to {support}, and {listed.name} "
|
|
f"is staffed only {hours}"
|
|
)
|
|
effort = entry.get("effort_hours_per_month")
|
|
if (
|
|
isinstance(effort, bool)
|
|
or not isinstance(effort, (int, float))
|
|
or effort <= 0
|
|
):
|
|
problems.append(
|
|
f"{where}: effort_hours_per_month must be a number above zero"
|
|
)
|
|
if not str(entry.get("basis") or "").strip():
|
|
problems.append(f"{where} needs a basis for its effort")
|
|
if upstream is not None:
|
|
problems += [
|
|
f"{name}: Item {identifier} is covered by no Capability"
|
|
for identifier in sorted(known_items - covered)
|
|
]
|
|
problems += [
|
|
f"{name}: Operational requirement {identifier} is served by no Capability"
|
|
for identifier in sorted(known_requirements - served)
|
|
]
|
|
return problems
|
|
|
|
return check
|
|
|
|
|
|
def names_of(
|
|
capabilities_list: Sequence[Mapping[str, Any]], catalogue: Catalogue
|
|
) -> dict[str, str]:
|
|
"""Each Capability's name: its catalogue entry's, or its own when it is custom."""
|
|
return {
|
|
str(entry["id"]): (
|
|
catalogue.entries[str(entry.get("catalogue"))].name
|
|
if str(entry.get("catalogue")) in catalogue.entries
|
|
else str(entry.get("name") or entry["id"])
|
|
)
|
|
for entry in capabilities_list
|
|
}
|