feat chaotic: OpenAPI handlers [1/2]

commit_hash:9bd49817481c671718a00c9fc0737410904100e2

Author: segoon

.mapping.json

@@ -0,0 +1,49 @@
+# Jinja style guide
+
+`*.{hpp,cpp}.jinja` templates produce C++ source files when rendered.
+Mixed jinja/C++ template source is hard to perceive for a human.
+We use several rules to ease this task:
+
+- Jinja files should be as small as possible. Duplicated code/types must be moved to static `include/**.hpp` files.
+- Use 4 spaces for generated C++ code:
+  ```cpp
+  namespace ns {
+  class X {
+  public:
+      void f() {
+          g();
+      }
+  };
+  } // namespace ns
+  ```
+- Use identation with spaces to reflect statement/expression nesting level (1 level = 2 spaces), E.g.:
+  ```jinja
+  // In file.hpp.jinja
+  class X {
+    {% if flag %}
+      {% for item in items %}
+        {{ item.cpp_type }} {{ item.cpp_name }};
+      {% endfor %}
+    {% endif %}
+  };
+  ```
+- Leave empty line after closing statements `end*` (e.g. endif, endfor) unless followed by closing statement, "}", ">", or ";". E.g.:
+  ```jinja
+  class T {
+    {% if is_enabled %}
+      {% if f_flag %}
+        f();
+      {% endif %}
+
+      {% if g_flag %}
+        g();
+      {% endif %}
+
+      foo();
+
+      {% if h_flag %}
+        h();
+      {% endif %}
+    {% endif %}
+  };
+  ```

chaotic-openapi/AGENTS.jinja.md

@@ -0,0 +1,56 @@
+# chaotic-openapi — Agent Guide
+
+## What this project is
+
+OpenAPI 3.x / Swagger 2.0 → C++ HTTP client code generator for the userver framework,
+plus a small C++ runtime library the generated code links against.
+
+Main external dependencies:
+- C++ code — `../chaotic`, `../core`, `../utils`
+- cmake — `../cmake`, `../CMakeLists.txt`
+- bash/python scripts, helpers — `../scripts`
+- documentation in markdown — `../scripts/docs`
+
+
+## References
+
+Reference specification is located at github: https://github.com/OAI/OpenAPI-Specification/tree/main/versions
+
+
+## Generation pipeline
+
+```
+OpenAPI/Swagger YAML
+  → ref_resolver.sort_openapis()     topological sort of multi-file $refs
+  → front/parser.Parser              pydantic objects → model.Service (language-neutral IR)
+  → back/cpp/client/translator       model.Service → types.ClientSpec (C++-typed IR)
+  → back/cpp/client/renderer         Jinja2 templates → 14 .hpp/.cpp files
+```
+
+`output.py` is **not** part of this pipeline. It is a separate Yandex build-system tool
+that generates the `PEERDIR`/include lists for `ya.make` files. It is never called from
+`main.py`.
+
+
+# Tests
+
+Tests are implemented at multiple levels:
+
+- tests/front/ - python tests on OpenAPI/Swagger format parsing
+- tests/back/ - python tests on IR -> C++-specific model translator
+- integration_tests/ - full cycle tests (parsing -> translation -> rendering -> C++ compilation -> generated types tests)
+- golden_tests/ - NOT tests, but a showcase of "what's possible with chaotic" / "how chaotic output looks like",
+  containing examples of core types, cases and features
+
+
+# Jinja style guide
+
+See @AGENTS.jinja.md
+
+
+# Python style guide
+
+Style guide is based on PEP8.
+Also:
+- use `abc` module for abstract classes
+- `from x import y` is limited to `y` modules (IMR241 check in flake8-import-restrictions)

chaotic-openapi/AGENTS.md

@@ -9,7 +9,7 @@
 from chaotic.back.cpp import types as cpp_types
 from chaotic.front import parser as chaotic_parser
 from chaotic.front import ref
-from chaotic_openapi.back.cpp_client import renderer
+from chaotic_openapi.back.cpp.client import renderer
 
 TYPES_INCLUDES = [
     'cstdint',

…otic_openapi/back/cpp_client/__init__.py …api/chaotic_openapi/back/cpp/__init__.pychaotic-openapi/chaotic_openapi/back/cpp_client/__init__.py renamed to chaotic-openapi/chaotic_openapi/back/cpp/__init__.py chaotic-openapi/chaotic_openapi/back/cpp_client/__init__.py renamed to chaotic-openapi/chaotic_openapi/back/cpp/__init__.py

@@ -7,7 +7,7 @@
 from chaotic import cpp_format
 from chaotic import jinja_env
 from chaotic.back.cpp import renderer as cpp_renderer
-from chaotic_openapi.back.cpp_client import types
+from chaotic_openapi.back.cpp.client import types
 
 PARENT_DIR = os.path.dirname(__file__)
 
@@ -66,7 +66,7 @@ def cpp_comment(string: str) -> str:
 
 def make_env() -> jinja2.Environment:
     env = jinja_env.make_env(
-        'chaotic-openapi/chaotic_openapi/back/cpp_client',
+        'chaotic-openapi/chaotic_openapi/back/cpp/client',
         os.path.join(PARENT_DIR),
     )
     env.globals['list'] = list

chaotic-openapi/chaotic_openapi/back/cpp/client/__init__.py

@@ -15,10 +15,11 @@ public:
     {{ op.description | cpp_comment }}
     /// @throw {{ op.cpp_namespace() }}::Exception
     {% for response in op.responses %}
-        {% if response.is_error() %}
-          /// @throw {{ op.cpp_namespace() }}::Response{{ response.status }}
+      {% if response.is_error() %}
+        /// @throw {{ op.cpp_namespace() }}::Response{{ response.status }}
       {% endif %}
     {% endfor -%}
+
     virtual {{ op.cpp_namespace() }}::Response {{ op.cpp_method_name() }}(
       {%- if not op.empty_request() -%}
           const {{ op.cpp_namespace() }}::Request& request ,