Cthulhu.jl

While Cthulhu places type annotations directly on source code, this can sometimes obscure details. For deeper insight, you can examine Julia's internal type-inferred representations.

Key concepts for interpreting inferred code:

• invoke statements: Represent calls that can be statically dispatched (inferred).
• call statements: Represent dynamic dispatch (not fully inferred).
• Transformations: Depending on optimization levels, the representation may include inlining and other compiler transformations.

When printing with printstyled in a REPL, the package uses colors to highlight potential type instability:

• Red: Indicates non-concrete types (e.g., Any, Real).
• Yellow: Indicates a "small union" of concrete types. These are generally safe unless the number of combinations becomes too large.

To install Cthulhu.jl, use the Julia package manager. It is recommended to let the package manager select a version compatible with your Julia installation.

Note for nightly users: If you are using a Julia nightly build, regularly run pkg> update Cthulhu to ensure compatibility with recent internal compiler changes.

using Pkg
Pkg.add("Cthulhu")
# Or in the REPL:
# pkg> add Cthulhu

You can customize the default configuration of toggles in the @descend menu using Cthulhu.CONFIG. To make these changes persistent across Julia sessions, use Cthulhu.save_config!(), which utilizes Preferences.jl.

# Change a default setting
Cthulhu.CONFIG.enable_highlighter = true

# Persistently save the current configuration
Cthulhu.save_config!(Cthulhu.CONFIG)

# Overwrite existing preferences forcefully
Cthulhu.save_config!(Cthulhu.CONFIG; force = true)

Users should be aware of two primary limitations:

1. Anonymous and Internal Functions: Types inside anonymous functions (e.g., x -> first(x)) are hidden from the annotator because Julia handles them as separate type-inferred methods. Consequently, variables inside these functions may not be annotated correctly in the parent function's tree.
2. Mapping Failures: Due to the way Julia lowers code, some statements in the type-inferred representation may not map directly back to a specific source line (resulting in empty mappings). However, named variables usually provide enough information for successful annotation.

You can use printstyled to display the code in a format similar to the original source, but with type annotations included.

By default, hide_type_stable=true suppresses concrete types to help you focus on type instability. To see all inferred types, set hide_type_stable=false.

To suppress colorized output in the REPL, use the iswarn=false keyword argument.

# Show all types (including concrete ones)
printstyled(stdout, node; hide_type_stable=false)

# Default behavior (hides stable concrete types to highlight instability)
printstyled(stdout, node)

To map types to source code, use the TypedSyntaxNode constructor. You must provide the function to be analyzed and a tuple representing the types of its arguments. This creates a syntax tree where each node is annotated with its inferred type.

using TypedSyntax

f(x, y, z) = x + y * z;

# Create a node for function f with argument types (Float64, Int, Float32)
node = TypedSyntaxNode(f, (Float64, Int, Float32))

Because TypedSyntax works by attempting to "reconstruct history" from type-inferred code back to source, some mappings may be empty if the lowering process changes the implementation significantly.

You can inspect these mappings using TypedSyntax.tsn_and_mappings(function, argument_types). This returns a tuple containing the TypedSyntaxNode and a collection of mappings. The mappings show how statements in the type-inferred code relate to the original source code.

function summer(list)
   s = 0
   for x in list
       s += x
   end
   return s
end;

# Get the node and the source mappings
tsn, mappings = TypedSyntax.tsn_and_mappings(summer, (Vector{Float64},));

# View mappings: left column is inferred code, right column is source mapping
hcat(1:length(mappings), tsn.typedsource.code, mappings)