pytest-httpchain 0.3.0__tar.gz → 0.5.0__tar.gz

{pytest_httpchain-0.3.0 → pytest_httpchain-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-httpchain
-Version: 0.3.0
+Version: 0.5.0
 Summary: pytest plugin for HTTP testing using JSON files
 Keywords: testing,pytest,requests
 Author: Alexander Eresov
@@ -198,28 +198,30 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
 
 ## AI agent support
 
-`pytest-httpchain` ships tooling to help AI coding agents (and humans) author and check test scenarios.
+`pytest-httpchain` ships a scenario validator to help AI coding agents (and humans) author and check test scenarios.
 
-### Claude Code skill
+### Scenario validation
 
-Install the authoring skill into your project (or `--global` for personal scope):
+Validate scenario files for structure and common problems — undefined variables, variables referenced before they are saved (data-flow ordering), duplicate stage names, fixture/variable conflicts, no-op `verify` steps, and contradictory body checks:
 
 ```bash
-uvx pytest-httpchain install
+uvx pytest-httpchain validate tests/test_login.http.json
 ```
 
-This writes `.claude/skills/pytest-httpchain/SKILL.md` with guidance for writing scenarios.
+Each finding carries a stable diagnostic code (`HTTPCHAINxxx`) and a severity. It exits non-zero when any file is invalid, so it doubles as a CI gate. Use `--format json` for machine-readable output (editor/CI integration):
 
-### Scenario validation
+```bash
+uvx pytest-httpchain validate --format json tests/test_login.http.json
+```
 
-Validate scenario files for structure and common problems — undefined variables, duplicate stage names, fixture/variable conflicts, stages with no assertions:
+The same checks also run automatically at **pytest collection time** — semantic errors fail collection and warnings are reported — so `pytest --collect-only` validates every scenario in your suite.
+
+For deeper, opt-in checks, add `--deep`: it imports your `module:func` references to confirm they resolve, checks their call signatures (including the injected `response` for save/verify functions), and verifies referenced files and schemas exist. Because it imports your code it is never run at collection time; pair it with `--strict` to fail CI on any warning, and `--syspath` to add import roots:
 
 ```bash
-uvx pytest-httpchain validate tests/test_login.http.json
+uvx pytest-httpchain validate --deep --strict tests/test_login.http.json
 ```
 
-It exits non-zero when any file is invalid, so it doubles as a CI gate. The same checks also run automatically at **pytest collection time** — semantic errors fail collection and warnings are reported — so `pytest --collect-only` validates every scenario in your suite.
-
 ### Editor schema
 
 A JSON Schema is published for as-you-type validation and autocomplete. Reference it from your test files:
@@ -230,6 +232,27 @@ A JSON Schema is published for as-you-type validation and autocomplete. Referenc
 }
 ```
 
+The hosted schema tracks the latest release; to pin the schema matching your installed version (e.g. for CI), emit it locally:
+
+```bash
+uvx pytest-httpchain schema --output scenario.schema.json
+```
+
+### Inspecting scenarios
+
+More read-only commands help author and debug scenarios offline — no network, no test run:
+
+```bash
+# Print a scenario with all $ref/$include/$merge inlined and deep-merged
+uvx pytest-httpchain resolve tests/test_login.http.json
+
+# Summarize stages and the variable data-flow (which stage saves what, who consumes it)
+uvx pytest-httpchain show tests/test_login.http.json
+
+# Render the stage data-flow as a Mermaid flowchart
+uvx pytest-httpchain graph tests/test_login.http.json
+```
+
 ## Documentation
 
 -   [Full Documentation](https://aeresov.github.io/pytest-httpchain) - Complete usage guide

{pytest_httpchain-0.3.0 → pytest_httpchain-0.5.0}/README.md

@@ -171,28 +171,30 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
 
 ## AI agent support
 
-`pytest-httpchain` ships tooling to help AI coding agents (and humans) author and check test scenarios.
+`pytest-httpchain` ships a scenario validator to help AI coding agents (and humans) author and check test scenarios.
 
-### Claude Code skill
+### Scenario validation
 
-Install the authoring skill into your project (or `--global` for personal scope):
+Validate scenario files for structure and common problems — undefined variables, variables referenced before they are saved (data-flow ordering), duplicate stage names, fixture/variable conflicts, no-op `verify` steps, and contradictory body checks:
 
 ```bash
-uvx pytest-httpchain install
+uvx pytest-httpchain validate tests/test_login.http.json
 ```
 
-This writes `.claude/skills/pytest-httpchain/SKILL.md` with guidance for writing scenarios.
+Each finding carries a stable diagnostic code (`HTTPCHAINxxx`) and a severity. It exits non-zero when any file is invalid, so it doubles as a CI gate. Use `--format json` for machine-readable output (editor/CI integration):
 
-### Scenario validation
+```bash
+uvx pytest-httpchain validate --format json tests/test_login.http.json
+```
 
-Validate scenario files for structure and common problems — undefined variables, duplicate stage names, fixture/variable conflicts, stages with no assertions:
+The same checks also run automatically at **pytest collection time** — semantic errors fail collection and warnings are reported — so `pytest --collect-only` validates every scenario in your suite.
+
+For deeper, opt-in checks, add `--deep`: it imports your `module:func` references to confirm they resolve, checks their call signatures (including the injected `response` for save/verify functions), and verifies referenced files and schemas exist. Because it imports your code it is never run at collection time; pair it with `--strict` to fail CI on any warning, and `--syspath` to add import roots:
 
 ```bash
-uvx pytest-httpchain validate tests/test_login.http.json
+uvx pytest-httpchain validate --deep --strict tests/test_login.http.json
 ```
 
-It exits non-zero when any file is invalid, so it doubles as a CI gate. The same checks also run automatically at **pytest collection time** — semantic errors fail collection and warnings are reported — so `pytest --collect-only` validates every scenario in your suite.
-
 ### Editor schema
 
 A JSON Schema is published for as-you-type validation and autocomplete. Reference it from your test files:
@@ -203,6 +205,27 @@ A JSON Schema is published for as-you-type validation and autocomplete. Referenc
 }
 ```
 
+The hosted schema tracks the latest release; to pin the schema matching your installed version (e.g. for CI), emit it locally:
+
+```bash
+uvx pytest-httpchain schema --output scenario.schema.json
+```
+
+### Inspecting scenarios
+
+More read-only commands help author and debug scenarios offline — no network, no test run:
+
+```bash
+# Print a scenario with all $ref/$include/$merge inlined and deep-merged
+uvx pytest-httpchain resolve tests/test_login.http.json
+
+# Summarize stages and the variable data-flow (which stage saves what, who consumes it)
+uvx pytest-httpchain show tests/test_login.http.json
+
+# Render the stage data-flow as a Mermaid flowchart
+uvx pytest-httpchain graph tests/test_login.http.json
+```
+
 ## Documentation
 
 -   [Full Documentation](https://aeresov.github.io/pytest-httpchain) - Complete usage guide

{pytest_httpchain-0.3.0 → pytest_httpchain-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytest-httpchain"
-version = "0.3.0"
+version = "0.5.0"
 description = "pytest plugin for HTTP testing using JSON files"
 readme = "README.md"
 requires-python = ">=3.13,<4.0"

pytest_httpchain-0.5.0/src/pytest_httpchain/cli.py

@@ -0,0 +1,222 @@
+import enum
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+app = typer.Typer()
+
+
+class OutputFormat(enum.StrEnum):
+    text = "text"
+    json = "json"
+
+
+class GraphDirection(enum.StrEnum):
+    TD = "TD"
+    LR = "LR"
+
+
+@app.callback()
+def main() -> None:
+    """pytest-httpchain command-line tools."""
+
+
+@app.command()
+def validate(
+    paths: Annotated[list[Path], typer.Argument(help="Scenario JSON file(s) to validate.")],
+    ref_parent_traversal_depth: Annotated[int, typer.Option(help="Maximum $ref parent directory traversal depth.")] = 3,
+    output_format: Annotated[OutputFormat, typer.Option("--format", help="Output format: human-readable text or machine-readable JSON.")] = OutputFormat.text,
+    deep: Annotated[bool, typer.Option("--deep", help="Run deep checks: resolve user-function imports/signatures and referenced files. Imports user modules.")] = False,
+    syspath: Annotated[list[Path] | None, typer.Option("--syspath", help="Extra directories to add to sys.path for --deep import resolution (repeatable).")] = None,
+    strict: Annotated[bool, typer.Option("--strict", help="Treat warnings as failures for the exit code.")] = False,
+) -> None:
+    """Validate pytest-httpchain scenario file(s).
+
+    Reports errors and warnings (each with a stable HTTPCHAINxxx diagnostic code)
+    per file and exits non-zero if any file is invalid (or, with --strict, has any
+    warnings).
+    """
+    from pytest_httpchain.validation import validate_scenario
+
+    results = [(path, validate_scenario(path, ref_parent_traversal_depth=ref_parent_traversal_depth, deep=deep, syspaths=list(syspath or []))) for path in paths]
+
+    def passed(result) -> bool:
+        return result.valid and not (strict and result.warnings)
+
+    all_passed = all(passed(result) for _, result in results)
+
+    if output_format is OutputFormat.json:
+        payload = {
+            "valid": all_passed,
+            "files": [{"path": str(path), "result": result.model_dump()} for path, result in results],
+        }
+        typer.echo(json.dumps(payload, indent=2, default=str))
+    else:
+        for path, result in results:
+            if not result.valid:
+                status = "INVALID"
+            elif result.warnings:
+                status = "FAILED (warnings)" if strict else "OK with warnings"
+            else:
+                status = "OK"
+            typer.echo(f"{path}: {status}")
+            for diagnostic in result.diagnostics:
+                typer.echo(f"  {diagnostic.severity} [{diagnostic.code}]: {diagnostic.message}")
+
+    raise typer.Exit(0 if all_passed else 1)
+
+
+@app.command()
+def schema(
+    output: Annotated[Path | None, typer.Option("--output", "-o", help="Write schema to PATH instead of stdout.")] = None,
+) -> None:
+    """Emit the JSON Schema for scenario files (editor autocomplete/validation)."""
+    from pytest_httpchain.schema import build_schema
+
+    text = json.dumps(build_schema(), indent=2, default=str)
+    if output is not None:
+        output.write_text(text + "\n")
+        typer.echo(f"Wrote schema to {output}")
+    else:
+        typer.echo(text)
+
+
+@app.command()
+def resolve(
+    scenario: Annotated[Path, typer.Argument(help="Scenario JSON file to resolve.")],
+    output: Annotated[Path | None, typer.Option("--output", "-o", help="Write resolved JSON to PATH instead of stdout.")] = None,
+    ref_parent_traversal_depth: Annotated[int, typer.Option(help="Maximum $ref parent directory traversal depth.")] = 3,
+) -> None:
+    """Resolve $ref/$include/$merge and print the merged scenario JSON."""
+    import pytest_httpchain_jsonref.loader
+    from pytest_httpchain_jsonref.exceptions import ReferenceResolverError
+
+    from pytest_httpchain.validation import resolve_root_path
+
+    try:
+        data = pytest_httpchain_jsonref.loader.load_json(
+            scenario,
+            max_parent_traversal_depth=ref_parent_traversal_depth,
+            root_path=resolve_root_path(scenario),
+        )
+    except (ReferenceResolverError, json.JSONDecodeError, OSError) as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(1) from e
+
+    text = json.dumps(data, indent=2, default=str)
+    if output is not None:
+        output.write_text(text + "\n")
+        typer.echo(f"Wrote resolved scenario to {output}")
+    else:
+        typer.echo(text)
+
+
+def _load_for_inspection(path: Path, depth: int):
+    """Load + validate a scenario for show/graph, mapping failures to Exit(1)."""
+    from pydantic import ValidationError
+    from pytest_httpchain_jsonref.exceptions import ReferenceResolverError
+
+    from pytest_httpchain.dataflow import load_scenario
+
+    try:
+        return load_scenario(path, ref_parent_traversal_depth=depth)
+    except (ReferenceResolverError, json.JSONDecodeError, OSError) as e:
+        typer.echo(f"error: cannot load {path}: {e}", err=True)
+        raise typer.Exit(1) from e
+    except ValidationError:
+        typer.echo(f"error: {path} is not a valid scenario — run `pytest-httpchain validate {path}` for details", err=True)
+        raise typer.Exit(1) from None
+
+
+def _render_show_text(path: Path, scenario, flow) -> list[str]:
+    producer_of: dict[tuple[int, str], int] = {}
+    for edge in flow.edges:
+        for name in edge.vars:
+            producer_of[(edge.consumer, name)] = edge.producer
+
+    all_fixtures = sorted({*flow.scenario_fixtures, *(f for s in flow.stages for f in s.fixtures)})
+    lines: list[str] = [scenario.description or path.name]
+    summary = f"{len(flow.stages)} stage(s)"
+    if all_fixtures:
+        summary += f" · fixtures: {all_fixtures}"
+    if flow.scenario_vars:
+        summary += f" · vars: {flow.scenario_vars}"
+    lines.append(summary)
+    lines.append("")
+
+    for s in flow.stages:
+        name = s.name or f"(stage {s.index + 1})"
+        lines.append(f"{s.index + 1} · {name}    {s.method} {s.url}")
+        if s.saves:
+            lines.append(f"    saves:    {', '.join(s.saves)}")
+        if s.consumes:
+            parts: list[str] = []
+            for name in s.consumes:
+                producer = producer_of.get((s.index, name))
+                if producer is None:
+                    parts.append(name)
+                else:
+                    producer_name = flow.stages[producer].name or f"stage {producer + 1}"
+                    parts.append(f"{name} (from #{producer + 1} {producer_name})")
+            lines.append(f"    consumes: {', '.join(parts)}")
+        if s.marks:
+            lines.append(f"    marks:    {', '.join(s.marks)}")
+    return lines
+
+
+@app.command()
+def show(
+    scenario: Annotated[Path, typer.Argument(help="Scenario JSON file to summarize.")],
+    output_format: Annotated[OutputFormat, typer.Option("--format", help="Output format: human-readable text or machine-readable JSON.")] = OutputFormat.text,
+    ref_parent_traversal_depth: Annotated[int, typer.Option(help="Maximum $ref parent directory traversal depth.")] = 3,
+) -> None:
+    """Summarize a scenario's stages and variable data-flow."""
+    from pytest_httpchain.dataflow import analyze_dataflow
+
+    sc, test_data = _load_for_inspection(scenario, ref_parent_traversal_depth)
+    flow = analyze_dataflow(sc, test_data)
+
+    if output_format is OutputFormat.json:
+        payload = flow.model_dump()
+        payload["description"] = sc.description or None
+        typer.echo(json.dumps(payload, indent=2, default=str))
+    else:
+        for line in _render_show_text(scenario, sc, flow):
+            typer.echo(line)
+
+
+def _mermaid_label(text: str) -> str:
+    return text.replace('"', "'").replace("\n", " ")
+
+
+def _to_mermaid(flow, direction: str = "TD") -> str:
+    lines = [f"flowchart {direction}"]
+    if not flow.stages:
+        lines.append("    %% (no stages)")
+        return "\n".join(lines)
+    for s in flow.stages:
+        label = f"{s.index + 1} · {s.name}" if s.name else f"{s.index + 1}"
+        lines.append(f'    S{s.index}["{_mermaid_label(label)}"]')
+    for edge in flow.edges:
+        lines.append(f"    S{edge.producer} -->|{', '.join(edge.vars)}| S{edge.consumer}")
+    return "\n".join(lines)
+
+
+@app.command()
+def graph(
+    scenario: Annotated[Path, typer.Argument(help="Scenario JSON file to graph.")],
+    direction: Annotated[GraphDirection, typer.Option("--direction", help="Flowchart orientation.")] = GraphDirection.TD,
+    ref_parent_traversal_depth: Annotated[int, typer.Option(help="Maximum $ref parent directory traversal depth.")] = 3,
+) -> None:
+    """Emit a Mermaid flowchart of the stage data-flow."""
+    from pytest_httpchain.dataflow import analyze_dataflow
+
+    sc, test_data = _load_for_inspection(scenario, ref_parent_traversal_depth)
+    flow = analyze_dataflow(sc, test_data)
+    typer.echo(_to_mermaid(flow, direction.value))
+
+
+if __name__ == "__main__":
+    app()

pytest_httpchain-0.5.0/src/pytest_httpchain/dataflow.py

@@ -0,0 +1,127 @@
+"""Structured stage data-flow analysis for the ``show`` and ``graph`` CLI commands.
+
+Reuses the same extraction helpers as the order-aware validator
+(``validation._dataflow_diagnostics``) but produces a graph model instead of
+diagnostics: which variables each stage saves, which it consumes from earlier
+stages, and the producer -> consumer edges between stages.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import pytest_httpchain_jsonref.loader
+from pydantic import BaseModel
+from pytest_httpchain_models import Scenario
+
+from pytest_httpchain.validation import (
+    extract_template_variables,
+    raw_stages,
+    resolve_root_path,
+    saved_in_stage,
+    stage_defined_names,
+    substitution_names,
+)
+
+
+class DataFlowEdge(BaseModel):
+    """A data dependency: ``vars`` saved by stage ``producer`` are referenced by stage ``consumer``."""
+
+    producer: int
+    consumer: int
+    vars: list[str]
+
+
+class StageFlow(BaseModel):
+    """Per-stage data-flow summary."""
+
+    index: int
+    name: str
+    method: str
+    url: str
+    fixtures: list[str]
+    marks: list[str]
+    saves: list[str]
+    consumes: list[str]
+
+
+class DataFlow(BaseModel):
+    """Whole-scenario data-flow graph."""
+
+    stages: list[StageFlow]
+    edges: list[DataFlowEdge]
+    scenario_fixtures: list[str] = []
+    scenario_vars: list[str] = []
+
+
+def analyze_dataflow(scenario: Scenario, test_data: dict[str, Any]) -> DataFlow:
+    """Build the stage data-flow graph for a validated scenario.
+
+    A stage *consumes* a variable when its request/response/substitutions/parallel
+    templates reference a name saved by an earlier stage and not redefined locally
+    (own substitutions, parametrize/foreach parameters, or fixtures). ``parametrize``
+    values are excluded — they resolve against scenario scope, never saved values.
+    """
+    raws = raw_stages(test_data)
+    saves_by_stage = [saved_in_stage(stage) for stage in scenario.stages]
+
+    first_save_stage: dict[str, int] = {}
+    for i, saved in enumerate(saves_by_stage):
+        for name in saved:
+            first_save_stage.setdefault(name, i)
+
+    stages: list[StageFlow] = []
+    edges: list[DataFlowEdge] = []
+    cumulative_saves: set[str] = set()
+
+    for i, stage in enumerate(scenario.stages):
+        raw = raws[i] if i < len(raws) and isinstance(raws[i], dict) else {}
+
+        refs: set[str] = set()
+        for key in ("request", "response", "substitutions", "parallel"):
+            extract_template_variables(raw.get(key), refs)
+
+        local = stage_defined_names(stage)
+        consumes = {name for name in refs if name in cumulative_saves and name not in local}
+
+        by_producer: dict[int, list[str]] = {}
+        for name in consumes:
+            by_producer.setdefault(first_save_stage[name], []).append(name)
+        for producer in sorted(by_producer):
+            edges.append(DataFlowEdge(producer=producer, consumer=i, vars=sorted(by_producer[producer])))
+
+        stages.append(
+            StageFlow(
+                index=i,
+                name=stage.name,
+                method=str(stage.request.method),
+                url=str(stage.request.url),
+                fixtures=sorted(stage.fixtures),
+                marks=list(stage.marks),
+                saves=sorted(saves_by_stage[i]),
+                consumes=sorted(consumes),
+            )
+        )
+
+        cumulative_saves |= saves_by_stage[i]
+
+    scenario_fixtures = sorted(f for f in test_data["fixtures"] if isinstance(f, str)) if isinstance(test_data.get("fixtures"), list) else []
+    scenario_var_names = set(substitution_names(scenario.substitutions))
+    if isinstance(test_data.get("vars"), dict):
+        scenario_var_names |= {k for k in test_data["vars"] if isinstance(k, str)}
+
+    return DataFlow(stages=stages, edges=edges, scenario_fixtures=scenario_fixtures, scenario_vars=sorted(scenario_var_names))
+
+
+def load_scenario(path: Path, ref_parent_traversal_depth: int = 3) -> tuple[Scenario, dict[str, Any]]:
+    """Load + ``$ref``-resolve + validate a scenario file.
+
+    Returns ``(scenario, raw_test_data)``. Raises ``ReferenceResolverError``,
+    ``json.JSONDecodeError`` or ``pydantic.ValidationError`` on failure — callers
+    map these to user-facing errors.
+    """
+    test_data = pytest_httpchain_jsonref.loader.load_json(
+        path,
+        max_parent_traversal_depth=ref_parent_traversal_depth,
+        root_path=resolve_root_path(path),
+    )
+    return Scenario.model_validate(test_data), test_data

{pytest_httpchain-0.3.0 → pytest_httpchain-0.5.0}/src/pytest_httpchain/plugin.py

@@ -66,12 +66,15 @@ class JsonModule(python.Module):
             raise nodes.Collector.CollectError(full_error_msg) from None
 
         # semantic validation: cross-cutting checks the schema cannot express
-        # (duplicate stage names, fixture/variable conflicts, undefined variables, ...)
-        semantic_errors, semantic_warnings, _ = check_scenario(scenario, test_data)
-        for warning in semantic_warnings:
-            warnings.warn(ScenarioValidationWarning(f"{self.path}: {warning}"), stacklevel=2)
-        if semantic_errors:
-            detail = "\n".join(f"  - {e}" for e in semantic_errors)
+        # (duplicate stage names, fixture/variable conflicts, undefined/forward-referenced
+        # variables, no-op verify, contradictory body checks, ...)
+        diagnostics, _ = check_scenario(scenario, test_data)
+        for diagnostic in diagnostics:
+            if diagnostic.severity == "warning":
+                warnings.warn(ScenarioValidationWarning(f"{self.path}: [{diagnostic.code}] {diagnostic.message}"), stacklevel=2)
+        error_diagnostics = [d for d in diagnostics if d.severity == "error"]
+        if error_diagnostics:
+            detail = "\n".join(f"  - [{d.code}] {d.message}" for d in error_diagnostics)
             raise nodes.Collector.CollectError(f"Invalid test scenario in {self.path}:\n{detail}")
 
         # generate python test class

pytest_httpchain-0.5.0/src/pytest_httpchain/schema.py

@@ -0,0 +1,69 @@
+"""Build the JSON Schema for pytest-httpchain scenario files.
+
+Shared by the ``pytest-httpchain schema`` CLI command and
+``scripts/generate_schema.py``. The schema is derived from the Pydantic
+``Scenario`` model and augmented so editors accept pytest-httpchain's
+``$ref``/``$include``/``$merge`` reference directives at any object level.
+"""
+
+from typing import Any
+
+from pytest_httpchain_models import Scenario
+
+SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"
+SCHEMA_ID = "https://aeresov.github.io/pytest-httpchain/schema/scenario.schema.json"
+
+
+def _add_jsonref_support(schema: dict[str, Any]) -> dict[str, Any]:
+    """Allow ``$include``/``$merge``/``$ref`` objects as alternatives anywhere.
+
+    pytest-httpchain-jsonref can substitute any element at runtime, so each
+    definition and root property is wrapped in an ``anyOf`` that also accepts a
+    reference object — otherwise editors flag missing required properties when a
+    reference is used.
+    """
+    if "$defs" not in schema:
+        schema["$defs"] = {}
+
+    schema["$defs"]["JsonRef"] = {
+        "type": "object",
+        "description": "Reference to external JSON file or JSON pointer. Use $include or $merge (preferred) or $ref. Resolved at runtime by pytest-httpchain-jsonref.",
+        "properties": {
+            "$include": {
+                "type": "string",
+                "description": "Path to external JSON file, JSON pointer (#/path), or combined (file.json#/path). Preferred over $ref to avoid VS Code conflicts.",
+            },
+            "$merge": {
+                "type": "string",
+                "description": "Alias for $include. Path to external JSON file, JSON pointer (#/path), or combined (file.json#/path).",
+            },
+        },
+        "additionalProperties": True,
+    }
+
+    for type_name, original_def in list(schema["$defs"].items()):
+        if type_name == "JsonRef":
+            continue
+        schema["$defs"][type_name] = {"anyOf": [{"$ref": "#/$defs/JsonRef"}, original_def]}
+        if "title" in original_def:
+            schema["$defs"][type_name]["title"] = original_def.pop("title")
+        if "description" in original_def:
+            schema["$defs"][type_name]["description"] = original_def.pop("description")
+
+    for prop_name, prop_def in list(schema.get("properties", {}).items()):
+        schema["properties"][prop_name] = {
+            "anyOf": [{"$ref": "#/$defs/JsonRef"}, prop_def],
+            "title": prop_def.get("title", prop_name),
+        }
+        if "description" in prop_def:
+            schema["properties"][prop_name]["description"] = prop_def.get("description")
+
+    return schema
+
+
+def build_schema() -> dict[str, Any]:
+    """Return the augmented JSON Schema dict for the ``Scenario`` model."""
+    schema = Scenario.model_json_schema()
+    schema["$schema"] = SCHEMA_DIALECT
+    schema["$id"] = SCHEMA_ID
+    return _add_jsonref_support(schema)