Redesign downstream integration with Cthulhu

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog for Cthulhu
+
+## `v3.0.0`
+
+### Improvements
+
+- The way that packages integrate with Cthulhu to customize the behavior of code introspection has been redesigned (see https://github.com/JuliaDebug/Cthulhu.jl/pull/662 for more details).
+- A new UI command mapped to `DEL` (backspace, `'\x7f'`) now allows to go back (ascend) with a single key press.
+
+### Breaking changes
+
+- The `AbstractCursor` interface was removed, deleting or changing the signature of most associated methods (`Cthulhu.AbstractCursor`, `Cthulhu.lookup`, `Cthulhu.lookup_constproped`, `Cthulhu.get_ci`, `Cthulhu.update_cursor`, `Cthulhu.navigate`)
+- The `Cthulhu.custom_toggles` interface was removed, along with `Cthulhu.CustomToggle`, replaced by `Cthulhu.menu_commands` and `Cthulhu.Command`, respectively.
+- `CthulhuConfig` is no longer mutable (but `CthulhuState`, the new state structure holding it, is mutable). `CONFIG` was therefore changed to a global typed but non-const variable, which may be reassigned by users (instead of mutating its fields) with `Cthulhu.CONFIG = my_new_config`. See [`set_config`] and [`set_config!`] to modify an existing configuration, and [`save_config!`] to persist a configuration with Preferences.jl.
+- The `annotate_source` configuration option was removed in favor of a `view::Symbol` configuration option, with the `:source|:ast|:typed|:llvm|:native` available views by default (more may be defined by providers).
+- The `exception_type` configuration option was renamed to `exception_types` for consistency with `remarks`.
+- The `with_effects` configuration option was renamed to `effects` for consistency with `remarks` and `exception_types`.
+- The `inline_cost` configuration option was renamed to `inlining_costs`, also for consistency reasons.
+- The `interruptexc` configuration option was removed. It used to control whether `q` exited (by throwing an `InterruptException`) or ascended, but now that backspace was added as a shortcut to ascend, we can now unconditionally exit with `q` (which actually matches its action description).
+

Project.toml

@@ -1,24 +1,10 @@
-authors = ["Valentin Churavy <[email protected]> and contributors"]
 name = "Cthulhu"
 uuid = "f68482b8-f384-11e8-15f7-abe071a5a75f"
-version = "2.17.10"
-
-[compat]
-CodeTracking = "0.5, 1, 2"
-Compiler = "0.1"
-FoldingTrees = "1"
-InteractiveUtils = "1.9"
-JuliaSyntax = "1"
-PrecompileTools = "1"
-Preferences = "1"
-REPL = "1.9"
-TypedSyntax = "1.3.0"
-UUIDs = "1.9"
-Unicode = "1.9"
-WidthLimitedIO = "1"
-julia = "1.12"
+version = "3.0.0"
+authors = ["Valentin Churavy <[email protected]> and contributors"]
 
 [deps]
+Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"
 CodeTracking = "da1fd8a2-8d9e-5ec2-8556-3022fb5608a2"
 FoldingTrees = "1eca21be-9b9b-4ed8-839a-6d8ae26b1781"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
@@ -37,14 +23,32 @@ Compiler = "807dbc54-b67e-4c79-8afb-eafe4df6f2e1"
 [extensions]
 CthulhuCompilerExt = "Compiler"
 
+[compat]
+Accessors = "0.1.42"
+CodeTracking = "0.5, 1, 2"
+Compiler = "0.1"
+FoldingTrees = "1"
+InteractiveUtils = "1.9"
+JuliaSyntax = "1"
+PrecompileTools = "1"
+Preferences = "1"
+REPL = "1.9"
+TypedSyntax = "1.3.0"
+UUIDs = "1.9"
+Unicode = "1.9"
+WidthLimitedIO = "1"
+julia = "1.12"
+
 [extras]
 CthulhuCompilerExt = "a0401a94-d28a-5d0d-bd4d-a83640b62d95"
 DeepDiffs = "ab62b9b5-e342-54a8-a765-a90f495de1a6"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 PerformanceTestTools = "dc46b164-d16f-48ec-a853-60448fc869fe"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test", "DeepDiffs", "PerformanceTestTools", "Random", "Revise", "StaticArrays"]
+test = ["Test", "Compiler", "DeepDiffs", "LinearAlgebra", "Logging", "PerformanceTestTools", "Random", "Revise", "StaticArrays"]

README.md

@@ -49,13 +49,18 @@ these interactive features; you can also see Cthulhu v2.8 in action in
 ## Usage: descend
 
 ```julia
-function foo()
+function foo(x)
     T = rand() > 0.5 ? Int64 : Float64
-    sum(rand(T, 100))
+    x + sum(rand(T, 100))
 end
 
-descend(foo, Tuple{})     # option 1: specify by function name and argument types
-@descend foo()            # option 2: apply `@descend` to a working execution of the function
+# option 1: use the function form to specify the signature
+descend(foo, (Int,))
+descend(foo, Tuple{Type{Int}})
+descend(Tuple{typeof(foo), Type{Int}})
+# option 2: use `@descend` with valid syntax to automatically extract the signature
+@descend foo(1)
+@descend foo(::Int) # 1.13+ only
 ```
 
 If you do this, you'll see quite a bit of text output. Let's break it down and
@@ -329,3 +334,8 @@ true
 
 julia> Cthulhu.save_config!(Cthulhu.CONFIG) # Will be automatically read next time you `using Cthulhu`
 ```
+
+## Development
+
+If you intend to Revise changes made to Cthulhu, it is strongly advised to disable the Compiler extension by uncommenting it from the `Project.toml` while iterating.
+Otherwise, the Compiler extension will be unconditionally loaded, and Revise seems to fail to revise the changes into `CthulhuCompilerExt`.

TypedSyntax/Project.toml

@@ -1,7 +1,7 @@
 name = "TypedSyntax"
 uuid = "d265eb64-f81a-44ad-a842-4247ee1503de"
 authors = ["Tim Holy <[email protected]> and contributors"]
-version = "1.5.2"
+version = "1.5.3"
 
 [deps]
 CodeTracking = "da1fd8a2-8d9e-5ec2-8556-3022fb5608a2"

TypedSyntax/src/node.jl

@@ -495,7 +495,7 @@ function map_ssas_to_source(src::CodeInfo, mi::MethodInstance, rootnode::SyntaxN
     used = BitSet()
     for (i, stmt) in enumerate(src.code)
         Core.Compiler.scan_ssa_use!(push!, used, stmt)
-        if isa(stmt, Core.ReturnNode)
+        if isa(stmt, Core.ReturnNode) && isdefined(stmt, :val)
             val = stmt.val
             if isa(val, SSAValue)
                 push!(used, val.id)
@@ -573,7 +573,7 @@ function map_ssas_to_source(src::CodeInfo, mi::MethodInstance, rootnode::SyntaxN
         empty!(argmapping)
         if is_slot(stmt) || isa(stmt, SSAValue) || isa(stmt, GlobalRef)
             append_targets_for_arg!(mapped, i, stmt)
-        elseif isa(stmt, Core.ReturnNode)
+        elseif isa(stmt, Core.ReturnNode) && isdefined(stmt, :val)
             append_targets_for_line!(mapped, i, append_targets_for_arg!(argmapping, i, stmt.val))
         elseif isa(stmt, Expr)
             targets = get_targets(stmt)

ext/CthulhuCompilerExt.jl

@@ -6,7 +6,7 @@ using Cthulhu: Cthulhu
 
 function __init__()
     Cthulhu.CTHULHU_MODULE[] = @__MODULE__
-    read_config!(CONFIG)
+    read_config!()
 end
 
 include("../src/CthulhuBase.jl")

src/Cthulhu.jl

@@ -1,14 +1,33 @@
 module Cthulhu
 
 export @descend, @descend_code_typed, @descend_code_warntype,
-    descend, descend_code_typed, descend_code_warntype, ascend
+    descend, descend_code_typed, descend_code_warntype, ascend,
+    AbstractProvider
 
 const CC = Base.Compiler
 const IRShow = Base.IRShow
 
 const CTHULHU_MODULE = Ref{Module}(@__MODULE__)
 
-__init__() = read_config!(CONFIG)
+function is_compiler_loaded()
+    pkgid = Base.PkgId(Base.UUID("807dbc54-b67e-4c79-8afb-eafe4df6f2e1"), "Compiler")
+    return haskey(Base.loaded_modules, pkgid)
+end
+is_compiler_extension_loaded() = CTHULHU_MODULE[] !== @__MODULE__
+
+function resolve_module(Compiler::Module)
+    Compiler === Base.Compiler && return @__MODULE__
+    Compiler === CTHULHU_MODULE[].Compiler && return CTHULHU_MODULE[]
+    return resolve_module()
+end
+resolve_module() = CTHULHU_MODULE[]
+function resolve_module(@nospecialize(::T)) where {T}
+    mod = parentmodule(T)
+    nameof(mod) === :Compiler && return resolve_module(mod)
+    return resolve_module()
+end
+
+__init__() = read_config!()
 
 include("CthulhuBase.jl")
 include("backedges.jl")
@@ -26,7 +45,16 @@ See [`Cthulhu.CONFIG`](@ref) for options and their defaults.
 julia> @descend sin(1)
 [...]
 
-julia> @descend iswarn=false foo()
+julia> @descend view=:typed iswarn=true optimize=false foo() # equivalent to `@descend_warntype`
+[...]
+
+julia> @descend view=:typed iswarn=false foo() # equivalent to `@descend_code_typed`
+[...]
+
+julia> @descend interp=SomeInterpreter() foo() # use a custom `Compiler.AbstractInterpreter`
+[...]
+
+julia> @descend provider=SomeProvider() foo() # use a custom `AbstractProvider`, see the docs for more details
 [...]
 ```
 """
@@ -41,6 +69,10 @@ Evaluates the arguments to the function or macro call, determines their
 types, and calls [`descend_code_typed`](@ref) on the resulting expression.
 See [`Cthulhu.CONFIG`](@ref) for options and their defaults.
 
+This macro is equivalent to `@descend` with the following options set (unless provided):
+- `view = :typed`
+- `iswarn = false`
+
 # Examples
 ```julia
 julia> @descend_code_typed sin(1)
@@ -61,6 +93,11 @@ Evaluates the arguments to the function or macro call, determines their
 types, and calls [`descend_code_warntype`](@ref) on the resulting expression.
 See [`Cthulhu.CONFIG`](@ref) for options and their defaults.
 
+This macro is equivalent to `@descend` with the following options set (unless provided):
+- `view = :typed`
+- `iswarn = true`
+- `optimize = false`
+
 # Examples
 ```julia
 julia> function foo()
@@ -83,12 +120,12 @@ end
 """
     descend(f, argtypes=Tuple{...}; kwargs...)
     descend(tt::Type{<:Tuple}; kwargs...)
-    descend(Cthulhu.BOOKMARKS[i])
+    descend(Cthulhu.BOOKMARKS[i]; kwargs...)
     descend(mi::MethodInstance; kwargs...)
 
 Given a function and a tuple-type, interactively explore the source code of functions
-annotated with inferred types by descending into `invoke` statements. Type enter to select an
-`invoke` to descend into, select `↩` to ascend, and press `q` or `control-c` to quit.
+annotated with inferred types by descending into `invoke` statements. Type enter to select a callsite
+to descend into, select `↩` or press backspace to ascend, and press `q` or `ctrl-c` to quit.
 See [`Cthulhu.CONFIG`](@ref) for `kwargs` and their defaults.
 
 # Usage:
@@ -109,8 +146,20 @@ julia> descend() do
 [...]
 ```
 """
-function descend(@nospecialize(args...); @nospecialize(kwargs...))
-    CTHULHU_MODULE[].descend_impl(args...; kwargs...)
+function descend(@nospecialize(args...); interp=nothing,
+                                         provider=nothing,
+                                         @nospecialize(kwargs...))
+    if provider !== nothing
+        mod = resolve_module(provider)
+        mod.descend_with_error_handling(args...; provider, kwargs...)
+    elseif interp !== nothing
+        mod = resolve_module(interp)
+        mod.descend_with_error_handling(args...; interp, kwargs...)
+    else
+        mod = resolve_module()
+        mod.descend_with_error_handling(args...; kwargs...)
+    end
+    return nothing
 end
 
 """
@@ -142,9 +191,8 @@ julia> descend_code_typed() do
 [...]
 ```
 """
-function descend_code_typed(@nospecialize(args...); kwargs...)
-    CTHULHU_MODULE[].descend_code_typed_impl(args...; kwargs...)
-end
+descend_code_typed(@nospecialize(args...); view = :typed, iswarn = false, kwargs...) =
+    descend(args...; view, iswarn, kwargs...)
 
 """
     descend_code_warntype(f, argtypes=Tuple{...}; kwargs...)
@@ -175,9 +223,8 @@ julia> descend_code_warntype() do
 [...]
 ```
 """
-function descend_code_warntype(@nospecialize(args...); kwargs...)
-    CTHULHU_MODULE[].descend_code_warntype_impl(args...; kwargs...)
-end
+descend_code_warntype(@nospecialize(args...); view = :typed, iswarn = true, optimize = false, kwargs...) =
+    descend(args...; view, iswarn, optimize, kwargs...)
 
 """
     ascend(mi::MethodInstance; kwargs...)
@@ -197,15 +244,19 @@ using PrecompileTools
 @setup_workload begin
     try
         @compile_workload begin
-            terminal = Testing.FakeTerminal()
+            terminal = Testing.VirtualTerminal()
+            harness = Testing.@run terminal @descend terminal=terminal gcd(1, 2)
             task = @async @descend terminal=terminal.tty gcd(1, 2)
-            write(terminal, 'q')
-            wait(task)
-            finalize(terminal)
+            @assert Testing.end_terminal_session(harness)
         end
     catch err
         @error "Errorred while running the precompile workload, the package may or may not work but latency will be long" exeption=(err,catch_backtrace())
     end
 end
 
+get_specialization(@nospecialize(f), @nospecialize(tt=default_tt(f))) =
+    get_specialization(Base.signature_type(f, tt))
+get_specialization(@nospecialize tt::Type{<:Tuple}) =
+    specialize_method(Base._which(tt))
+
 end # module Cthulhu