The reference agent's subject, cloud solution architecture, as an agent in the operating model agent's pattern: the Execution engine (from orchestration_engine) and one Workflow in app/solution_architecture, built for the settings and provider bundle by assembly.workflow_for. Copied from gcp_solution_architecture_agent at 8b397cd without its own engine: its role files, Skills, provider bundle, ADRs, vocabulary, scripts and evaluation datasets. The image takes the engine from a named build context and installs Terraform. It is called through the Orchestration engine, and its files are what the operating model agent digests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
170 lines
6.5 KiB
Python
170 lines
6.5 KiB
Python
"""A review of the Target architecture against the provider's schema, in code.
|
|
|
|
A Check that names a setting its Element's resource type does not have cannot be met
|
|
by any code. Left alone it costs a whole Revision: the code's author finds it, the
|
|
design is reopened, and everything after it is done again. In the run of 2026-10-07
|
|
that happened twice, with a schema lookup available to the Specialist that wrote the
|
|
Checks.
|
|
|
|
This reads the settings each Check names and looks them up, so the design is told
|
|
before it is submitted. It is a review, not a rule: a Check is prose, and a word that
|
|
looks like a setting may be a value. What it raises is returned once.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import difflib
|
|
import logging
|
|
import re
|
|
from collections.abc import Mapping, Sequence
|
|
from typing import Any
|
|
|
|
from execution_engine.adk.runtime import ToolResult
|
|
|
|
from app.solution_architecture.kinds import DeliverableKind
|
|
from app.solution_architecture.local import TerraformRunner
|
|
from app.solution_architecture.target_architecture import (
|
|
GRAPH_ATTACHMENT,
|
|
GraphError,
|
|
parse_graph,
|
|
)
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
_QUOTED = re.compile(r"\"[^\"]*\"|'[^']*'")
|
|
_CODE = re.compile(r"`([^`]+)`")
|
|
# snake_case with at least one underscore, or a dotted path of lower-case names.
|
|
_NAME = re.compile(
|
|
r"(?<![\w/.\-])"
|
|
r"([a-z][a-z0-9]*(?:_[a-z0-9]+)+(?:\.[a-z][a-z0-9_]*)*"
|
|
r"|[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+)"
|
|
r"(?![\w/\-])"
|
|
)
|
|
_PATH = re.compile(r"^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$")
|
|
# Values a Check may put in backticks. `true` and `false` were raised as missing
|
|
# settings in a run of 2026-10-10.
|
|
_LITERALS = frozenset({"true", "false", "null", "none"})
|
|
|
|
|
|
def named_settings(statement: str) -> tuple[str, ...]:
|
|
"""The settings a Check's statement names, as written.
|
|
|
|
Anything in backticks that reads as a name or a dotted path, and bare
|
|
snake_case names and dotted paths. Quoted text is a value, so it is skipped,
|
|
as are paths such as roles/x.y.
|
|
"""
|
|
found: list[str] = []
|
|
for span in _CODE.findall(statement):
|
|
candidate = span.strip().split("=")[0].strip()
|
|
if _PATH.match(candidate) and candidate not in _LITERALS:
|
|
found.append(candidate)
|
|
bare = _QUOTED.sub(" ", _CODE.sub(" ", statement))
|
|
found += [match.group(1).rstrip(".") for match in _NAME.finditer(bare)]
|
|
return tuple(dict.fromkeys(found))
|
|
|
|
|
|
def _names(block: Mapping[str, Any]) -> set[str]:
|
|
"""Every argument and block name anywhere in a resource type's schema."""
|
|
names = set(block.get("attributes") or {})
|
|
for name, nested in (block.get("block_types") or {}).items():
|
|
names.add(name)
|
|
names |= _names(nested.get("block") or {})
|
|
return names
|
|
|
|
|
|
def _is_missing(setting: str, known: set[str]) -> bool:
|
|
"""Whether a name a Check uses is a setting the resource type lacks.
|
|
|
|
A path is judged by the setting at its end, and only when it starts at a name
|
|
the type has. One that does not start there is a value written with dots, such
|
|
as a database flag (`cloudsql.iam_authentication`) or a service
|
|
(`run.googleapis.com`): both were raised as missing settings on 2026-10-09.
|
|
"""
|
|
first, _, rest = setting.partition(".")
|
|
if rest and first not in known:
|
|
return False
|
|
return setting.split(".")[-1] not in known
|
|
|
|
|
|
class SchemaReview:
|
|
def __init__(self, runner: TerraformRunner) -> None:
|
|
self._runner = runner
|
|
self._names: dict[str, set[str]] = {}
|
|
|
|
async def __call__(
|
|
self,
|
|
kind: DeliverableKind,
|
|
attachments: Mapping[str, str],
|
|
upstream: Mapping[str, Mapping[str, Any]] | None,
|
|
scope: str = "",
|
|
) -> Sequence[str]:
|
|
"""Resource types the provider does not have, and Checks naming a setting
|
|
their Element's resource type does not have."""
|
|
if kind != DeliverableKind.TARGET_ARCHITECTURE:
|
|
return ()
|
|
try:
|
|
graph = parse_graph(attachments.get(GRAPH_ATTACHMENT, ""))
|
|
except GraphError:
|
|
return ()
|
|
schemas = await self._runner._load_schemas()
|
|
if isinstance(schemas, ToolResult):
|
|
logger.info("Schema review skipped: %s", schemas.message[:120])
|
|
return ()
|
|
|
|
concerns: list[str] = []
|
|
types = {element.id: element.resource_type for element in graph.elements}
|
|
for element in graph.elements:
|
|
if element.resource_type not in schemas:
|
|
close = difflib.get_close_matches(
|
|
element.resource_type, schemas, n=3, cutoff=0.6
|
|
)
|
|
hint = f" Close matches: {', '.join(close)}." if close else ""
|
|
concerns.append(
|
|
f"Element {element.id}: {element.resource_type} is not a "
|
|
f"resource type of the provider.{hint}"
|
|
)
|
|
for check in graph.checks:
|
|
resource_type = types.get(check.applies_to)
|
|
if resource_type not in schemas:
|
|
continue # a Check on a Relationship, or a type already raised
|
|
known = self._names.setdefault(
|
|
resource_type, _names(schemas[resource_type][1])
|
|
)
|
|
missing = [
|
|
setting
|
|
for setting in named_settings(check.statement)
|
|
if setting not in schemas and _is_missing(setting, known)
|
|
]
|
|
if missing:
|
|
concerns.append(
|
|
f"Check {check.id}: {resource_type} has no setting named "
|
|
f"{', '.join(missing)}, so no code can meet it there. Put the "
|
|
"Check on the Element whose resource type has that setting, "
|
|
"or reword it. Leave it if that word is a value, not a setting"
|
|
)
|
|
if concerns:
|
|
logger.info("[%s] schema review raised %d item(s)", scope, len(concerns))
|
|
return tuple(concerns)
|
|
|
|
|
|
class Reviews:
|
|
"""Several reviews as one: everything any of them raises."""
|
|
|
|
def __init__(self, reviews: Sequence[Any]) -> None:
|
|
self._reviews = tuple(reviews)
|
|
|
|
async def __call__(
|
|
self,
|
|
kind: Any,
|
|
attachments: Mapping[str, str],
|
|
upstream: Mapping[str, Mapping[str, Any]] | None,
|
|
scope: str = "",
|
|
) -> Sequence[str]:
|
|
raised: list[str] = []
|
|
for review in self._reviews:
|
|
try:
|
|
raised += await review(kind, attachments, upstream, scope)
|
|
except Exception: # one review failing must not lose the others
|
|
logger.exception("A submission review failed; continuing")
|
|
return tuple(raised)
|