Refactor AST emitters/parsers for bi-directional IR symmetry, strict typing, and 100% test/doc coverage

- [.gitignore, .coveragerc]: Anchor root-level ignore rules (/client.py, /src/client.py) so src/openapi_client/mcp_client/client.py is tracked; configure branch coverage across src/openapi_client and scripts without scratch-file omissions.
- [src/openapi_client/openapi/keywords.py]: Deduplicate ~3,900 lines of copy-pasted _OPENAPI_3_2_0_FIELDS and _ALL_KEYWORDS tuples across 17 modules into canonical OPENAPI_3_2_0_FIELDS and ALL_KEYWORDS constants.
- [src/openapi_client/classes/{emit,parse}.py]: Support PEP 604 union (T | None), Optional[T], list[T], dict[str, T], required vs optional fields, and $ref schema resolution in both Pydantic emission and LibCST ClassExtractor.
- [src/openapi_client/functions/{emit,parse,utils}.py]: Extract HTTP verb and URL path from client method bodies (self.base_url + ... and self.http.request) in FunctionExtractor so custom operationIds round-trip; guard query string concatenation against trailing '?' when query_params is empty; add get_default_server_url helper.
- [src/openapi_client/fastapi/{emit,parse}.py]: Construct typed PathItem and Operation Pydantic models instead of raw dicts in FastAPIExtractor; support both @app.<method> and @router.<method> decorators; sanitize route tags into valid Python module identifiers; emit 422 JSONResponse when strict_validation is enabled.
- [src/openapi_client/cli_sdk/emit_mcp*.py, src/openapi_client/mcp.py]: Consolidate OpenAPI-to-MCP tool schema extraction into extract_mcp_tools_from_spec; delegate tools/list, resources/list, and resources/read in cli.py:run_mcp_server to openapi_client.mcp; use http.server.HTTPServer in serve_json_rpc.
- [src/openapi_client/cli.py]: Implement --truth filtering in sync_dir; pass args.mcp to generate_from_openapi; merge AST changes on top of openapi.snapshot.json in generate_to_openapi.
- [src/openapi_client/tests/{emit,parse}.py]: Replace hardcoded Petstore/Chaos-audit literals with schema-driven example/default/enum/format resolution and response status code inspection; implement SSE response extraction in ASTTestExtractor; implement parse_cli_sdk_cdd and parse_sqlalchemy_cdd.
- [src/**, scripts/**]: Enforce from __future__ import annotations, complete PEP 484 parameter/return type annotations, remove all # type: ignore suppressions and dead Pydantic v1 fallbacks, and extend scripts/doc_coverage.py to verify argument docstrings.
- [tests/*]: Isolate all filesystem tests via tmp_path/monkeypatch, replace tautological/empty pass tests with behavioral assertions, and consolidate 41 fragmented test files into 12 domain-aligned test modules achieving 100.00% line/branch and docstring coverage.

Author: SamuelMarks

.coveragerc

@@ -1,9 +1,5 @@
 [run]
-omit =
-    src/client.py
-    src/mock_server.py
-    update_models.py
-    update_tests.py
-    update_tests2.py
-    update_tests3.py
-    update_tests4.py
+branch = True
+source =
+    src/openapi_client
+    scripts

.gitignore

@@ -3,54 +3,14 @@ out_server/
 build/
 dist/
 *.xml
-.vscode
-.idea
+.vscode/
+.idea/
 *venv*
-__pycache__
-*.pyc
-coverage.json
-3.2.0.md
-.coverage
-/test_client.py
-openapi.json
-
-client.py
-docs.json
-spec.json
-all_objects.txt
-objects.txt
-compliance-openapi-3-2-0/
-debug_compliance.py
-fix_all.py
-fix_coverage.py
-test_get_terms.py
-update.py
-
-*.wasm
-node_modules/
 __pycache__/
-*.o
-*.so
-target/
-.idea/
-temp-*
-temp-py/
-.git.bak
-test_wasi.js
-
-# ---------------------------------------------------
-# Additional comprehensive exclusions for careless git add .
-# ---------------------------------------------------
-
-# Byte-compiled / optimized / DLL files
 *.py[cod]
 *$py.class
 *.pyd
-
-# C extensions
 *.so
-
-# Distribution / packaging
 .Python
 env/
 venv/
@@ -59,55 +19,31 @@ env.bak/
 venv.bak/
 .env
 .venv
-
-# Unit test / coverage reports
 htmlcov/
 .tox/
 .nox/
 .coverage
 .coverage.*
-.cache
-nosetests.xml
+coverage.json
 coverage.xml
 *.cover
 *.sfdx
 .hypothesis/
 .pytest_cache/
-
-# Jupyter Notebook
+.cache/
+nosetests.xml
 .ipynb_checkpoints
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# mypy
 .mypy_cache/
 .dmypy.json
 dmypy.json
 .pyre/
-
-# OS generated files
 .DS_Store
 .DS_Store?
 ._*
 .Spotlight-V100
 .Trashes
 ehthumbs.db
 Thumbs.db
-
-# ---------------------------------------------------
-# Further comprehensive wildcards for safe `git add .`
-# ---------------------------------------------------
-
-# IDEs and Editors
-.vscode/
-.idea/
 *.swp
 *~
 *.bak
@@ -119,13 +55,9 @@ Thumbs.db
 .cproject
 .pydevproject
 .settings/
-
-# Logs and databases
 *.log
 *.sqlite
 *.sqlite3
-
-# Build and Packaging artifacts
 *.egg-info/
 .eggs/
 *.egg
@@ -136,8 +68,6 @@ Thumbs.db
 *.zip
 MANIFEST
 out/
-
-# Caches and tools
 .ruff_cache/
 .uv_cache/
 .pre-commit-config.yaml.bak
@@ -147,42 +77,45 @@ celerybeat.pid
 *.pid
 *.seed
 *.pid.lock
-
-# Pyenv / Misc
 .python-version
 *.snapshot.json
-
-# Profiling and Patching
 *.patch
 *.diff
 *.pyprof
 *.lprof
 *.pstats
 *.cprof
-
-# ---------------------------------------------------
-# Custom Scratch and Temporary Files
-# ---------------------------------------------------
+*.wasm
+node_modules/
+*.o
+target/
+temp-*
+temp-py/
+.git.bak
+test_wasi.js
+bin/
+*.lock
+prompt*.md
+.tmp_*/
+/3.2.0.md
+/test_client.py
+/openapi.json
+/client.py
+/src/client.py
+/src/mock_server.py
+/docs.json
+/spec.json
+/all_objects.txt
+/objects.txt
+/compliance-openapi-3-2-0/
+/debug_compliance.py
+/fix_all.py
+/fix_coverage.py
+/test_get_terms.py
+/update.py
 /tmp.txt
 /tmp*.txt
 /update_models.py
 /update_tests*.py
 /fix_*.py
-
 /test_pydantic_v1.py
-
-# Pre-commit test directories
-.tmp_swagger/
-.tmp_oas3/
-.pytest_cache
-bin
-
-# Transient and Lock Files
-*.lock
-prompt*.md
-update_models.py
-update_tests.py
-update_tests2.py
-update_tests3.py
-update_tests4.py
-.tmp_*

run_manual_test.py

@@ -1 +1,3 @@
 """Scripts package."""
+
+from __future__ import annotations

scripts/__init__.py

@@ -1,10 +1,13 @@
 """Build script for WebAssembly bundle."""
 
+from __future__ import annotations
+
 import os
 import subprocess
+import zipfile
 
 
-def main():
+def main() -> None:
     """Build WASI output or fallback to zip bundle."""
     os.makedirs("bin", exist_ok=True)
     wasm_out = os.path.join("bin", "cdd-python-all.wasm")
@@ -20,11 +23,8 @@ def main():
         if os.path.exists(wasm_out):
             os.remove(wasm_out)
 
-        # Cross-platform zip
-        import zipfile
-
         with zipfile.ZipFile(wasm_out, "w", zipfile.ZIP_DEFLATED) as zipf:
-            for root, dirs, files in os.walk("src"):
+            for root, _dirs, files in os.walk("src"):
                 for file in files:
                     if "__pycache__" not in root and file.endswith(".py"):
                         file_path = os.path.join(root, file)

scripts/build_wasm.py

@@ -1,11 +1,20 @@
-"""Module for calculating docstring coverage."""
+"""Module for calculating docstring coverage across modules, classes, functions, and arguments."""
+
+from __future__ import annotations
 
 import ast
 import os
 
 
-def calculate_doc_coverage(directory):
-    """Calculate the percentage of functions, classes, and modules with docstrings."""
+def calculate_doc_coverage(directory: str) -> tuple[float, int, int]:
+    """Calculate the percentage of modules, classes, functions, and arguments with docstrings.
+
+    Args:
+        directory: Root directory to scan recursively for `.py` files.
+
+    Returns:
+        A tuple of `(coverage_percentage, documented_count, total_count)`.
+    """
     total = 0
     with_docs = 0
 
@@ -18,10 +27,9 @@ def calculate_doc_coverage(directory):
                 content = f.read()
             try:
                 tree = ast.parse(content)
-            except Exception:
+            except SyntaxError:
                 continue
 
-            # Check module docstring
             total += 1
             if ast.get_docstring(tree):
                 with_docs += 1
@@ -32,18 +40,28 @@ def calculate_doc_coverage(directory):
                 if isinstance(
                     node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
                 ):
-                    # skip private methods but keep __init__
                     if node.name.startswith("__") and node.name != "__init__":
                         continue
-                    # Actually let's just ignore __init__ or count it if the class has a docstring?
-                    # Let's count __init__ as requiring a docstring.
                     total += 1
-                    if ast.get_docstring(node):
+                    doc = ast.get_docstring(node)
+                    if doc:
                         with_docs += 1
                     else:
                         print(f"Missing docstring: {path} :: {node.name}")
 
-    percent = (with_docs / total * 100) if total > 0 else 0
+                    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        for arg in node.args.args:
+                            if arg.arg in ("self", "cls"):
+                                continue
+                            total += 1
+                            if doc and arg.arg in doc:
+                                with_docs += 1
+                            else:
+                                print(
+                                    f"Missing arg docstring: {path} :: {node.name}({arg.arg})"
+                                )
+
+    percent = (with_docs / total * 100) if total > 0 else 0.0
     return percent, with_docs, total