You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit bacbae4
Browse filesBrowse the repository at this point in the historyBrowse files
The **cdd-rust** tool acts as a dedicated compiler and transpiler. Its fundamental architecture follows standard compiler design principles, divided into three distinct phases: **Frontend (Parsing)**, **Intermediate Representation (IR)**, and **Backend (Emitting)**.
8
+
The **cdd-rust** tool acts as a dedicated lossless compiler and transpiler. Its fundamental architecture follows standard compiler design principles, divided into three distinct phases: **Frontend (Parsing)**, **Intermediate Representation (IR)**, and **Backend (Emitting & Surgical Patching)**.
10
9
11
-
This decoupled design ensures that any format capable of being parsed into the IR can subsequently be emitted into any supported output format, whether that is a server-side route, a client-side SDK, a database ORM, or an OpenAPI specification.
10
+
This decoupled design ensures that any format capable of being parsed into the IR can subsequently be emitted or patched into any supported output format—whether that is an Actix-Web or Axum server route, a Reqwest client SDK, a Clap CLI, a Diesel ORM model, an Arazzo 1.1.0 workflow orchestrator, an MCP adapter, or an OpenAPI 3.2.0 specification.
12
11
13
12
## 🏗 High-Level Overview
14
13
@@ -21,22 +20,22 @@ graph TD
21
20
classDef endpoint fill:#ffffff,stroke:#20344b,stroke-width:1px,color:#20344b,font-family:Google Sans
The Frontend's responsibility is to read an input source and translate it into the universal CDD Intermediate Representation (IR).
59
58
60
-
***Static Analysis (AST-Driven)**: For `Rust` source code, the tool **does not** use dynamic reflection or execute the code. Instead, it reads the source files, generates an Abstract Syntax Tree (AST) using the `syn` crate, and navigates the tree to extract classes, structs, functions, type signatures, API client definitions, server routes, and docstrings.
61
-
***OpenAPIParsing**: For OpenAPI and JSON Schema inputs, the parser normalizes the structure, resolving internal `$ref`s and extracting properties, endpoints (client or server perspectives), and metadata into the IR.
59
+
***Static Analysis (CST-Driven via `ra_ap_syntax`)**: For `Rust` source code, the tool **does not** use dynamic reflection or execute the code. Instead, it parses source files into a lossless Concrete Syntax Tree (CST) using `ra_ap_syntax` (`rust-analyzer`'s syntax tree engine for Rust Edition 2021), preserving whitespace, comments, docstrings, and attributes while extracting structs, enums, functions, type signatures, Reqwest client calls, Actix-Web/Axum server routes, and Arazzo workflow steps.
60
+
***OpenAPI, Swagger & Arazzo Parsing**: For OpenAPI 3.2.0, Swagger 2.0, JSON Schema (2020-12), and Arazzo 1.1.0 inputs, the parser normalizes legacy specifications, resolves internal and external `$ref`s (`DocumentRegistry`), and extracts models, routes, security schemes, webhooks, callbacks, and multi-step workflow graphs into the IR.
The Intermediate Representation is the crucial "glue" of the architecture. It is a normalized, language-agnostic data structure that represents concepts like:
66
-
***Models**: Entities containing typed properties, required fields, defaults, and descriptions.
67
-
***Endpoints / Operations**: HTTP verbs, paths, path/query/body parameters, and responses. In the IR, an operation is an abstract concept that can represent *either* a Server Route receiving a request *or* an API Client dispatching a request.
68
-
***Metadata**: Tooling hints, docstrings, and validations.
64
+
The Intermediate Representation (`cdd-core`) is the normalized, language-agnostic data structure representing:
***Structural Diffs (`StructDiff` / `FieldChange`)**: Computed differences between existing CST nodes and target specifications to drive lossless in-place patching.
69
69
70
-
By standardizing on a single IR (heavily inspired by OpenAPI / JSON Schema primitives), the system guarantees that parsing logic and emitting logic remain completely decoupled.
70
+
### 3. The Backend (Emitters & Surgical Patchers)
71
71
72
-
### 3. The Backend (Emitters)
72
+
The Backend takes the universal IR (and optional CST diffs) and emits or patches target outputs via the `BackendStrategy`, `CliStrategy`, and `WorkflowStrategy` traits:
73
73
74
-
The Backend's responsibility is to take the universal IR and generate valid target output. Emitters can be written to support various environments (e.g., Client vs Server, Web vs CLI).
75
-
76
-
***Code Generation**: Emitters iterate over the IR and generate idiomatic `Rust` source code utilizing the `quote` crate.
77
-
* A **Server Emitter** creates Actix-web routing controllers and request-validation logic.
78
-
* A **Client Emitter** creates Reqwest API wrappers, fetch functions, and response-parsing logic.
79
-
***Database & CLI Generation**: Emitters can also target Diesel ORM models or Clap command-line parsers by mapping IR properties to database columns or CLI arguments.
80
-
***Specification Generation**: Emitters translating back to OpenAPI serialize the IR into standard Swagger 2.0 and OpenAPI 3.2.0 JSON or YAML, rigorously formatting descriptions, type constraints, and endpoint schemas based on what was parsed from the source code.
74
+
***Lossless CST Patcher (`cdd_core::classes::patcher`)**: Modifies existing `.rs` files in-place without disturbing user comments, formatting, or custom handler bodies.
75
+
***Server Emitters (`ActixStrategy`, `AxumStrategy`, `McpServerStrategy`)**: Create and update Actix-Web and Axum route handlers, router configurations, MCP server handlers, and contract tests.
***Specification Emitters**: Serialize the IR into compliant OpenAPI 3.2.0, JSON Schema 2020-12, and Arazzo 1.1.0 JSON or YAML documents.
81
79
82
80
## 🔄 Extensibility
83
81
84
-
Because of the IR-centric design, adding support for a new `Rust` framework (e.g., a new Client library, Web framework, or ORM) requires minimal effort:
85
-
1.**To support parsing a new framework**: Write a parser that converts the framework's AST/DSL into the CDD IR. Once written, the framework can automatically be exported to OpenAPI, Client SDKs, CLI parsers, or any other existing output target.
86
-
2.**To support emitting a new framework**: Write an emitter that converts the CDD IR into the framework's DSL/AST. Once written, the framework can automatically be generated from OpenAPI or any other supported input.
82
+
Because of the strategy and IR design, adding support for a new `Rust` framework requires minimal effort:
83
+
1.**To support parsing a new framework**: Implement extraction into `ParsedRoute` / `ParsedStruct` in `cdd-core`.
84
+
2.**To support emitting a new framework**: Implement the `BackendStrategy` / `WorkflowStrategy` traits in `cdd_core::strategies`.
87
85
88
86
## 🛡 Design Principles
89
87
90
-
1.**A Single Source of Truth**: Developers should be able to maintain their definitions in whichever format is most ergonomic for their team (OpenAPI files, Native Code, Client libraries, ORM models) and generate the rest.
91
-
2.**Zero-Execution Parsing**: Ensure security and resilience by strictly statically analyzing inputs. The compiler must never need to run the target code to understand its structure.
92
-
3.**Lossless Conversion**: Maximize the retention of metadata (e.g., type annotations, docstrings, default values, validators) during the transition `Source -> IR -> Target`.
93
-
4.**Symmetric Operations**: An Endpoint in the IR holds all the information necessary to generate both the Server-side controller that fulfills it, and the Client-side SDK method that calls it.
88
+
1.**A Single Source of Truth**: Maintain definitions in whichever format is most ergonomic (OpenAPI/Arazzo files, Rust structs/handlers, or Diesel `schema.rs`) and synchronize the rest.
89
+
2.**Zero-Execution Parsing**: Strictly statically analyze inputs without compiling or executing untrusted target code.
90
+
3.**Lossless Conversion**: Retain formatting, comments, docstrings, type annotations, and attributes across `Source ⇄ CST/IR ⇄ Target`.
91
+
4.**Symmetric Operations**: Every operation and workflow in the IR holds all metadata required to emit both server handlers and client SDK/CLI orchestrators.
The toolchain has been fully verified against the universal conformance suite via `../scripts/check_all_conformance.sh`. All features, including callbacks, links, and examples, are successfully roundtripped and marked as green in the `ECOSYSTEM_COMPLIANCE_OAS_3_2_0.md` tracking document.
12
-
## Support Matrix
12
+
The toolchain has been verified against the universal conformance suite via `../scripts/check_all_conformance.sh`. All features—including callbacks, webhooks, links, runtime expressions, and examples—are roundtripped and verified in [`conformance/`](conformance/).
0 commit comments