bug: [P2] Python public API surface hashes ignore async, type annotation, and method changes

[aoto-tech]

Scope

Commit: 1a88d503e83ceb6688d41be1e00495abfd17f054 (0.4.0)

Actual behavior

Python public API surface serialization does not preserve the distinction between synchronous and asynchronous functions, type annotations, or class method definitions. As a result, changes that break compatibility can still produce the same hash used for API comparison.

Each of the following pairs was passed to the built-in Python inspector, and the returned surfaceParts and their SHA-256 hashes were compared.

# Pair 1: Synchronous function changed to an asynchronous function
# before
def api(value):
    return value
# after
async def api(value):
    return value

Both produced ["py:function:api(value)"] with SHA-256 76d7e4ffc6b818310b87ecf4b0145de29143e7e61dfbf275940893fb2585e149. The function now returns a coroutine instead of a regular value, requiring callers to change how they invoke it.

# Pair 2
# before: def api(value: str) -> str: ...
# after:  def api(value: int) -> int: ...

# Pair 3
# before
class Api:
    def fetch(self, value):
        return value
# after
class Api:
    def fetch(self, value, required):
        return required

The type annotation pair also produced the same function representation and hash. Both versions in the class pair produced ["py:class:Api()"] with SHA-256 81536ae12c7e641b3e8b1c98f421205b5df618ed590c9f57ff377c9bcff1fe8e. The inspector's errors array was empty for all six inputs.

Expected behavior

The public API representation should reflect changes that make public functions asynchronous, change type annotations, or add required arguments to public methods. Changes confined to a function body should not count as API changes.

Cause

• function_signature does not include argument type annotations.
• The FunctionDef/AsyncFunctionDef branch uses the same representation for both and also omits return types.
• The ClassDef branch stores only the class name and base classes.
• Python signature retrieval and hash generation use this representation.

Validation scope

The PYTHON_INSPECTOR implementation from the affected source was executed unchanged in memory, replacing only the input from tokenize.open with io.StringIO. No repository files were modified on disk, and no integration tests of the baseline command were run.

If you find this repository useful, please consider giving it a star.