|
1 | 1 | cdd-java |
2 | | -======== |
| 2 | +============ |
| 3 | + |
3 | 4 | [](https://opensource.org/licenses/Apache-2.0) |
4 | 5 | [](https://offscale.io/wasm_web_demo) |
5 | 6 | [](https://github.com/SamuelMarks/cdd-java/actions) |
6 | 7 | [](#) |
7 | 8 | [](#) |
8 | 9 |
|
9 | | ----- |
| 10 | +**Compiler Driven Development (CDD)** is a development approach designed to eradicate the disconnect between: API specifications; server implementations; client SDKs; and command-line tooling. |
10 | 11 |
|
11 | | -OpenAPI ↔ Java. This is one compiler in a suite, all focussed on the same task: Compiler Driven Development (CDD). |
| 12 | +Unlike traditional code generators—that treat outputs as disposable or read-only—CDD provides a **complete, standalone compiler** for each supported language. These compilers are fully CST-aware (Concreate Syntax Tree is a whitespace+comment aware Abstract Syntax Tree), allowing true bidirectional synchronization between existing hand-edited source code and OpenAPI specifications. |
12 | 13 |
|
13 | | -Each compiler is written in its target language, is whitespace and comment sensitive, and has both an SDK and CLI. |
| 14 | +--- |
14 | 15 |
|
15 | | -The core philosophy of Compiler Driven Development (CDD) is synchronization without compromise. Where traditional generators silo your API boundaries into read-only files, this compiler natively merges changes into your codebase via a robust, [whitespace and comment aware] Abstract Syntax Tree (AST) driven parser & emitter. It bridges the gap between design and implementation, allowing you to seamlessly generate SDKs from a spec or extract a spec from existing code. By keeping your APIs, SDKs, and tests in continuous, automated alignment, it drastically improves both delivery speed and software reliability. |
| 16 | +## 🏗️ The Standalone Compiler Architecture |
16 | 17 |
|
17 | | -The CLI—at a minimum—has: |
| 18 | +Traditional tools use naïve templating—if you regenerate, your custom code is overwritten. |
18 | 19 |
|
19 | | -- `cdd-java --help` |
20 | | -- `cdd-java --version` |
21 | | -- `cdd-java from_openapi to_sdk_cli -i spec.json` |
22 | | -- `cdd-java from_openapi to_sdk -i spec.json` |
23 | | -- `cdd-java from_openapi to_server -i spec.json` |
24 | | -- `cdd-java to_openapi -f path/to/code` |
25 | | -- `cdd-java to_docs_json --no-imports --no-wrapping -i spec.json` |
26 | | -- `cdd-java serve_json_rpc --port 8080 --listen 0.0.0.0` (provides Model Context Protocol (MCP) server) |
| 20 | +The CDD ecosystem is fundamentally different. It utilizes language-specific, standalone compilers capable of full AST parsing, semantic diffing, and surgical patching. |
27 | 21 |
|
28 | | -## SDK Example |
| 22 | +**The Core Guarantee:** Every part of the generated codebase is fully editable. |
| 23 | +You are encouraged to open the generated routing files, model definitions, and CLI structures, and directly inject your business logic. |
29 | 24 |
|
30 | | -```java |
31 | | -import com.cdd.CddGenerator; |
32 | | -import com.cdd.Config; |
| 25 | +- **When your specification changes**, the CDD compiler reads your code, builds an AST, diffs it against the new spec, and safely patches in new endpoints or fields without touching your custom logic. |
| 26 | +- **When your codebase changes**, the compiler reverse-engineers your structural updates back into a 100% accurate, authoritative OpenAPI specification. |
33 | 27 |
|
34 | | -public class Main { |
35 | | - public static void main(String[] args) { |
36 | | - Config config = new Config("spec.json", "src/models"); |
37 | | - CddGenerator.generateSdk(config); |
38 | | - System.out.println("SDK generation complete."); |
39 | | - } |
40 | | -} |
41 | | -``` |
| 28 | +--- |
42 | 29 |
|
43 | | -## Installation |
| 30 | +## 🔄 The Bidirectional Synchronization Loop |
44 | 31 |
|
45 | | -```bash |
46 | | -mvn compile |
47 | | -``` |
| 32 | +```mermaid |
| 33 | +flowchart TD |
| 34 | + OAS["📄 OpenAPI v3 Spec"] <--> CDD{"⚙️ CDD Compiler"} |
48 | 35 |
|
49 | | -## Development |
50 | | - |
51 | | -You can use standard tooling commands or the included cross-platform Makefiles to fetch dependencies, build, and test: |
52 | | - |
53 | | -```bash |
54 | | -mvn compile |
55 | | -mvn test |
56 | | -# or |
57 | | -make deps |
58 | | -make build |
59 | | -make test |
60 | | -# or on Windows |
61 | | -.\make.bat deps |
62 | | -.\make.bat build |
63 | | -.\make.bat test |
64 | | -``` |
| 36 | + CDD <--> Codebase |
65 | 37 |
|
66 | | -See [PUBLISH.md](PUBLISH.md) for packaging and releasing. |
| 38 | + subgraph Codebase ["💻 Application Codebase"] |
| 39 | + direction TB |
67 | 40 |
|
68 | | -## Features |
| 41 | + subgraph Outputs ["📦 Primary Outputs"] |
| 42 | + direction TB |
| 43 | + CLI["⌨️ CLI Tooling"] |
| 44 | + SDK["📦 Client SDK"] |
| 45 | + Server["🖥️ Server"] |
69 | 46 |
|
70 | | -The `cdd-java` compiler leverages a unified architecture to support various facets of API and code lifecycle management. For a deep dive into the compiler's design, see [ARCHITECTURE.md](ARCHITECTURE.md). |
| 47 | + %% Force vertical stacking inside the subgraph |
| 48 | + CLI ~~~ SDK ~~~ Server |
| 49 | + end |
71 | 50 |
|
72 | | -- **Compilation**: |
73 | | - - **OpenAPI → `Java`**: Generate idiomatic native models, network routes, client SDKs, and boilerplate directly from OpenAPI (`.json` / `.yaml`) specifications. |
74 | | - - **`Java` → OpenAPI**: Statically parse existing `Java` source code and emit compliant OpenAPI specifications. |
75 | | -- **AST-Driven & Safe**: Employs static analysis instead of unsafe dynamic execution or reflection, allowing it to safely parse and emit code even for incomplete or un-compilable project states. |
76 | | -- **Model Context Protocol (MCP)**: Native JSON-RPC server (`serve_json_rpc`) enabling LLMs and agents to discover and interact with the codebase tools. |
77 | | -- **Seamless Sync**: Keep your docs, tests, database, clients, and routing in perfect harmony. Update your code, and generate the docs; or update the docs, and generate the code. |
| 51 | + subgraph Core ["🔗 Core Architecture"] |
| 52 | + direction TB |
| 53 | + Models["🔗 Data Models"] |
| 54 | + Routes["🔀 API Routes"] |
| 55 | + Tests["🧪 Tests"] |
78 | 56 |
|
79 | | -**Uncommon Features:** |
| 57 | + %% Force vertical stacking inside the subgraph |
| 58 | + Models ~~~ Routes ~~~ Tests |
| 59 | + end |
80 | 60 |
|
81 | | -`cdd-java` supports standard CDD features. |
| 61 | + Mocks["🎭 API Mocks / Fakes"] |
82 | 62 |
|
83 | | -## CLI Options |
| 63 | + %% Simple dependency flow down the page |
| 64 | + Outputs --> Core |
| 65 | + Tests --> Mocks |
| 66 | + end |
84 | 67 |
|
85 | | -```text |
86 | | -Usage: cdd-java [OPTIONS] <COMMAND> |
| 68 | + style OAS fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px |
| 69 | + style CDD fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px |
| 70 | + style Codebase fill:#fafafa,stroke:#9e9e9e,stroke-width:2px,stroke-dasharray: 5 5 |
| 71 | + style Outputs fill:#e8f5e9,stroke:#43a047,stroke-width:2px |
| 72 | + style Core fill:#fff3e0,stroke:#f57c00,stroke-width:2px |
87 | 73 | ``` |
88 | 74 |
|
| 75 | +The CDD lifecycle supports continuous evolution from any starting point: |
| 76 | +1. **Generate**: Scaffold servers, SDKs, or CLIs from a central specification. |
| 77 | +2. **Edit**: Developers write real, unconstrained code directly in the generated files. |
| 78 | +3. **Extract**: Reverse-compile the edited code to produce an updated OpenAPI spec. |
| 79 | +4. **Sync**: Apply new specification changes seamlessly into the existing, hand-edited codebase. |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +## 🌐 The Global Language Ecosystem |
| 84 | + |
| 85 | +Every supported language operates on the same core CDD philosophies but is powered by a dedicated, native compiler tailored to that language's specific AST, idioms, and package management. |
| 86 | + |
| 87 | +All implementations share a standardized CLI interface (`cdd [subcommand]`), acting as a universal toolchain. |
| 88 | + |
| 89 | +| Repository | Language | Client; Client CLI; Server | Extra features | Standards | CI Status | |
| 90 | +|---|---|---|---|---|---| |
| 91 | +| [`cdd-c`](https://github.com/SamuelMarks/cdd-c) | C (C89) | Client; Client CLI; Server | FFI | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/SamuelMarks/cdd-c/actions/workflows/ci.yml) | |
| 92 | +| [`cdd-cpp`](https://github.com/SamuelMarks/cdd-cpp) | C++ | Client; Client CLI; Server | Upgrades Swagger & Google Discovery to OpenAPI 3.2.0 | Google Discovery; Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/SamuelMarks/cdd-cpp/actions/workflows/ci.yml) | |
| 93 | +| [`cdd-csharp`](https://github.com/SamuelMarks/cdd-csharp) | C# | Client; Client CLI; Server | CLR | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/SamuelMarks/cdd-csharp/actions/workflows/ci.yml) | |
| 94 | +| [`cdd-go`](https://github.com/SamuelMarks/cdd-go) | Go | Client; Client CLI; Server | | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/SamuelMarks/cdd-go/actions/workflows/ci.yml) | |
| 95 | +| [`cdd-java`](https://github.com/SamuelMarks/cdd-java) | Java | Client; Client CLI; Server | | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/SamuelMarks/cdd-java/actions/workflows/ci.yml) | |
| 96 | +| [`cdd-kotlin`](https://github.com/offscale/cdd-kotlin) | Kotlin (ktor for Multiplatform) | Client; Client CLI; Server | Auto-Admin UI | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/offscale/cdd-kotlin/actions/workflows/ci.yml) | |
| 97 | +| [`cdd-php`](https://github.com/SamuelMarks/cdd-php) | PHP | Client; Client CLI; Server | | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/SamuelMarks/cdd-php/actions/workflows/ci.yml) | |
| 98 | +| [`cdd-python`](https://github.com/offscale/cdd-python) | Python | N/A (server building blocks) | CLI ↔ SQL ↔ Pydantic ↔ docs ↔ JSON-schema | N/A | [](https://github.com/offscale/cdd-python/actions) | |
| 99 | +| [`cdd-python-all`](https://github.com/offscale/cdd-python-all) | Python | Client; Client CLI; Server | | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/offscale/cdd-python-all/actions/workflows/ci.yml) | |
| 100 | +| [`cdd-ruby`](https://github.com/SamuelMarks/cdd-ruby) | Ruby | Client; Client CLI; Server | | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/SamuelMarks/cdd-ruby/actions/workflows/ci.yml) | |
| 101 | +| [`cdd-rust`](https://github.com/SamuelMarks/cdd-rust) | Rust | Client; Client CLI; Server | | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/offscale/cdd-rust/actions/workflows/ci.yml) | |
| 102 | +| [`cdd-sh`](https://github.com/SamuelMarks/cdd-sh) | Shell (/bin/sh) | Client; Client CLI; Server | | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/SamuelMarks/cdd-sh/actions/workflows/ci.yml) | |
| 103 | +| [`cdd-swift`](https://github.com/SamuelMarks/cdd-swift) | Swift | Client; Client CLI; Server | | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/SamuelMarks/cdd-swift/actions/workflows/ci.yml) | |
| 104 | +| [`cdd-ts`](https://github.com/offscale/cdd-ts) | TypeScript | Client; Client CLI; Server | Auto-Admin UI; Angular; React; Vue; fetch; Axios; Node.js | Swagger 2.0 & OpenAPI 3.2.0 | [](https://github.com/offscale/cdd-ts/actions/workflows/ci.yml) | |
| 105 | + |
| 106 | +--- |
| 107 | + |
| 108 | +## 🛠️ Universal CLI Toolchain |
| 109 | + |
| 110 | +A true ecosystem requires standardized tooling. Once a developer learns the CDD toolchain, they can synchronize architecture across the entire polyglot stack. |
| 111 | + |
| 112 | +### Global Arguments |
| 113 | + |
| 114 | +- `--help`: Print help information. |
| 115 | +- `--version`: Print version information. |
| 116 | +- `--input, -i` (or `-f`): Target file, directory, or OpenAPI spec. |
| 117 | +- `--output, -o`: Destination path for generation or sync. |
| 118 | + |
| 119 | +### Core Subcommands |
| 120 | + |
| 121 | +#### `from_openapi to_sdk_cli` |
| 122 | +Generate a client SDK and a corresponding command-line interface (CLI) from an OpenAPI specification. |
| 123 | +- `--input, -i <spec>`: Path to the OpenAPI specification file. |
| 124 | + |
| 125 | +#### `from_openapi to_sdk` |
| 126 | +Generate a client SDK from an OpenAPI specification. |
| 127 | +- `--input, -i <spec>`: Path to the OpenAPI specification file. |
| 128 | + |
| 129 | +#### `from_openapi to_server` |
| 130 | +Generate server boilerplate, models, and routing logic from an OpenAPI specification. |
| 131 | +- `--input, -i <spec>`: Path to the OpenAPI specification file. |
| 132 | + |
| 133 | +#### `to_openapi` |
| 134 | +Parse the existing codebase and extract an authoritative OpenAPI specification. |
| 135 | +- `--input, -i <path>` (or `-f <path>`): Path to the source code directory or file to parse. |
| 136 | + |
| 137 | +#### `to_docs_json` |
| 138 | +Convert an OpenAPI specification into a localized, documentation-optimized JSON format. |
| 139 | +- `--input, -i <spec>`: Path to the OpenAPI specification file. |
| 140 | +- `--no-imports`: Disable import statements in the generated documentation. |
| 141 | +- `--no-wrapping`: Disable line wrapping in the generated documentation. |
| 142 | + |
| 143 | +#### `serve_json_rpc` |
| 144 | +Launch a JSON-RPC server for editor and tool integrations. |
| 145 | +- `--port <port>` (or `-p`): Port to listen on (e.g., `8080`). |
| 146 | +- `--listen <address>` (or `-l`): Address to bind to (e.g., `0.0.0.0`). |
| 147 | + |
| 148 | +#### `from_openapi to_orm` |
| 149 | +Generate ORM entities from an OpenAPI specification. |
| 150 | +- `--input, -i <spec>`: Path to the OpenAPI specification file. |
| 151 | + |
| 152 | +#### `sync` |
| 153 | +Synchronize database schema to models and OpenAPI specifications. |
| 154 | +- `-d <dir>`: Directory containing the code to synchronize. |
| 155 | + |
| 156 | +### Detail Features Beyond Common Subset |
| 157 | + |
| 158 | +- **ORM Generation (`from_openapi to_orm`)**: Generates Hibernate ORM entities from the OpenAPI spec. |
| 159 | +- **Two-way Syncing (`sync`)**: Syncs codebase updates across models, ORM entities, routes, tests, and CLI logic. |
| 160 | +- **WASI Compatibility**: The JSON-RPC server (`serve_json_rpc`) supports a `--wasi` flag, making it compatible with WASI stdio constraints. |
| 161 | +- **In-Memory Tooling Integration**: Implements `process_in_memory` via JSON-RPC, enabling in-memory code generation (SDK, Server, ORM) without making intermediate filesystem changes—ideal for editor plugins. |
| 162 | + |
| 163 | +--- |
| 164 | + |
| 165 | +## 🚀 The End of "Spec Drift" |
| 166 | + |
| 167 | +With Compiler Driven Development, specifications and code are no longer loosely coupled artifacts. They are strict, isomorphic reflections of one another, maintained by dedicated standalone compilers. |
| 168 | + |
| 169 | +Choose your language ecosystem above and start treating your architecture as a seamlessly compiled, endlessly editable whole. |
| 170 | + |
89 | 171 | --- |
90 | 172 |
|
91 | 173 | ## License |
|
0 commit comments