Files
tom_analysis_agent/app/operating_model/chain.py

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
}