Unify CLI/SQLAlchemy AST round-tripping, enforce strict typing, and eliminate tautological tests

- Consolidate CLI SDK operation extraction in openapi_client.cli_sdk.emit.extract_cli_operations and share it with cli_sdk_cdd, emitting Client(base_url=os.environ.get('API_BASE_URL', ...)) and supporting requestBody (--body) and non-primitive argument types.
- Enhance CLIExtractor in openapi_client.cli_sdk.parse to synthesize PathItem, Operation, Parameter, and RequestBody nodes when extracting from standalone CLI scripts where spec.paths starts empty.
- Implement SQLAlchemyExtractor and extract_sqlalchemy_column in openapi_client.sqlalchemy_cdd.parse to parse declarative Column/mapped_column AST assignments into OpenAPI component schemas and wire models/ extraction into sync_dir(--truth sqlalchemy) and generate_to_openapi.
- Break top-level circular imports between cli, sdk, sync, servers.json_rpc, and servers.mcp_stdio; route MCP stdio tools/call through mcp.execute_tool with normalized argument aliases and add sync_dir to mcp.get_tools().
- Standardize OpenAPI 3.2.0 HTTP_METHODS (including options, head, trace, query) and PathItem.additionalOperations across emitters and AST extractors, and add deterministic PoolManager lifecycle methods (close, __enter__, __exit__) to generated Client classes.
- Introduce build_cst_module to normalize LibCST EmptyLine nodes into statement leading_lines/footer, add PEP 561 py.typed marker, and achieve zero mypy --strict errors across all 99 source and test files.
- Replace tautological and mock-only assertions in test/ and tests/ with behavioral round-trip verification while maintaining 100.00% statement/branch test coverage and 100.00% docstring/argument coverage.

Author: SamuelMarks

.pre-commit-config.yaml

@@ -20,6 +20,18 @@ repos:
     language: system
     pass_filenames: false
     always_run: true
+  - id: mypy
+    name: Mypy Strict Type Check
+    entry: uv run mypy
+    language: system
+    pass_filenames: false
+    always_run: true
+  - id: doc-coverage
+    name: Docstring & Argument Coverage (100%)
+    entry: uv run python scripts/doc_coverage.py
+    language: system
+    pass_filenames: false
+    always_run: true
   - id: test-and-coverage-badges
     name: Run Tests and Update Coverage Badges
     entry: uv run python scripts/update_badges.py

pyproject.toml

@@ -39,11 +39,21 @@ packages = ["src/openapi_client"]
 testpaths = ["tests", "test"]
 
 [tool.mypy]
+packages = ["openapi_client", "scripts", "tests", "test"]
+plugins = ["pydantic.mypy"]
 strict = true
 disallow_any_generics = true
 warn_return_any = true
 warn_unused_ignores = true
 
+[[tool.mypy.overrides]]
+module = ["cdd.*", "fastapi", "fastapi.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["test.mock_server"]
+disallow_untyped_decorators = false
+
 [dependency-groups]
 dev = [
     "pre-commit>=4.3.0",

scripts/run_generated_server_test.py

@@ -18,8 +18,8 @@ def find_free_port() -> int:
         An available port number.
     """
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-        s.bind(("", 0))
         s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind(("", 0))
         port: int = s.getsockname()[1]
         return port
 

scripts/run_petstore_test.py

@@ -18,8 +18,8 @@ def find_free_port() -> int:
         An available port number.
     """
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-        s.bind(("", 0))
         s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind(("", 0))
         port: int = s.getsockname()[1]
         return port
 

src/openapi_client/arazzo/keywords.py

@@ -6,6 +6,7 @@
     "Arazzo Specification Object",
     "arazzo",
     "$self",
+    "self_",
     "info",
     "sourceDescriptions",
     "workflows",
@@ -42,6 +43,7 @@
     "action",
     "Parameter Object",
     "in",
+    "in_",
     "value",
     "Success Action Object",
     "criteria",

src/openapi_client/arazzo/parse.py

@@ -14,9 +14,12 @@
     ReusableObject,
     SuccessAction,
 )
+from openapi_client.exceptions import SpecificationParseError
 from openapi_client.models import OpenAPI, Operation
 from openapi_client.openapi.parse import parse_openapi_dict
 
+SourceDocument = OpenAPI | Arazzo | dict[str, Any]
+
 
 def decode_json_pointer_token(token: str) -> str:
     """Decode an RFC 6901 JSON Pointer reference token (`~1` -> `/`, `~0` -> `~`).
@@ -142,7 +145,7 @@ def resolve_source_descriptions(
     arazzo_spec: Arazzo,
     base_path: Path = Path("."),
     visited: frozenset[Path] = frozenset(),
-) -> dict[str, OpenAPI | Arazzo | dict[str, Any]]:
+) -> dict[str, SourceDocument]:
     """Resolve and load external documents listed in `arazzo_spec.sourceDescriptions`.
 
     Args:
@@ -154,7 +157,7 @@ def resolve_source_descriptions(
         A dictionary mapping each `sourceDescription.name` to its parsed `OpenAPI`,
         `Arazzo`, or raw `dict` representation.
     """
-    resolved: dict[str, OpenAPI | Arazzo | dict[str, Any]] = {}
+    resolved: dict[str, SourceDocument] = {}
     effective_base = base_path
     if arazzo_spec.self_ and not arazzo_spec.self_.startswith(("http://", "https://")):
         self_path = (base_path / arazzo_spec.self_).resolve()
@@ -192,7 +195,7 @@ def resolve_source_descriptions(
 
 def resolve_operation_path(
     operation_path: str,
-    sources: dict[str, OpenAPI | Arazzo | dict[str, Any]],
+    sources: dict[str, SourceDocument],
 ) -> tuple[str | None, str | None, str | None, Operation | None]:
     """Resolve an Arazzo `operationPath` expression to `(source_name, http_method, path, Operation)`.
 
@@ -275,6 +278,12 @@ def parse_arazzo_json(spec_text: str, base_path: Path = Path(".")) -> Arazzo:
 
     Returns:
         The validated `Arazzo` model instance.
+
+    Raises:
+        SpecificationParseError: If `spec_text` is not valid JSON.
     """
-    spec_dict: dict[str, Any] = json.loads(spec_text)
+    try:
+        spec_dict: dict[str, Any] = json.loads(spec_text)
+    except json.JSONDecodeError as err:
+        raise SpecificationParseError(f"Invalid Arazzo JSON: {err}") from err
     return parse_arazzo_dict(spec_dict, base_path)

src/openapi_client/classes/emit.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
+
 import libcst as cst
 
 from openapi_client.docstrings.emit import emit_class_docstring
-from openapi_client.functions.utils import get_annotation_for_schema
+from openapi_client.functions.utils import build_cst_module, get_annotation_for_schema
 from openapi_client.models import Schema, SchemaOrReference
 
 
@@ -127,7 +129,7 @@ def emit_class(name: str, schema: Schema) -> cst.ClassDef:
     )
 
 
-def emit_classes(schemas: dict[str, SchemaOrReference]) -> list[cst.ClassDef]:
+def emit_classes(schemas: Mapping[str, SchemaOrReference]) -> list[cst.ClassDef]:
     """Emit a list of Pydantic BaseModel classes from a dictionary of OpenAPI Schema objects.
 
     Args:
@@ -144,7 +146,7 @@ def emit_classes(schemas: dict[str, SchemaOrReference]) -> list[cst.ClassDef]:
     return class_defs
 
 
-def emit_models_module(schemas: dict[str, SchemaOrReference]) -> str:
+def emit_models_module(schemas: Mapping[str, SchemaOrReference]) -> str:
     """Emit a complete Python module containing Pydantic models.
 
     Args:
@@ -199,5 +201,5 @@ def emit_models_module(schemas: dict[str, SchemaOrReference]) -> str:
         body.append(class_def)
         body.append(cst.EmptyLine())
 
-    module = cst.Module(body=body)
+    module = build_cst_module(body)
     return module.code

src/openapi_client/cli.py

@@ -3,16 +3,17 @@
 from __future__ import annotations
 
 import argparse
+import json
 import os
 import sys
 from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
-from typing import Any
 
 import libcst as cst
 
 from openapi_client.arazzo.emit import emit_arazzo_json
 from openapi_client.arazzo.parse import parse_arazzo_json, resolve_source_descriptions
+from openapi_client.arazzo_models import Arazzo
 from openapi_client.classes.emit import emit_models_module
 from openapi_client.classes.parse import extract_classes_from_ast
 from openapi_client.cli_sdk.emit_arazzo import emit_arazzo_cli_code
@@ -46,6 +47,7 @@
 from openapi_client.servers.json_rpc import JSONRPCRequestHandler, serve_json_rpc
 from openapi_client.servers.mcp_stdio import run_mcp_server
 from openapi_client.sqlalchemy_cdd.emit import emit_sqlalchemy
+from openapi_client.sqlalchemy_cdd.parse import parse_sqlalchemy_cdd
 from openapi_client.sync import sync_dir
 from openapi_client.tests.emit import emit_tests
 from openapi_client.tests.emit_arazzo_tests import emit_arazzo_tests_code
@@ -55,6 +57,40 @@
 from openapi_client.workflows.emit import emit_workflows_code
 from openapi_client.workflows.parse import extract_arazzo_from_code
 
+__all__ = [
+    "JSONRPCRequestHandler",
+    "apply_env_vars_to_parser",
+    "emit_dao",
+    "emit_seeder",
+    "generate_docs_json",
+    "generate_from_arazzo",
+    "generate_from_openapi",
+    "generate_to_arazzo",
+    "generate_to_openapi",
+    "get_version",
+    "main",
+    "run_mcp_server",
+    "serve_json_rpc",
+    "sync_dir",
+]
+
+
+def _resolve_output_dir(output_dir: str) -> Path:
+    """Resolve an output directory or file path to its target directory.
+
+    Args:
+        output_dir: Destination directory or file path string.
+
+    Returns:
+        The resolved directory `Path`.
+    """
+    if not output_dir:
+        output_dir = "."
+    out_path = Path(output_dir)
+    if out_path.suffix.lower() in (".py", ".json", ".yaml", ".yml"):
+        return out_path.parent
+    return out_path
+
 
 def get_version() -> str:
     """Get the installed package version of the CLI.
@@ -86,6 +122,8 @@ def apply_env_vars_to_parser(
                     action.default = val.lower() in ("true", "1", "yes")
                 elif isinstance(action, argparse._StoreFalseAction):
                     action.default = val.lower() not in ("true", "1", "yes")
+                elif action.type in (int, float) and callable(action.type):
+                    action.default = action.type(val)
                 else:
                     action.default = val
         if isinstance(action, argparse._SubParsersAction):
@@ -117,14 +155,7 @@ def generate_from_openapi(
         mcp: If True, generate MCP server, SSE server, and adapter modules.
         arazzo_path: Optional path to a companion Arazzo 1.1.0 specification to bundle.
     """
-    if not output_dir:
-        output_dir = "."
-    out_path = Path(output_dir)
-    if out_path.suffix:
-        out_dir = out_path.parent
-    else:
-        out_dir = out_path
-
+    out_dir = _resolve_output_dir(output_dir)
     out_dir.mkdir(parents=True, exist_ok=True)
 
     if input_path:
@@ -149,8 +180,7 @@ def generate_from_openapi(
             (src_dir / "client.py").write_text(
                 generator.generate_code(), encoding="utf-8"
             )
-
-            if spec.components and getattr(spec.components, "schemas", None):
+            if spec.components and spec.components.schemas:
                 (src_dir / "models.py").write_text(
                     emit_models_module(spec.components.schemas), encoding="utf-8"
                 )
@@ -181,7 +211,7 @@ def generate_from_openapi(
                 generator.generate_code(), encoding="utf-8"
             )
 
-            if spec.components and getattr(spec.components, "schemas", None):
+            if spec.components and spec.components.schemas:
                 (src_dir / "models.py").write_text(
                     emit_models_module(spec.components.schemas), encoding="utf-8"
                 )
@@ -278,13 +308,10 @@ def generate_from_arazzo(
         no_installable_package: If True, skip `pyproject.toml` generation.
         tests: If True, generate end-to-end workflow pytest suites.
     """
-    if not output_dir:
-        output_dir = "."
-    out_path = Path(output_dir)
-    out_dir = out_path.parent if out_path.suffix else out_path
+    out_dir = _resolve_output_dir(output_dir)
     out_dir.mkdir(parents=True, exist_ok=True)
 
-    specs: list[tuple[Path, Any]] = []
+    specs: list[tuple[Path, Arazzo]] = []
     if input_path:
         spec_path = Path(input_path)
         specs.append(
@@ -298,7 +325,8 @@ def generate_from_arazzo(
     elif input_dir:
         for p in Path(input_dir).glob("*.json"):
             raw_text = p.read_text(encoding="utf-8")
-            if '"arazzo"' in raw_text:
+            raw_obj = json.loads(raw_text)
+            if isinstance(raw_obj, dict) and "arazzo" in raw_obj:
                 specs.append((p.parent, parse_arazzo_json(raw_text, p.parent)))
     else:
         print("Either --input or --input-dir is required.")
@@ -423,7 +451,7 @@ def generate_to_arazzo(input_path: str, output_path: str) -> None:
     print(f"Successfully extracted Arazzo spec to {out_path}")
 
 
-def generate_to_openapi(input_path: str, output_path: str) -> None:
+def generate_to_openapi(input_path: str | Path, output_path: str | Path) -> None:
     """Extract an OpenAPI spec from a Python module or directory.
 
     Args:
@@ -458,6 +486,12 @@ def generate_to_openapi(input_path: str, output_path: str) -> None:
         if not models_py.exists():
             models_py = in_path / "models.py"
 
+        models_dir = (
+            in_path / "src" / "models"
+            if (in_path / "src" / "models").is_dir()
+            else in_path / "models"
+        )
+
         mock_py = in_path / "test" / "mock_server.py"
         if not mock_py.exists():
             mock_py = in_path / "mock_server.py"
@@ -475,9 +509,15 @@ def generate_to_openapi(input_path: str, output_path: str) -> None:
             extract_classes_from_ast(mod, spec)
             extract_functions_from_ast(mod, spec)
 
-        if models_py.exists():
+        if models_py.is_file():
             mod = cst.parse_module(models_py.read_text(encoding="utf-8"))
-            extract_classes_from_ast(mod, spec)
+            parse_sqlalchemy_cdd(mod, spec)
+
+        if models_dir.is_dir():
+            for sa_file in sorted(models_dir.glob("*.py")):
+                if sa_file.name != "__init__.py":
+                    mod = cst.parse_module(sa_file.read_text(encoding="utf-8"))
+                    parse_sqlalchemy_cdd(mod, spec)
 
         if mock_py.exists():
             mod = cst.parse_module(mock_py.read_text(encoding="utf-8"))
@@ -516,7 +556,6 @@ def generate_to_openapi(input_path: str, output_path: str) -> None:
 
 def main() -> None:
     """CLI entrypoint."""
-    _ = JSONRPCRequestHandler
     parser = argparse.ArgumentParser(
         description="Compiler Driven Development (CDD) compiler and transpiler."
     )