Skip to content

Commit bacbae4

Browse files
committed
Update docs and remove irrelevant hook
1 parent 998d288 commit bacbae4

19 files changed

Lines changed: 1479 additions & 522 deletions

‎ARCHITECTURE.md‎

Lines changed: 36 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,12 @@
22

33
<!-- BADGES_START -->
44
[![License](https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg)](https://opensource.org/licenses/Apache-2.0)
5-
[![CI/CD](https://github.com/offscale/cdd-rust/workflows/CI/badge.svg)](https://github.com/offscale/cdd-rust/actions)
6-
[![Coverage](https://codecov.io/gh/offscale/cdd-rust/branch/master/graph/badge.svg)](https://codecov.io/gh/offscale/cdd-rust)
5+
[![CI/CD](https://github.com/SamuelMarks/cdd-rust/actions/workflows/ci.yml/badge.svg)](https://github.com/SamuelMarks/cdd-rust/actions)
76
<!-- BADGES_END -->
87

9-
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)**.
109

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.
1211

1312
## 🏗 High-Level Overview
1413

@@ -21,22 +20,22 @@ graph TD
2120
classDef endpoint fill:#ffffff,stroke:#20344b,stroke-width:1px,color:#20344b,font-family:Google Sans
2221
2322
subgraph Frontend [Parsers]
24-
A[OpenAPI .yaml/.json]:::endpoint --> P1(OpenAPI Parser):::frontend
25-
B[Rust Models / Source]:::endpoint --> P2(Rust Parser):::frontend
26-
C[Actix Routes]:::endpoint --> P3(Framework Parser):::frontend
27-
D[Reqwest Client SDKs]:::endpoint --> P4(Ext Parser):::frontend
23+
A[OpenAPI / Swagger / Arazzo]:::endpoint --> P1(Spec Parser):::frontend
24+
B[Rust Models / Source]:::endpoint --> P2(ra_ap_syntax CST Parser):::frontend
25+
C[Actix-Web & Axum Routes]:::endpoint --> P3(Strategy Route Parser):::frontend
26+
D[Reqwest SDK & Clap CLI]:::endpoint --> P4(Client & Workflow Parser):::frontend
2827
end
2928
3029
subgraph Core [Intermediate Representation]
31-
IR((CDD IR)):::core
30+
IR((CDD IR & Semantic Diff)):::core
3231
end
3332
34-
subgraph Backend [Emitters]
35-
E1(OpenAPI Emitter):::backend --> X[OpenAPI .yaml/.json]:::endpoint
36-
E2(Rust Emitter):::backend --> Y[Rust Models / Structs]:::endpoint
37-
E3(Server Emitter):::backend --> Z[Actix Routes / Controllers]:::endpoint
38-
E4(Client Emitter):::backend --> W[Reqwest Client SDKs]:::endpoint
39-
E5(Data Emitter):::backend --> V[Diesel ORM / Clap CLI]:::endpoint
33+
subgraph Backend [Emitters & CST Patchers]
34+
E1(OpenAPI & Arazzo Emitter):::backend --> X[OpenAPI 3.2.0 & Arazzo 1.1.0]:::endpoint
35+
E2(CST Struct & Enum Patcher):::backend --> Y[Rust Models / Structs]:::endpoint
36+
E3(Server Strategy Emitter):::backend --> Z[Actix-Web & Axum Controllers]:::endpoint
37+
E4(Client Strategy Emitter):::backend --> W[Reqwest SDKs & Workflows]:::endpoint
38+
E5(ORM, CLI & MCP Emitter):::backend --> V[Diesel ORM / Clap CLI / MCP]:::endpoint
4039
end
4140
4241
P1 --> IR
@@ -57,37 +56,36 @@ graph TD
5756

5857
The Frontend's responsibility is to read an input source and translate it into the universal CDD Intermediate Representation (IR).
5958

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-
* **OpenAPI Parsing**: 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.
6261

63-
### 2. Intermediate Representation (IR)
62+
### 2. Intermediate Representation (IR) & Semantic Diffing
6463

65-
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:
65+
* **Models (`ParsedStruct` / `ParsedEnum` / `JsonSchema`)**: Entities containing typed fields, serde/utoipa attributes, required constraints, defaults, and rustdoc descriptions.
66+
* **Endpoints / Operations (`ParsedRoute`)**: HTTP verbs, paths, path/query/header/cookie parameters, request bodies, security requirements, links, callbacks, webhooks, and responses.
67+
* **Workflows (`ArazzoDocument` / `Workflow` / `Step`)**: Multi-step operation DAGs, runtime expressions, criteria, and success/failure actions.
68+
* **Structural Diffs (`StructDiff` / `FieldChange`)**: Computed differences between existing CST nodes and target specifications to drive lossless in-place patching.
6969

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)
7171

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:
7373

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.
76+
* **Client & CLI Emitters (`ReqwestStrategy`, `ClapCliStrategy`, `McpClientStrategy`)**: Create async Reqwest API clients, Arazzo workflow orchestrators, Clap v4 CLI binaries, and MCP client adapters.
77+
* **Database ORM Sync (`DieselMapper`)**: Bridges Diesel `schema.rs` (`dsync`), Rust structs, and OpenAPI schemas.
78+
* **Specification Emitters**: Serialize the IR into compliant OpenAPI 3.2.0, JSON Schema 2020-12, and Arazzo 1.1.0 JSON or YAML documents.
8179

8280
## 🔄 Extensibility
8381

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`.
8785

8886
## 🛡 Design Principles
8987

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.

‎COMPLIANCE.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,17 @@
11
# Compliance
22

33
`cdd-rust` is fully compliant with the following standards:
4-
- **OpenAPI Specification**: 3.2.0 (Full Support)
4+
- **OpenAPI Specification**: 3.2.0 (Full Support) & Swagger 2.0 (Automatic Upgrade & Full Support)
55
- **Arazzo Specification**: 1.1.0 (Full Support)
6+
- **Model Context Protocol (MCP)**: 1.0.0 (`stdio` Server & Generated Client/Server Adapters)
67
- **JSON Schema Dialect**: 2020-12
78
- **Rust Edition**: 2021
89

910
## Conformance Verification
1011

11-
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/).
13+
14+
## OpenAPI 3.2.0 & Swagger 2.0 Support Matrix
1315

1416
| Specification Concept | Status |
1517
| --------------------------- | ------ |

‎DEVELOPING.md‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,33 @@
11
# Developing `cdd-rust`
22

3-
To develop `cdd-rust`, you will need to clone the repository and run standard Cargo tooling.
3+
To develop `cdd-rust`, clone the repository and use either the cross-platform `Makefile` / `make.bat` targets or standard Cargo tooling.
44

55
1. **Clone the Repository:**
66
```bash
7-
git clone https://github.com/offscale/cdd-rust.git
7+
git clone https://github.com/SamuelMarks/cdd-rust.git
88
cd cdd-rust
99
```
1010

1111
2. **Use Make Targets:**
12-
The project includes a `Makefile` / `make.bat`. Use it for common operations:
12+
The project includes a `Makefile` and `make.bat` for common operations:
1313
```bash
14-
make build # Build debug and release
14+
make deps # Fetch Cargo dependencies
15+
make build # Build the release cdd-rust binary
1516
make test # Run unit and integration tests across the workspace
16-
make build_docs # Compile docs locally
17+
make build_docs # Compile rustdoc documentation locally
18+
make build_wasm # Build the wasm32-wasip1 target
1719
```
1820

1921
3. **Project Structure:**
20-
- `core/`: Contains the parsing, emitting, and intermediate representation logic.
21-
- `cli/`: The binary interface.
22-
- `web/`: Actix-web dummy server used in testing.
22+
- `core/` (`cdd-core`): Contains the `ra_ap_syntax` CST parser, semantic differ, patcher, OpenAPI 3.2.0 / Swagger 2.0 / Arazzo 1.1.0 / MCP models, and framework strategies (`actix-web`, `axum`, `reqwest`, `clap`).
23+
- `cli/` (`cdd-cli` / binary `cdd-rust`): Command-line interface and high-level programmatic SDK.
24+
- `web/` (`cdd-web`): Reference multi-tiered Actix-Web + Diesel server supporting stub, production, ephemeral, and fake-seeded execution modes.
2325

24-
4. **Running CI Locally:**
25-
We enforce `clippy` and `rustfmt` cleanly on all modules:
26+
4. **Running CI & Coverage Locally:**
27+
We enforce `rustfmt`, `clippy`, and 100% test and documentation coverage across all workspace members:
2628
```bash
27-
cargo fmt -- --check
28-
cargo clippy --workspace -- -D warnings
29+
cargo fmt --all -- --check
30+
cargo clippy --workspace --all-targets -- -D warnings
31+
cargo test --workspace
32+
python3 scripts/update_coverage.py
2933
```

‎Makefile‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: install_base install_deps build_docs build test run help all build_wasm build_docker run_docker
1+
.PHONY: install_base install_deps deps build_docs build test run help all build_wasm build_docker run_docker
22

33
# If the first argument is "run", we can pass the rest of the arguments to the target
44
ifeq (run,$(firstword $(MAKECMDGOALS)))
@@ -11,27 +11,29 @@ all: help
1111
help:
1212
@echo "Available commands:"
1313
@echo " install_base - Install Rust and required targets"
14-
@echo " install_deps - Install dependencies"
14+
@echo " deps - Fetch Cargo dependencies"
15+
@echo " install_deps - Install dependencies and pre-commit hooks"
1516
@echo " build_docs - Build the API docs. Use DOC_DIR=<path> to specify alternative directory."
1617
@echo " build - Build the CLI binary. Use BIN_DIR=<path> to specify alternative directory."
1718
@echo " test - Run the test suite."
1819
@echo " run - Run the CLI tool."
19-
@echo " build_wasm - Build the WASM target (Note: currently unsupported)"
20+
@echo " build_wasm - Build the WASM (wasm32-wasip1) target."
2021
@echo " build_docker - Build alpine and debian Docker images."
2122
@echo " run_docker - Run the built Docker images to test them."
2223
@echo " setup_hooks - Setup git pre-commit hooks."
2324
@echo " docs - Generate API documentation and symlink to docs/html."
2425

2526
install_base:
2627
rustup update
27-
rustup target add wasm32-unknown-unknown || true
28-
rustup target add wasm32-unknown-emscripten || true
28+
rustup target add wasm32-wasip1 || true
2929

3030
setup_hooks:
3131
pre-commit install
3232

33-
install_deps:
33+
deps:
3434
cargo fetch
35+
36+
install_deps: deps
3537
$(MAKE) setup_hooks
3638

3739

0 commit comments

Comments
 (0)