modules

Documentation

Overview

Package modules handles module export type computation.

This package computes the exported type of a Lua module by analyzing its return statements and the types of exported values.

Export Detection

Lua modules export values via return statements:

local M = {}
function M.foo() ... end
return M

The package traces the returned value to compute its type, including all fields and methods.

Type Enrichment

Exported types are enriched with:

• Function effect annotations (terminates, type guards)
• Refined field types from flow analysis
• Method signatures from implementation analysis

Integration

Module export types are stored in the type database for use by importers, enabling cross-module type checking.

Package modules provides module export and import functionality for the type checker.

When a Lua file is type-checked as a module, its exports (the return value) are captured and stored in a database. Other modules can then require() this module and receive accurate type information for its exports.

Manifest Structure

Each module produces an io.Manifest containing:

• Export type: The type of the module's return value
• Type definitions: Named types exported by the module
• Function summaries: Effect and constraint information for exported functions

Function Summaries

Function summaries enable cross-module flow analysis. They capture:

• Effect rows: Read/write/throw effects
• KeyOf constraints: Type narrowing conditions on return

These summaries allow the type checker to perform narrowing and escape analysis when calling functions from imported modules.

Index

• func CollectAliases(graph *cfg.Graph) map[cfg.SymbolID]string
• func Connect(database *db.DB, name string, exportType typ.Type, ...) *io.Manifest
• func CopyEffectsForExport(effectsBySym map[cfg.SymbolID]*constraint.FunctionEffect) map[cfg.SymbolID]*constraint.FunctionEffect
• func Disconnect(database *db.DB, name string)
• func ExportFunctionSummaries(manifest *io.Manifest, exportType typ.Type, graph *cfg.Graph, ...)
• func ExportType(result *api.FuncResult, ...) typ.Type
• func ExportTypes(result *api.FuncResult) map[string]typ.Type
• func MergeAliases(base, overlay map[cfg.SymbolID]string) map[cfg.SymbolID]string

Functions

func CollectAliases

func CollectAliases(graph *cfg.Graph) map[cfg.SymbolID]string

CollectAliases extracts module alias mappings from require() assignments in a graph.

This scans the graph for patterns like:

local json = require("json")

And builds a map from the symbol ID (for `json`) to the module path ("json"). This enables the type checker to resolve module types when the alias is used.

The function handles direct require() calls with a string literal argument, including multi-target assignments (e.g., local m = require("mod")). It does not require the assignment to be local, since module aliases can be introduced via re-assignments or outer scope bindings.

This is called once per graph; nested functions merge their local aliases with the session-level alias map.

func Connect

func Connect(database *db.DB, name string, exportType typ.Type, exportTypes map[string]typ.Type, graph *cfg.Graph, effectsBySym map[cfg.SymbolID]*constraint.FunctionEffect) *io.Manifest

Connect creates a manifest from export data and connects it to the DB.

This is the main entry point for module export. It:

1. Creates a new manifest for the module
2. Sets the export type (module's return value type)
3. Defines any exported types
4. Extracts function summaries for cross-module analysis
5. Registers the manifest with the database

func CopyEffectsForExport

func CopyEffectsForExport(effectsBySym map[cfg.SymbolID]*constraint.FunctionEffect) map[cfg.SymbolID]*constraint.FunctionEffect

CopyEffectsForExport returns a defensive copy of effects for manifest export.

func Disconnect

func Disconnect(database *db.DB, name string)

Disconnect removes a module's manifest from the DB.

func ExportFunctionSummaries

func ExportFunctionSummaries(manifest *io.Manifest, exportType typ.Type, graph *cfg.Graph, effectsBySym map[cfg.SymbolID]*constraint.FunctionEffect)

ExportFunctionSummaries populates manifest with function summaries.

For each exported function with OnReturn constraints, this creates a summary containing parameter types, return types, and the ensures constraint. Effect rows are also included when available.

OnReturn constraints encode assert-style narrowing (e.g. assert.not_nil), enabling callers to narrow types based on imported module behavior.

func ExportType

func ExportType(result *api.FuncResult, effectsBySym map[cfg.SymbolID]*constraint.FunctionEffect) typ.Type

ExportType computes the module's exported type from return statements. Pass effectsBySym to enrich exported functions with effect summaries.

func ExportTypes

func ExportTypes(result *api.FuncResult) map[string]typ.Type

ExportTypes extracts module-local type definitions for manifest generation.

func MergeAliases

func MergeAliases(base, overlay map[cfg.SymbolID]string) map[cfg.SymbolID]string

MergeAliases returns a merged alias map with overlay taking precedence. Always returns a fresh map when any input is non-nil to avoid mutation side effects.