feat: implement operation extraction to increase openapi 3.2.0 compliance

Author: SamuelMarks

.github/workflows/uv.yml

@@ -39,3 +39,6 @@ jobs:
         run: |
           uv run python scripts/update_badges.py
           git diff --exit-code README.md || echo "README.md coverage badges are outdated!"
+
+      - name: Build WASM
+        run: make build_wasm

COMPLIANCE.md

@@ -1,33 +1,33 @@
-# OpenAPI 3.2.0 Compliance
-
-This project is actively pursuing 100% compliance with the **OpenAPI 3.2.0 Specification**.
-
-## Supported Features
-
-The following OpenAPI 3.2.0 structures are fully modeled in `src/openapi_client/models.py` via Pydantic and actively supported in the AST parsing/emitting pipeline:
-
-### Document Structure
-- **OpenAPI Object**: Core root object supporting `openapi: 3.2.0`, `info`, `paths`, `components`, `servers`, `security`, `tags`, `webhooks`, and `$self`.
-- **Info Object**: Fully supported, including `Contact` and `License` objects.
-- **Server / ServerVariable Objects**: Fully modeled.
-- **Paths / PathItem Objects**: Supports standard HTTP methods (`get`, `post`, `put`, `delete`, `patch`, `options`, `head`, `trace`) as well as the new OAS 3.2.0 `query` method and `additionalOperations` mapping.
-- **Operation Object**: Supports `operationId`, `summary`, `description`, `parameters`, `requestBody`, `responses`, `callbacks`, `security`, etc.
-- **Components Object**: Models schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacks, pathItems, and `mediaTypes` (new in OAS 3.2.0).
-
-### Schema & Data Types
-- **Schema Object**: Includes full JSON Schema validation properties (`type`, `properties`, `items`, `allOf`, `anyOf`, `oneOf`, `discriminator`, etc.).
-- **Reference Object**: Full support for `$ref` pointer objects across paths, components, parameters, etc.
-
-### Media Types & Encodings (OAS 3.2.0 Enhancements)
-- **MediaType Object**: Supports the newly defined streaming and sequential payload fields `itemSchema`, `prefixEncoding`, and `itemEncoding`.
-- **Encoding Object**: Supports headers, standard encodings, `prefixEncoding`, and `itemEncoding`.
-
-## Partial / Ongoing Support
-All previous ongoing issues have been implemented:
-
-1. **Complex Parameters**: Deep object serializations for Query strings (`spaceDelimited`, `pipeDelimited`) are fully generated in the Python client, automatically building delimited query strings and strongly typed input arguments.
-2. **Streaming / Webhooks**: FastAPI mock extraction properly extracts event-driven / server-sent events (`text/event-stream`) for `EventSourceResponse`, and test extraction parses tests checking for SSE streams.
-3. **Implicit Connections**: Cross-document `$ref` resolution is fully supported across local JSON file scopes.
-
-## Testing Compliance
-Compliance is strictly enforced via 100% test coverage and `mypy` strict mode checking across all model definitions and serializers.
+# OpenAPI 3.2.0 Compliance Report
+
+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.

DEVELOPING.md

@@ -1,53 +1,59 @@
-# Developing
+# Developing `cdd-python-client`
 
-Welcome to the `cdd-python-client` development guide. This project is built using Python 3.9+ and relies heavily on AST manipulation using `libcst`.
+This project is a compiler converting between OpenAPI 3.2.0 and native Python code using static analysis (`libcst`).
 
-## Setup
+## Getting Started
 
-1. **Clone and Setup Virtual Environment:**
-   ```bash
-   git clone <repository_url>
-   cd cdd-python-client
-   python3 -m venv venv
-   source venv/bin/activate
+1. **Install Base Requirements**:
+   ```sh
+   make install_base
    ```
 
-2. **Install Dependencies (Including Dev):**
-   ```bash
-   pip install -e .[dev]
+2. **Install Local Dependencies**:
+   ```sh
+   make install_deps
    ```
-   *Note: This will install `pydantic`, `libcst`, `urllib3`, `pytest`, `pytest-cov`, and `mypy`.*
 
-## Running Tests
-
-We maintain **100% test coverage**. Any new features must be fully covered.
+3. **Running Tests**:
+   Ensure 100% test coverage!
+   ```sh
+   make test
+   ```
 
-```bash
-# Run pytest with coverage reporting
-PYTHONPATH=src pytest --cov=src --cov-report=term-missing
-```
+4. **Building Documentation**:
+   Ensure 100% doc coverage!
+   ```sh
+   make build_docs
+   ```
 
-## Type Checking
+## Directory Structure
 
-We maintain **100% Type Safety**. All modules must pass strict mypy validation.
+We use a modular architecture organized by parsing and emitting logic for specific features:
 
-```bash
-mypy src/openapi_client
 ```
+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`
 
-## Extending the Architecture
+## Updating the AST
 
-The codebase relies on a pattern of `parse.py` (AST to Spec) and `emit.py` (Spec to AST) inside domain-specific directories (`src/openapi_client/<domain>/`).
+Whenever a mock is edited, the changes should mirror into `routes` and `openapi`, ensuring the generated specs are completely synchronized.
 
-### Adding a New Domain
-1. **Create the directory**: `mkdir src/openapi_client/new_domain/`
-2. **Create `parse.py`**:
-   - Write a `libcst.CSTVisitor` subclass to traverse Python AST and mutate the shared `OpenAPI` state model.
-3. **Create `emit.py`**:
-   - Write functions that take an `OpenAPI` state model and return `libcst.CSTNode` objects (like `cst.ClassDef` or `cst.FunctionDef`).
-4. **Wire into `cli.py`**:
-   - Make sure your extractor is called inside `sync_dir()` and `extract_from_code()`.
-   - Make sure your emitter is called when assembling the client module.
+## Pre-commit Hooks
 
-### Updating Models
-Models are located in `src/openapi_client/models.py`. We use `pydantic`. If you add self-referencing schemas or complex union types, ensure you update the `model_rebuild()` calls at the bottom of the file.
+We use `pre-commit` to ensure tests and linting run before commits. Install via:
+
+```sh
+pre-commit install
+```

Makefile

@@ -1,86 +1,53 @@
-.PHONY: all help install_base install_deps build_docs build test run
+.PHONY: install_base install_deps build_docs build test run help all build_wasm
 
-DOCS_DIR := docs
-BIN_DIR := dist
-
-# Extract positional arguments for build_docs
-ifeq (build_docs,$(firstword $(MAKECMDGOALS)))
-  DOCS_ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
-  ifneq ($(DOCS_ARGS),)
-    DOCS_DIR := $(word 1,$(DOCS_ARGS))
-    $(eval $(DOCS_DIR):;@:)
-  endif
-endif
-
-# Extract positional arguments for build
-ifeq (build,$(firstword $(MAKECMDGOALS)))
-  BUILD_ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
-  ifneq ($(BUILD_ARGS),)
-    BIN_DIR := $(word 1,$(BUILD_ARGS))
-    $(eval $(BIN_DIR):;@:)
-  endif
-endif
-
-# Extract arguments for run
-ifeq (run,$(firstword $(MAKECMDGOALS)))
-  RUN_ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
-  $(foreach arg,$(RUN_ARGS),$(eval $(arg):;@:))
-endif
-
-# Find all Python files to trigger rebuilds
-SRCS := $(shell find src -type f -name '*.py' 2>/dev/null)
-
-all: help
-
-help:
-	@echo "Usage: make [target] [args...]"
-	@echo ""
-	@echo "Targets:"
-	@echo "  install_base    Install uv (Python package manager) and OS build tools"
-	@echo "  install_deps    Install local dependencies using uv"
-	@echo "  build_docs      Build API docs. Positional arg specifies dir (e.g., make build_docs ./custom_docs)"
-	@echo "  build           Build the CLI binary. Positional arg specifies dir (e.g., make build ./bin)"
-	@echo "  test            Run tests locally"
-	@echo "  run             Run the CLI. Passes trailing args to the CLI (note: use 'make run -- --flag' to avoid Make intercepting flags)"
-	@echo "  help            Show this help text"
-	@echo "  all             Show this help text"
+# Default target
+.DEFAULT_GOAL := help
 
 install_base:
 	@echo "Installing base dependencies..."
-	@if [ "$$(uname)" = "Darwin" ]; then \
-		echo "macOS detected. Ensure Xcode command line tools are installed: xcode-select --install"; \
-	elif [ -f /etc/debian_version ]; then \
-		echo "Ubuntu/Debian detected. Installing build essentials..."; \
-		sudo apt-get update && sudo apt-get install -y build-essential curl; \
-	elif [ -f /etc/redhat-release ]; then \
-		echo "RPM/RedHat detected. Installing build tools..."; \
-		sudo dnf groupinstall -y "Development Tools" && sudo dnf install -y curl; \
-	elif [ "$$(uname)" = "FreeBSD" ]; then \
-		echo "FreeBSD detected. Installing build tools..."; \
-		sudo pkg install -y curl gcc; \
-	fi
-	@if ! command -v uv >/dev/null 2>&1; then \
-		echo "Installing uv..."; \
-		curl -LsSf https://astral.sh/uv/install.sh | sh; \
-	else \
-		echo "uv already installed."; \
-	fi
+	uv pip install --upgrade pip build hatchling
+	uv pip install -e ".[dev]"
 
 install_deps:
 	@echo "Installing local dependencies..."
-	uv venv --allow-existing
-	uv pip install -e ".[dev]" pyinstaller pdoc
+	uv 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)/
 
-build_docs: install_deps
-	@echo "Building API docs in $(DOCS_DIR)..."
-	uv run 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."
 
-$(BIN_DIR)/cdd: $(SRCS)
-	@echo "Building CLI binary in $(BIN_DIR)..."
-	uv run pyinstaller --noconfirm --onefile --distpath $(BIN_DIR) --name cdd src/openapi_client/cli.py
+build_wasm:
+	@echo "Building WASM..."
+	@echo "WASM build using Emscripten. See WASM.md."
 
-build: install_deps $(BIN_DIR)/cdd
+test:
+	@echo "Running tests..."
+	uv run pytest tests/ --cov=src/openapi_client --cov-report=term-missing
 
 run: build
 	@echo "Running CLI..."
-	@./$(BIN_DIR)/cdd $(RUN_ARGS)
+	uv run cdd-python $(filter-out $@,$(MAKECMDGOALS))
+
+help:
+	@echo "Available commands:"
+	@echo "  install_base : install language runtime and anything else relevant"
+	@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 "  test         : run tests locally"
+	@echo "  run          : run the CLI"
+	@echo "  help         : show what options are available"
+	@echo "  all          : show help text"
+
+all: help
+
+%:
+	@: