feat: add public deep_resolve_refs() for recursive $ref resolution (0.4.1)

- Expose existing _deep_resolve_refs as public API, matching TypeScript
  deepResolveRefs. 12 new tests covering nested refs, allOf/anyOf/oneOf,
  circular ref depth limiting, and array items.
- README: fix apcore dependency version (0.13.1 → 0.14.0), add 10 missing
  public API entries to Core Modules table.
- Bump version to 0.4.1.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tercel

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.1] - 2026-03-25
+
+### Added
+
+- **`deep_resolve_refs()`** — public API for recursive `$ref` resolution in OpenAPI schemas (previously internal `_deep_resolve_refs`). Resolves nested `allOf`/`anyOf`/`oneOf`, `items`, and `properties`. Depth-limited to 16 levels.
+
+### Fixed
+
+- README: apcore dependency version updated from `>= 0.13.1` to `>= 0.14.0` (matches pyproject.toml).
+- README: Core Modules table now lists all public API functions (added 10 missing entries).
+
 ## [0.4.0] - 2026-03-23
 
 ### Added

README.md

@@ -43,6 +43,15 @@ pip install apcore-toolkit
 | `get_writer` | Factory function for writer instances |
 | `DisplayResolver` | Sparse binding.yaml display overlay — resolves surface-facing alias, description, guidance, tags into `metadata["display"]` (§5.13) |
 | `ConventionScanner` | Scans a `commands/` directory of plain Python files for public functions and converts them to `ScannedModule` instances with schema inferred from type annotations (§5.14) |
+| `extract_input_schema` | Merges OpenAPI query, path, and request body params into a single JSON Schema |
+| `extract_output_schema` | Extracts response schema from OpenAPI operation objects |
+| `resolve_ref` | Resolves a single internal `$ref` JSON pointer |
+| `resolve_schema` | Resolves a top-level `$ref` in a schema |
+| `deep_resolve_refs` | Recursively resolves all `$ref` pointers, depth-limited to 16 levels |
+| `annotations_to_dict` | Converts `ModuleAnnotations` to a plain dict |
+| `module_to_dict` | Converts a `ScannedModule` to a dict for JSON/YAML serialization |
+| `modules_to_dicts` | Batch version of `module_to_dict` |
+| `run_verifier_chain` | Runs multiple verifiers in sequence, stopping on first failure |
 
 ## Usage
 
@@ -214,7 +223,7 @@ Input and output schemas are inferred from PEP 484 type annotations. Use `includ
 ## Requirements
 
 - Python >= 3.11
-- apcore >= 0.13.1
+- apcore >= 0.14.0
 - pydantic >= 2.0
 - PyYAML >= 6.0
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-toolkit"
-version = "0.4.0"
+version = "0.4.1"
 description = "Shared scanner, schema extraction, and output toolkit for apcore framework adapters"
 requires-python = ">=3.11"
 readme = "README.md"

src/apcore_toolkit/__init__.py

@@ -9,6 +9,7 @@
 from apcore_toolkit.display import DisplayResolver
 from apcore_toolkit.formatting import to_markdown
 from apcore_toolkit.openapi import (
+    deep_resolve_refs,
     extract_input_schema,
     extract_output_schema,
     resolve_ref,
@@ -62,6 +63,7 @@
     "YAMLVerifier",
     "YAMLWriter",
     "annotations_to_dict",
+    "deep_resolve_refs",
     "enrich_schema_descriptions",
     "extract_input_schema",
     "extract_output_schema",

src/apcore_toolkit/openapi.py

@@ -85,6 +85,27 @@ def _deep_resolve_refs(
     return result
 
 
+def deep_resolve_refs(
+    schema: dict[str, Any],
+    openapi_doc: dict[str, Any],
+    depth: int = 0,
+) -> dict[str, Any]:
+    """Recursively resolve all ``$ref`` pointers in a schema.
+
+    Handles nested ``$ref``, ``allOf``, ``anyOf``, ``oneOf``, and ``items``.
+    Depth-limited to 16 levels to prevent infinite recursion on circular refs.
+
+    Args:
+        schema: A JSON Schema dict (possibly containing ``$ref`` pointers).
+        openapi_doc: The full OpenAPI document dict.
+        depth: Current recursion depth (callers should not set this).
+
+    Returns:
+        A new schema dict with all ``$ref`` pointers resolved.
+    """
+    return _deep_resolve_refs(schema, openapi_doc, depth)
+
+
 def extract_input_schema(
     operation: dict[str, Any],
     openapi_doc: dict[str, Any] | None = None,

tests/test_openapi.py

@@ -4,6 +4,7 @@
 
 from apcore_toolkit.openapi import (
     _deep_resolve_refs,
+    deep_resolve_refs,
     extract_input_schema,
     extract_output_schema,
     resolve_ref,
@@ -168,6 +169,101 @@ def test_no_mutation_of_original(self) -> None:
         assert OPENAPI_DOC["components"]["schemas"]["Address"]["properties"] == original_props
 
 
+class TestDeepResolveRefsPublic:
+    """Tests for the public deep_resolve_refs wrapper."""
+
+    def test_top_level_ref(self) -> None:
+        schema = {"$ref": "#/components/schemas/User"}
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result["type"] == "object"
+        assert "id" in result["properties"]
+        assert "name" in result["properties"]
+
+    def test_nested_ref_in_properties(self) -> None:
+        schema = {
+            "type": "object",
+            "properties": {
+                "address": {"$ref": "#/components/schemas/Address"},
+            },
+        }
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result["properties"]["address"]["type"] == "object"
+        assert "street" in result["properties"]["address"]["properties"]
+
+    def test_ref_in_allof(self) -> None:
+        schema = {
+            "allOf": [
+                {"$ref": "#/components/schemas/User"},
+                {"type": "object", "properties": {"extra": {"type": "boolean"}}},
+            ]
+        }
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result["allOf"][0]["type"] == "object"
+        assert "id" in result["allOf"][0]["properties"]
+
+    def test_ref_in_anyof(self) -> None:
+        schema = {
+            "anyOf": [
+                {"$ref": "#/components/schemas/User"},
+                {"$ref": "#/components/schemas/Address"},
+            ]
+        }
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert "name" in result["anyOf"][0]["properties"]
+        assert "street" in result["anyOf"][1]["properties"]
+
+    def test_ref_in_oneof(self) -> None:
+        schema = {
+            "oneOf": [
+                {"$ref": "#/components/schemas/User"},
+                {"$ref": "#/components/schemas/Address"},
+            ]
+        }
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result["oneOf"][0]["type"] == "object"
+        assert "name" in result["oneOf"][0]["properties"]
+        assert "city" in result["oneOf"][1]["properties"]
+
+    def test_ref_in_array_items(self) -> None:
+        schema = {"type": "array", "items": {"$ref": "#/components/schemas/User"}}
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result["items"]["type"] == "object"
+        assert "id" in result["items"]["properties"]
+
+    def test_deeply_nested_ref(self) -> None:
+        result = deep_resolve_refs({"$ref": "#/components/schemas/UserWithAddress"}, OPENAPI_DOC)
+        assert result["properties"]["address"]["type"] == "object"
+        assert "street" in result["properties"]["address"]["properties"]
+
+    def test_circular_ref_depth_limit(self) -> None:
+        result = deep_resolve_refs({"$ref": "#/components/schemas/SelfRef"}, OPENAPI_DOC)
+        assert result["type"] == "object"
+        assert "child" in result["properties"]
+
+    def test_no_mutation_of_original(self) -> None:
+        original_address = OPENAPI_DOC["components"]["schemas"]["Address"]
+        original_props = dict(original_address.get("properties", {}))
+        deep_resolve_refs({"$ref": "#/components/schemas/UserWithAddress"}, OPENAPI_DOC)
+        assert OPENAPI_DOC["components"]["schemas"]["Address"]["properties"] == original_props
+
+    def test_custom_depth_parameter(self) -> None:
+        """Passing depth=17 should short-circuit immediately."""
+        schema = {"$ref": "#/components/schemas/User"}
+        result = deep_resolve_refs(schema, OPENAPI_DOC, depth=17)
+        # Should return the unresolved schema since depth > 16
+        assert "$ref" in result
+
+    def test_plain_schema_no_refs(self) -> None:
+        schema = {"type": "string", "description": "A simple string"}
+        result = deep_resolve_refs(schema, OPENAPI_DOC)
+        assert result == {"type": "string", "description": "A simple string"}
+
+    def test_importable_from_package(self) -> None:
+        from apcore_toolkit import deep_resolve_refs as public_fn
+
+        assert callable(public_fn)
+
+
 class TestExtractInputSchema:
     def test_query_and_path_params(self) -> None:
         operation = {