JSON-RPC server, Dockerfiles, and CLI & doc improvements

Author: SamuelMarks

.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [ master, main ]
+    tags: [ 'v*.*.*' ]
+  pull_request:
+    branches: [ master, main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    - name: Install dependencies
+      run: |
+        pip install uv
+        make install_deps
+    - name: Run pre-commit hooks
+      run: |
+        uv run pre-commit run --all-files
+    - name: Test
+      run: make test
+    - name: Build
+      run: make build
+    - name: Build WASM
+      run: make build_wasm
+    - name: Upload Build Artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-build
+        path: dist/
+
+  release:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/download-artifact@v4
+      with:
+        name: python-build
+        path: dist/
+    - name: Release
+      uses: softprops/action-gh-release@v1
+      with:
+        files: dist/**/*

.github/workflows/uv.yml

@@ -9,3 +9,5 @@ __pycache__
 coverage.json
 3.2.0.md
 .coverage
+test_client.py
+openapi.json

.gitignore

@@ -10,7 +10,7 @@ repos:
     hooks:
     -   id: run-tests-and-update-badges
         name: Run Tests and Update Coverage Badges
-        entry: uv run python scripts/update_badges.py
+        entry: python3 scripts/update_badges.py
         language: system
         pass_filenames: false
         always_run: true

.pre-commit-config.yaml

@@ -1,6 +1,8 @@
+
 # cdd-python-client Architecture
 
 <!-- BADGES_START -->
+<!-- Replace these placeholders with your repository-specific badges -->
 [![License](https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![CI/CD](https://github.com/offscale/cdd-python-client/workflows/CI/badge.svg)](https://github.com/offscale/cdd-python-client/actions)
 [![Coverage](https://codecov.io/gh/offscale/cdd-python-client/branch/master/graph/badge.svg)](https://codecov.io/gh/offscale/cdd-python-client)
@@ -22,7 +24,7 @@ graph TD
 
     subgraph Frontend [Parsers]
         A[OpenAPI .yaml/.json]:::endpoint --> P1(OpenAPI Parser):::frontend
-        B[Python Models / Source]:::endpoint --> P2(Python Parser):::frontend
+        B[LANGUAGE Models / Source]:::endpoint --> P2(LANGUAGE Parser):::frontend
         C[Server Routes / Frameworks]:::endpoint --> P3(Framework Parser):::frontend
         D[Client SDKs / ORMs]:::endpoint --> P4(Ext Parser):::frontend
     end
@@ -33,7 +35,7 @@ graph TD
 
     subgraph Backend [Emitters]
         E1(OpenAPI Emitter):::backend --> X[OpenAPI .yaml/.json]:::endpoint
-        E2(Python Emitter):::backend --> Y[Python Models / Structs]:::endpoint
+        E2(LANGUAGE Emitter):::backend --> Y[LANGUAGE Models / Structs]:::endpoint
         E3(Server Emitter):::backend --> Z[Server Routes / Controllers]:::endpoint
         E4(Client Emitter):::backend --> W[Client SDKs / API Calls]:::endpoint
         E5(Data Emitter):::backend --> V[ORM Models / CLI Parsers]:::endpoint
@@ -51,13 +53,15 @@ graph TD
     IR --> E5
 ```
 
+<!-- INSTRUCTION TO LLM: If this specific repo is explicitly Client-only or Server-only based on the `Client-only`, gracefully adjust the descriptions below to emphasize its specific role. -->
+
 ## 🧩 Core Components
 
 ### 1. The Frontend (Parsers)
 
 The Frontend's responsibility is to read an input source and translate it into the universal CDD Intermediate Representation (IR).
 
-* **Static Analysis (AST-Driven)**: For `Python` 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) via `libcst`, and navigates the tree to extract classes, structs, functions, type signatures, API client definitions, server routes, and docstrings.
+* **Static Analysis (AST-Driven)**: For `Python` 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), and navigates the tree to extract classes, structs, functions, type signatures, API client definitions, server routes, and docstrings.
 * **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.
 
 ### 2. Intermediate Representation (IR)
@@ -74,8 +78,8 @@ By standardizing on a single IR (heavily inspired by OpenAPI / JSON Schema primi
 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).
 
 * **Code Generation**: Emitters iterate over the IR and generate idiomatic `Python` source code.
-  * A **Server Emitter** creates routing controllers and request-validation logic (like mock servers using FastAPI).
-  * A **Client Emitter** creates API wrappers, fetch functions, and response-parsing logic using `urllib3` or `requests`.
+  * A **Server Emitter** creates routing controllers and request-validation logic.
+  * A **Client Emitter** creates API wrappers, fetch functions, and response-parsing logic.
 * **Database & CLI Generation**: Emitters can also target ORM models or command-line parsers by mapping IR properties to database columns or CLI arguments.
 * **Specification Generation**: Emitters translating back to OpenAPI serialize the IR into standard OpenAPI 3.x JSON or YAML, rigorously formatting descriptions, type constraints, and endpoint schemas based on what was parsed from the source code.
 

ARCHITECTURE.md

@@ -1,33 +1,4 @@
-# OpenAPI 3.2.0 Compliance Report
+# Compliance
 
-This document outlines the current level of compliance of `cdd-python-client` with the [OpenAPI 3.2.0 Specification](https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/main/versions/3.2.0.md).
-
-## Currently Implemented
-
-- **OpenAPI Object**: `openapi` version parsing (`3.2.0`), `info`, `paths`, `components` (schemas).
-- **Info Object**: `title`, `version`.
-- **Paths Object**: basic mapping of routes.
-- **Path Item Object**: `get`, `post`, `put`, `delete`, `patch`.
-- **Operation Object**: `operationId`, `parameters`, `requestBody`, `responses`, `deprecated`, `tags`.
-- **Parameter Object**: `name`, `in` (query/path/header/cookie).
-- **RequestBody Object**: `content`, `required`.
-- **Response Object**: `description`, `content`.
-- **Schema Object**: basic types (`string`, `integer`, `boolean`, `array`, `object`, `number`), `properties`, `$ref`.
-- **MediaType Object**: `schema` mapping.
-
-## Missing / Partial Implementation (WIP)
-
-- **OpenAPI Object**: `servers`, `security`, `externalDocs`, `webhooks`.
-- **Info Object**: `description`, `termsOfService`, `contact`, `license`, `summary`.
-- **Server Object** & **Server Variable Object**.
-- **Operation Object**: `callbacks`, `security`, `servers`.
-- **Responses Object**: advanced status mapping.
-- **Header Object**.
-- **Security Scheme Object** & **Security Requirement Object**.
-- **Components Object**: `responses`, `parameters`, `examples`, `requestBodies`, `headers`, `securitySchemes`, `links`, `callbacks`, `pathItems`.
-- **Discriminator Object** & polymorphism (`allOf`, `anyOf`, `oneOf`).
-- **XML Object**.
-
-## Goal
-
-Achieve 100% compliance with OpenAPI 3.2.0 by progressively adding AST mapping for missing components and expanding the Intermediate Representation (IR) to natively support all 3.2.0 features.
+This project aims to be 100% compliant with the OpenAPI 3.2.0 specification.
+Current status: Partial compliance.

COMPLIANCE.md

@@ -1,59 +1,11 @@
-# Developing `cdd-python-client`
+# Developing
 
-This project is a compiler converting between OpenAPI 3.2.0 and native Python code using static analysis (`libcst`).
-
-## Getting Started
-
-1. **Install Base Requirements**:
-   ```sh
-   make install_base
-   ```
-
-2. **Install Local Dependencies**:
-   ```sh
-   make install_deps
-   ```
-
-3. **Running Tests**:
-   Ensure 100% test coverage!
-   ```sh
-   make test
-   ```
-
-4. **Building Documentation**:
-   Ensure 100% doc coverage!
-   ```sh
-   make build_docs
-   ```
-
-## Directory Structure
-
-We use a modular architecture organized by parsing and emitting logic for specific features:
+To develop `cdd-python-client`, you will need Python 3.9+.
 
+```bash
+make install_deps
+make test
+make build
 ```
-src/openapi_client/
-├── classes/       # Parsing & emitting class definitions
-├── docstrings/    # Parsing & emitting Python docstrings
-├── functions/     # Parsing & emitting function signatures
-├── mocks/         # Generating mock servers
-├── openapi/       # Parsing & emitting OpenAPI JSON
-├── routes/        # Parsing & emitting routing configurations
-└── tests/         # Generating unit tests
-```
-
-Each subdirectory contains:
-- `parse.py`: Extracts information from Python AST or OpenAPI dicts to populate the unified Intermediate Representation (IR).
-- `emit.py`: Uses the unified IR to generate target code (Python AST) or OpenAPI JSON.
-- `__init__.py`
-
-## Updating the AST
-
-Whenever a mock is edited, the changes should mirror into `routes` and `openapi`, ensuring the generated specs are completely synchronized.
 
-## Pre-commit Hooks
-
-We use `pre-commit` to ensure tests and linting run before commits. Install via:
-
-```sh
-pre-commit install
-```
+We aim for 100% doc coverage and 100% test coverage on all PRs.

DEVELOPING.md

@@ -1,53 +1,92 @@
-.PHONY: install_base install_deps build_docs build test run help all build_wasm
+.PHONY: install_base install_deps build_docs build test run help all build_wasm build_docker run_docker
 
-# Default target
 .DEFAULT_GOAL := help
 
+# Extract arguments for build, build_docs, run
+ifeq ($(firstword $(MAKECMDGOALS)),build)
+  BIN_DIR := $(word 2,$(MAKECMDGOALS))
+  ifeq ($(BIN_DIR),)
+    BIN_DIR := dist
+  else
+    $(eval $(BIN_DIR):;@:)
+  endif
+endif
+
+ifeq ($(firstword $(MAKECMDGOALS)),build_docs)
+  DOCS_DIR := $(word 2,$(MAKECMDGOALS))
+  ifeq ($(DOCS_DIR),)
+    DOCS_DIR := docs
+  else
+    $(eval $(DOCS_DIR):;@:)
+  endif
+endif
+
+ifeq ($(firstword $(MAKECMDGOALS)),run)
+  RUN_ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
+  $(eval $(RUN_ARGS):;@:)
+endif
+
 install_base:
-	@echo "Installing base dependencies..."
-	uv python install
-	uv pip install --upgrade pip build hatchling
-	uv pip install -e ".[dev]"
+	@echo "Installing base tools (Python 3)"
+	@if [ -x "$$(command -v apt-get)" ]; then sudo apt-get update && sudo apt-get install -y python3 python3-pip python3-venv; fi
+	@if [ -x "$$(command -v brew)" ]; then brew install python; fi
+	@if [ -x "$$(command -v dnf)" ]; then sudo dnf install -y python3 python3-pip; fi
+
 install_deps:
-	@echo "Installing local dependencies..."
-	uv pip install -e ".[dev]"
+	pip install uv || pip3 install uv
+	uv venv || python3 -m venv .venv
+	uv pip install -e ".[dev]" || pip install -e ".[dev]"
 
 build_docs:
-	@echo "Building docs..."
-	@mkdir -p $(if $(word 2, $(MAKECMDGOALS)),$(word 2, $(MAKECMDGOALS)),docs)
-	uv run python -m pydoc -w src/openapi_client/cli.py
-	@mv cli.html $(if $(word 2, $(MAKECMDGOALS)),$(word 2, $(MAKECMDGOALS)),docs)/
+	@echo "Building docs in $(DOCS_DIR)"
+	@mkdir -p $(DOCS_DIR)
+	.venv/bin/python3 -m pdoc src/openapi_client -o $(DOCS_DIR) || pdoc src/openapi_client -o $(DOCS_DIR)
 
 build:
-	@echo "Building CLI binary (wheel)..."
-	uv run python -m build --wheel --outdir $(if $(word 2, $(MAKECMDGOALS)),$(word 2, $(MAKECMDGOALS)),dist)
-	@echo "Build complete."
+	@echo "Building binary/package in $(BIN_DIR)"
+	@mkdir -p $(BIN_DIR)
+	.venv/bin/python3 -m build --wheel --outdir $(BIN_DIR) || python3 -m build --wheel --outdir $(BIN_DIR)
 
 build_wasm:
-	@echo "Building WASM..."
-	@echo "WASM build using Emscripten. See WASM.md."
+	@echo "Building WASM to dist/wasm"
+	@mkdir -p dist/wasm
+	@echo "A full CPython WASM standalone build requires Pyodide. Stubbed for now." > dist/wasm/README.txt
 
 test:
-	@echo "Running tests..."
-	uv run pytest tests/ --cov=src/openapi_client --cov-report=term-missing
+	.venv/bin/python3 -m pytest tests/ || pytest tests/
 
 run: build
-	@echo "Running CLI..."
-	uv run cdd-python $(filter-out $@,$(MAKECMDGOALS))
+	.venv/bin/python3 -m openapi_client.cli $(RUN_ARGS) || cdd-python $(RUN_ARGS)
 
 help:
-	@echo "Available commands:"
-	@echo "  install_base : install language runtime and anything else relevant"
+	@echo "Available tasks:"
+	@echo "  install_base : install language runtime (Python 3)"
 	@echo "  install_deps : install local dependencies"
-	@echo "  build_docs   : build the API docs and put them in the 'docs' directory"
-	@echo "  build        : build the CLI binary"
-	@echo "  build_wasm   : build the WASM binary"
+	@echo "  build_docs   : build the API docs [dir]"
+	@echo "  build        : build the CLI [dir]"
 	@echo "  test         : run tests locally"
-	@echo "  run          : run the CLI"
-	@echo "  help         : show what options are available"
-	@echo "  all          : show help text"
+	@echo "  run          : run the CLI [args...]"
+	@echo "  build_wasm   : build WASM output"
+	@echo "  build_docker : build Docker images"
+	@echo "  run_docker   : run and test Docker containers"
+	@echo "  help         : show this help text"
+	@echo "  all          : show this help text"
 
 all: help
 
-%:
-	@:
+build_docker:
+	@echo "Building Docker images"
+	docker build -t cdd-python-client-alpine -f alpine.Dockerfile .
+	docker build -t cdd-python-client-debian -f debian.Dockerfile .
+
+run_docker: build_docker
+	docker run -d -p 8080:8080 --name cdd_alpine cdd-python-client-alpine
+	sleep 3
+	curl -X POST http://localhost:8080 -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "missing", "id": 1}' || echo "container failed to respond"
+	docker stop cdd_alpine
+	docker rm cdd_alpine
+	docker run -d -p 8080:8080 --name cdd_debian cdd-python-client-debian
+	sleep 3
+	curl -X POST http://localhost:8080 -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "missing", "id": 1}' || echo "container failed to respond"
+	docker stop cdd_debian
+	docker rm cdd_debian