registry

Centralize semantic declaration and top-level registration policy so the analyzer delegates identity and duplicate handling to a smaller subsystem.

Classes:

• SemanticRegistry –

SemanticRegistry

SemanticRegistry(
    context: SemanticContext, factory: SemanticEntityFactory
)

Register locals, functions, and structs while enforcing the duplicate declaration rules that semantic analysis currently exposes. attributes: context: type: SemanticContext factory: type: SemanticEntityFactory

Methods:

• declare_local –
• normalize_function_signature –
• register_class –
• register_function –
• register_struct –
• resolve_class –
• resolve_function –
• resolve_struct –
• signatures_match –

Source code in packages/irx/src/irx/analysis/registry.py

def __init__(
    self,
    context: SemanticContext,
    factory: SemanticEntityFactory,
) -> None:
    """
    title: Initialize SemanticRegistry.
    parameters:
      context:
        type: SemanticContext
      factory:
        type: SemanticEntityFactory
    """
    self.context = context
    self.factory = factory

declare_local

declare_local(
    name: str,
    type_: DataType,
    *,
    is_mutable: bool,
    declaration: AST,
    kind: str = "variable",
) -> SemanticSymbol

Source code in packages/irx/src/irx/analysis/registry.py

def declare_local(
    self,
    name: str,
    type_: astx.DataType,
    *,
    is_mutable: bool,
    declaration: astx.AST,
    kind: str = "variable",
) -> SemanticSymbol:
    """
    title: Declare one lexical symbol.
    parameters:
      name:
        type: str
      type_:
        type: astx.DataType
      is_mutable:
        type: bool
      declaration:
        type: astx.AST
      kind:
        type: str
    returns:
      type: SemanticSymbol
    """
    symbol = self.factory.make_variable_symbol(
        self._current_module_key(),
        name,
        type_,
        is_mutable=is_mutable,
        declaration=declaration,
        kind=kind,
    )
    current_scope = self.context.scopes.current
    existing = (
        current_scope.symbols.get(name)
        if current_scope is not None
        else None
    )
    if not self.context.scopes.declare(symbol):
        self.context.diagnostics.add(
            f"Identifier already declared: {name}",
            node=declaration,
            code=DiagnosticCodes.SEMANTIC_DUPLICATE_DECLARATION,
            related=(
                ()
                if existing is None or existing.declaration is None
                else (
                    DiagnosticRelatedInformation(
                        "previous declaration is here",
                        node=existing.declaration,
                        module_key=existing.module_key,
                    ),
                )
            ),
        )
    return symbol

normalize_function_signature

normalize_function_signature(
    prototype: FunctionPrototype,
    *,
    definition: FunctionDef | None = None,
    validate_ffi: bool = True,
    validate_main: bool = True,
) -> FunctionSignature

Source code in packages/irx/src/irx/analysis/registry.py

def normalize_function_signature(
    self,
    prototype: astx.FunctionPrototype,
    *,
    definition: astx.FunctionDef | None = None,
    validate_ffi: bool = True,
    validate_main: bool = True,
) -> FunctionSignature:
    """
    title: Normalize and validate one semantic function signature.
    parameters:
      prototype:
        type: astx.FunctionPrototype
      definition:
        type: astx.FunctionDef | None
      validate_ffi:
        type: bool
      validate_main:
        type: bool
    returns:
      type: FunctionSignature
    """
    seen_parameter_names: set[str] = set()
    seen_default_parameter = False
    for argument in prototype.args.nodes:
        if argument.name in seen_parameter_names:
            self.context.diagnostics.add(
                f"Function '{prototype.name}' repeats parameter "
                f"'{argument.name}'",
                node=argument,
                code=DiagnosticCodes.SEMANTIC_DUPLICATE_DECLARATION,
            )
            continue
        seen_parameter_names.add(argument.name)
        if self._argument_has_default(argument):
            seen_default_parameter = True
            continue
        if not seen_default_parameter:
            continue
        self.context.diagnostics.add(
            f"Function '{prototype.name}' parameter '{argument.name}' "
            "without a default cannot follow a parameter with a "
            "default value",
            node=argument,
            code=DiagnosticCodes.SEMANTIC_CALL_ARITY,
        )

    is_extern = self._prototype_is_extern(prototype)
    is_variadic = self._prototype_is_variadic(prototype)
    symbol_name = self._prototype_symbol_name(prototype)
    required_runtime_features = normalize_runtime_features(
        prototype,
        diagnostics=self.context.diagnostics,
    )
    calling_convention = self._prototype_calling_convention(
        prototype,
        is_extern=is_extern,
    )

    if definition is not None and is_extern:
        self.context.diagnostics.add(
            f"Extern function '{prototype.name}' cannot define a body",
            node=definition,
            code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
        )
    if is_variadic and not is_extern:
        self.context.diagnostics.add(
            f"Function '{prototype.name}' may be variadic only when "
            "declared extern",
            node=prototype,
            code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
        )
    if is_extern and calling_convention is not CallingConvention.C:
        self.context.diagnostics.add(
            f"Extern function '{prototype.name}' must use calling "
            "convention 'c'",
            node=prototype,
            code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
        )
    if (
        not is_extern
        and calling_convention is not CallingConvention.IRX_DEFAULT
    ):
        self.context.diagnostics.add(
            f"IRx-defined function '{prototype.name}' must use calling "
            "convention 'irx_default'",
            node=prototype,
            code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
        )
    if not is_extern and symbol_name != prototype.name:
        self.context.diagnostics.add(
            f"Function '{prototype.name}' may override symbol_name only "
            "for extern declarations",
            node=prototype,
            code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
        )
    if not is_extern and required_runtime_features:
        self.context.diagnostics.add(
            f"Function '{prototype.name}' may declare runtime features "
            "only when declared extern",
            node=prototype,
            code=DiagnosticCodes.RUNTIME_FEATURE_UNKNOWN,
        )

    signature = self.factory.make_function_signature(
        prototype,
        calling_convention=calling_convention,
        is_variadic=is_variadic,
        is_extern=is_extern,
        symbol_name=symbol_name,
        required_runtime_features=required_runtime_features,
    )

    if validate_ffi and signature.is_extern:
        ffi = build_ffi_callable_info(
            self.context,
            signature=signature,
            prototype=prototype,
        )
        if ffi is not None:
            signature = replace(signature, ffi=ffi)

    if validate_main and signature.name == MAIN_FUNCTION_NAME:
        if signature.is_extern:
            self.context.diagnostics.add(
                "Function 'main' cannot be extern",
                node=prototype,
                code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
            )
        if signature.is_variadic:
            self.context.diagnostics.add(
                "Function 'main' must not be variadic",
                node=prototype,
                code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
            )
        if len(signature.parameters) != 0:
            self.context.diagnostics.add(
                "Function 'main' must not declare parameters",
                node=prototype,
                code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
            )
        if (
            signature.calling_convention
            is not CallingConvention.IRX_DEFAULT
        ):
            self.context.diagnostics.add(
                "Function 'main' must use calling convention "
                "'irx_default'",
                node=prototype,
                code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
            )
        if not same_type(signature.return_type, astx.Int32()):
            self.context.diagnostics.add(
                "Function 'main' must return Int32",
                node=prototype,
                code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
            )

    return signature

register_class

register_class(node: ClassDefStmt) -> SemanticClass

Source code in packages/irx/src/irx/analysis/registry.py

def register_class(
    self,
    node: astx.ClassDefStmt,
) -> SemanticClass:
    """
    title: Register one top-level class.
    parameters:
      node:
        type: astx.ClassDefStmt
    returns:
      type: SemanticClass
    """
    module_key = self._current_module_key()
    existing = self.context.get_class(module_key, node.name)
    if existing is not None:
        if existing.declaration is not node:
            self.context.diagnostics.add(
                f"Class '{node.name}' already defined.",
                node=node,
                code=DiagnosticCodes.SEMANTIC_DUPLICATE_DECLARATION,
                related=(
                    DiagnosticRelatedInformation(
                        "previous class definition is here",
                        node=existing.declaration,
                        module_key=existing.module_key,
                    ),
                ),
            )
        return existing

    class_ = self.factory.make_class(module_key, node)
    self.context.register_class(class_)
    return class_

register_function

register_function(
    prototype: FunctionPrototype,
    *,
    definition: FunctionDef | None = None,
    validate_ffi: bool = True,
) -> SemanticFunction

Source code in packages/irx/src/irx/analysis/registry.py

def register_function(
    self,
    prototype: astx.FunctionPrototype,
    *,
    definition: astx.FunctionDef | None = None,
    validate_ffi: bool = True,
) -> SemanticFunction:
    """
    title: Register one top-level function.
    parameters:
      prototype:
        type: astx.FunctionPrototype
      definition:
        type: astx.FunctionDef | None
      validate_ffi:
        type: bool
    returns:
      type: SemanticFunction
    """
    signature = self.normalize_function_signature(
        prototype,
        definition=definition,
        validate_ffi=validate_ffi,
    )
    module_key = self._current_module_key()
    existing = self.context.get_function(module_key, prototype.name)
    if existing is not None:
        if not self.signatures_match(existing.signature, signature):
            mismatch = self._signature_mismatch_detail(
                existing.signature,
                signature,
                abi_only=False,
            )
            self.context.diagnostics.add(
                f"Conflicting declaration for function "
                f"'{prototype.name}': {mismatch}",
                node=definition or prototype,
                code=DiagnosticCodes.SEMANTIC_DUPLICATE_DECLARATION,
                related=(
                    DiagnosticRelatedInformation(
                        "previous declaration is here",
                        node=existing.definition or existing.prototype,
                        module_key=existing.module_key,
                    ),
                ),
            )
            return existing
        if definition is not None and existing.definition is not None:
            self.context.diagnostics.add(
                f"Function '{prototype.name}' already defined",
                node=definition,
                code=DiagnosticCodes.SEMANTIC_DUPLICATE_DECLARATION,
                related=(
                    DiagnosticRelatedInformation(
                        "previous definition is here",
                        node=existing.definition,
                        module_key=existing.module_key,
                    ),
                ),
            )
        if definition is not None and existing.definition is None:
            updated = replace(existing, definition=definition)
            self.context.register_function(updated)
            return updated
        return existing

    if signature.is_extern:
        for candidate in self.context.functions.values():
            if candidate.module_key != module_key:
                continue
            candidate_signature = candidate.signature
            if not candidate_signature.is_extern:
                continue
            if candidate_signature.symbol_name != signature.symbol_name:
                continue
            if candidate_signature.name == prototype.name:
                continue
            if self.signatures_match(candidate_signature, signature):
                continue
            mismatch = self._signature_mismatch_detail(
                candidate_signature,
                signature,
                abi_only=True,
            )
            self.context.diagnostics.add(
                f"Extern symbol '{signature.symbol_name}' is declared "
                f"incompatibly by '{candidate.name}' and "
                f"'{prototype.name}': {mismatch}",
                node=definition or prototype,
                code=DiagnosticCodes.FFI_INVALID_SIGNATURE,
                related=(
                    DiagnosticRelatedInformation(
                        "previous extern declaration is here",
                        node=candidate.definition or candidate.prototype,
                        module_key=candidate.module_key,
                    ),
                ),
            )
            break

    function = self.factory.make_function(
        module_key,
        prototype,
        signature=signature,
        definition=definition,
    )
    self.context.register_function(function)
    return function

register_struct

register_struct(node: StructDefStmt) -> SemanticStruct

Source code in packages/irx/src/irx/analysis/registry.py

def register_struct(
    self,
    node: astx.StructDefStmt,
) -> SemanticStruct:
    """
    title: Register one top-level struct.
    parameters:
      node:
        type: astx.StructDefStmt
    returns:
      type: SemanticStruct
    """
    module_key = self._current_module_key()
    existing = self.context.get_struct(module_key, node.name)
    if existing is not None:
        if existing.declaration is not node:
            self.context.diagnostics.add(
                f"Struct '{node.name}' already defined.",
                node=node,
                code=DiagnosticCodes.SEMANTIC_DUPLICATE_DECLARATION,
                related=(
                    DiagnosticRelatedInformation(
                        "previous struct definition is here",
                        node=existing.declaration,
                        module_key=existing.module_key,
                    ),
                ),
            )
        return existing

    struct = self.factory.make_struct(module_key, node)
    self.context.register_struct(struct)
    return struct

resolve_class

resolve_class(
    name: str, *, module_key: ModuleKey | None = None
) -> SemanticClass | None

Source code in packages/irx/src/irx/analysis/registry.py

def resolve_class(
    self,
    name: str,
    *,
    module_key: ModuleKey | None = None,
) -> SemanticClass | None:
    """
    title: Resolve one registered class.
    parameters:
      name:
        type: str
      module_key:
        type: ModuleKey | None
    returns:
      type: SemanticClass | None
    """
    lookup_module_key = module_key or self._current_module_key()
    return self.context.get_class(lookup_module_key, name)

resolve_function

resolve_function(
    name: str, *, module_key: ModuleKey | None = None
) -> SemanticFunction | None

Source code in packages/irx/src/irx/analysis/registry.py

def resolve_function(
    self,
    name: str,
    *,
    module_key: ModuleKey | None = None,
) -> SemanticFunction | None:
    """
    title: Resolve one registered function.
    parameters:
      name:
        type: str
      module_key:
        type: ModuleKey | None
    returns:
      type: SemanticFunction | None
    """
    lookup_module_key = module_key or self._current_module_key()
    return self.context.get_function(lookup_module_key, name)

resolve_struct

resolve_struct(
    name: str, *, module_key: ModuleKey | None = None
) -> SemanticStruct | None

Source code in packages/irx/src/irx/analysis/registry.py

def resolve_struct(
    self,
    name: str,
    *,
    module_key: ModuleKey | None = None,
) -> SemanticStruct | None:
    """
    title: Resolve one registered struct.
    parameters:
      name:
        type: str
      module_key:
        type: ModuleKey | None
    returns:
      type: SemanticStruct | None
    """
    lookup_module_key = module_key or self._current_module_key()
    return self.context.get_struct(lookup_module_key, name)

signatures_match

signatures_match(
    lhs: FunctionSignature, rhs: FunctionSignature
) -> bool

Source code in packages/irx/src/irx/analysis/registry.py

def signatures_match(
    self,
    lhs: FunctionSignature,
    rhs: FunctionSignature,
) -> bool:
    """
    title: Return whether two canonical function signatures match.
    parameters:
      lhs:
        type: FunctionSignature
      rhs:
        type: FunctionSignature
    returns:
      type: bool
    """
    if lhs.name != rhs.name:
        return False
    if lhs.calling_convention is not rhs.calling_convention:
        return False
    if lhs.is_variadic != rhs.is_variadic:
        return False
    if lhs.is_extern != rhs.is_extern:
        return False
    if lhs.symbol_name != rhs.symbol_name:
        return False
    if lhs.required_runtime_features != rhs.required_runtime_features:
        return False
    if not same_type(lhs.return_type, rhs.return_type):
        return False
    if len(lhs.parameters) != len(rhs.parameters):
        return False
    return all(
        self._same_parameter_spec(lhs_param, rhs_param)
        for lhs_param, rhs_param in zip(lhs.parameters, rhs.parameters)
    )