ffi

Normalize runtime-feature metadata and enforce the narrow public FFI type policy for explicit extern declarations.

Functions:

• build_ffi_callable_info –
• normalize_runtime_features –

build_ffi_callable_info

build_ffi_callable_info(
    context: SemanticContext,
    *,
    signature: FunctionSignature,
    prototype: FunctionPrototype,
) -> FFICallableInfo | None

Source code in src/irx/analysis/ffi.py

@typechecked
def build_ffi_callable_info(
    context: SemanticContext,
    *,
    signature: FunctionSignature,
    prototype: astx.FunctionPrototype,
) -> FFICallableInfo | None:
    """
    title: Build validated public FFI metadata for one extern signature.
    parameters:
      context:
        type: SemanticContext
      signature:
        type: FunctionSignature
      prototype:
        type: astx.FunctionPrototype
    returns:
      type: FFICallableInfo | None
    """
    start_count = len(context.diagnostics.diagnostics)
    parameter_types: list[FFITypeInfo] = []
    for parameter in signature.parameters:
        info = _classify_ffi_type(
            context,
            type_=parameter.type_,
            prototype=prototype,
            position=f"parameter '{parameter.name}'",
            allow_void=False,
            struct_stack=(),
            referenced_via_pointer=False,
        )
        if info is not None:
            parameter_types.append(info)

    return_type = _classify_ffi_type(
        context,
        type_=signature.return_type,
        prototype=prototype,
        position="return type",
        allow_void=True,
        struct_stack=(),
        referenced_via_pointer=False,
    )

    if (
        len(context.diagnostics.diagnostics) != start_count
        or return_type is None
    ):
        return None

    link_strategy = (
        FFILinkStrategy.RUNTIME_FEATURES
        if signature.required_runtime_features
        else FFILinkStrategy.SYSTEM_LINKER
    )
    return FFICallableInfo(
        admissibility=FFIAdmissibility.PUBLIC,
        parameters=tuple(parameter_types),
        return_type=return_type,
        required_runtime_features=signature.required_runtime_features,
        link_strategy=link_strategy,
    )

normalize_runtime_features

normalize_runtime_features(
    prototype: FunctionPrototype,
    *,
    diagnostics: DiagnosticBag,
) -> tuple[str, ...]

Source code in src/irx/analysis/ffi.py

@typechecked
def normalize_runtime_features(
    prototype: astx.FunctionPrototype,
    *,
    diagnostics: DiagnosticBag,
) -> tuple[str, ...]:
    """
    title: Normalize runtime-feature metadata from one prototype.
    parameters:
      prototype:
        type: astx.FunctionPrototype
      diagnostics:
        type: DiagnosticBag
    returns:
      type: tuple[str, Ellipsis]
    """
    raw_feature = getattr(prototype, "runtime_feature", None)
    raw_features = getattr(prototype, "runtime_features", None)

    if raw_feature is not None and raw_features is not None:
        diagnostics.add(
            f"Extern function '{prototype.name}' may use either "
            "'runtime_feature' or 'runtime_features', not both",
            node=prototype,
            code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
        )
        return ()

    if raw_features is None:
        values: Iterable[object] = (
            () if raw_feature is None else (raw_feature,)
        )
    elif isinstance(raw_features, str):
        values = (raw_features,)
    else:
        try:
            values = tuple(raw_features)
        except TypeError:
            diagnostics.add(
                f"Extern function '{prototype.name}' has an invalid "
                "runtime_features value",
                node=prototype,
                code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
            )
            return ()

    normalized: list[str] = []
    seen: set[str] = set()
    known_features = set(_runtime_feature_names())
    for value in values:
        if not isinstance(value, str) or not value.strip():
            diagnostics.add(
                f"Extern function '{prototype.name}' has an invalid runtime "
                "feature name",
                node=prototype,
                code=DiagnosticCodes.RUNTIME_FEATURE_UNKNOWN,
            )
            continue
        if value in seen:
            continue
        seen.add(value)
        normalized.append(value)
        if value not in known_features:
            diagnostics.add(
                f"Extern function '{prototype.name}' requires unknown runtime "
                f"feature '{value}'",
                node=prototype,
                code=DiagnosticCodes.RUNTIME_FEATURE_UNKNOWN,
                notes=(
                    (
                        "known runtime features: "
                        f"{', '.join(sorted(known_features))}"
                    ),
                )
                if known_features
                else (),
            )

    return tuple(normalized)