diagnostic: Add lowering/ambiguous-soft-scope detection

Add a new diagnostic that warns when a variable assignment inside
a `for`/`while`/`try` block at the top level shadows an existing
global variable, matching the warning Julia itself emits at
runtime as explained in the Julia's [soft scope manual](https://docs.julialang.org/en/v1/manual/variables-and-scoping/#on-soft-scope):
```
global i = 0
while i < 5
    i += 1     # Assignment to `i` in soft scope is ambiguous (JETLS lowering/ambiguous-soft-scope)
               # Variable `i` may be used before it is defined (JETLS lowering/undef-local-var)
    println(i)
end
```

- Add `analyze_ambiguous_soft_scope!` using JuliaLowering's
  `is_ambiguous_local` binding flag
- Add code actions: "Insert `global`" (preferred) and
  "Insert `local`" declarations with proper indentation
- Enable soft scope semantics for notebook cells via
  `is_notebook_cell_uri`, suppressing this diagnostic

Author: aviatesk

CHANGELOG.md

@@ -50,6 +50,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   Unreachable code is displayed as faded/grayed out with the `Unnecessary` tag.
   A "Delete unreachable code" quick fix code action is also available.
 
+- Added [`lowering/ambiguous-soft-scope`](https://aviatesk.github.io/JETLS.jl/release/diagnostic/#diagnostic/reference/lowering/ambiguous-soft-scope) diagnostic that warns when a variable assignment inside a `for`/`while`/`try` block at the top level shadows an existing global variable.
+  This matches the warning Julia itself emits at runtime for this pattern.
+  Two code actions are offered: "Insert `global` declaration" (preferred) and "Insert `local` declaration".
+  This diagnostic is suppressed for notebook cells, where soft scope semantics are enabled.
+
 ### Changed
 
 - [`lowering/undef-local-var`](https://aviatesk.github.io/JETLS.jl/release/diagnostic/#diagnostic/reference/lowering/undef-local-var) now recognizes correlated conditions to reduce false positives.

LSP/src/basic-json-structures.jl

@@ -504,22 +504,11 @@ Structure to capture a description for an error code.
 end
 
 # JETLS specific data structures for `data` field of `Diagnostic`
-struct UnusedArgumentData
-    is_kwarg::Bool
-end
-export UnusedArgumentData
-
-struct UnusedVariableData
-    is_tuple_unpacking::Bool
-    assignment_range::Union{Nothing,Range}
-    lhs_eq_range::Union{Nothing,Range}
-end
-export UnusedVariableData
-
-struct UnusedImportData
-    delete_range::Range
+struct AmbiguousSoftScopeData
+    name::String
+    indent::String
 end
-export UnusedImportData
+export AmbiguousSoftScopeData
 
 struct UnreachableCodeData
     delete_range::Range
@@ -531,6 +520,23 @@ struct UnsortedImportData
 end
 export UnsortedImportData
 
+struct UnusedArgumentData
+    is_kwarg::Bool
+end
+export UnusedArgumentData
+
+struct UnusedImportData
+    delete_range::Range
+end
+export UnusedImportData
+
+struct UnusedVariableData
+    is_tuple_unpacking::Bool
+    assignment_range::Union{Nothing,Range}
+    lhs_eq_range::Union{Nothing,Range}
+end
+export UnusedVariableData
+
 """
 Represents a diagnostic, such as a compiler error or warning.
 Diagnostic objects are only valid in the scope of a resource.
@@ -588,7 +594,7 @@ Diagnostic objects are only valid in the scope of a resource.
     # Tags
     - since – 3.16.0
     """
-    data::Union{UnusedArgumentData, UnusedVariableData, UnusedImportData, UnreachableCodeData, UnsortedImportData, Nothing} = nothing
+    data::Union{AmbiguousSoftScopeData, UnsortedImportData, UnreachableCodeData, UnusedArgumentData, UnusedImportData, UnusedVariableData, Nothing} = nothing
 end
 
 # Command

docs/src/diagnostic.md

@@ -115,6 +115,7 @@ Here is a summary table of the diagnostics explained in this section:
 | [`lowering/unused-import`](@ref diagnostic/reference/lowering/unused-import)                     | `Information`         | `JETLS/live`  | Imported names that are never used                 |
 | [`lowering/unreachable-code`](@ref diagnostic/reference/lowering/unreachable-code)               | `Information`         | `JETLS/live`  | Code after a block terminator that is never reached  |
 | [`lowering/unsorted-import-names`](@ref diagnostic/reference/lowering/unsorted-import-names)     | `Hint`                | `JETLS/live`  | Import/export names not sorted alphabetically      |
+| [`lowering/ambiguous-soft-scope`](@ref diagnostic/reference/lowering/ambiguous-soft-scope)       | `Warning`             | `JETLS/live`  | Assignment in soft scope shadows a global variable |
 | [`toplevel/error`](@ref diagnostic/reference/toplevel/error)                                     | `Error`               | `JETLS/save`  | Errors during code loading                         |
 | [`toplevel/method-overwrite`](@ref diagnostic/reference/toplevel/method-overwrite)               | `Warning`             | `JETLS/save`  | Method definitions that overwrite previous ones    |
 | [`toplevel/abstract-field`](@ref diagnostic/reference/toplevel/abstract-field)                   | `Information`         | `JETLS/save`  | Struct fields with abstract types                  |
@@ -602,6 +603,86 @@ export bar, @foo  # Names are not sorted alphabetically (JETLS lowering/unsorted
     [Julia's conventional maximum line length](https://docs.julialang.org/en/v1.14-dev/devdocs/contributing/formatting/#General-Formatting-Guidelines-for-Julia-code-contributions)),
     the code action wraps to multiple lines with 4-space continuation indent.
 
+#### [Ambiguous soft scope (`lowering/ambiguous-soft-scope`)](@id diagnostic/reference/lowering/ambiguous-soft-scope)
+
+**Default severity**: `Warning`
+
+Reported when a variable is assigned inside a `for`, `while`, or
+`try`/`catch` block at the top level of a file, and a global variable
+with the same name already exists[^on_soft_scope]. This assignment is
+ambiguous because it behaves differently depending on where the code
+runs:
+- In the REPL or notebooks: assigns to the existing global
+- In a file: creates a new local variable, leaving the global
+  unchanged
+
+[^on_soft_scope]: See
+    [On Soft Scope](https://docs.julialang.org/en/v1/manual/variables-and-scoping/#on-soft-scope)
+    in the Julia manual.
+
+Example ([A Common Confusion](https://docs.julialang.org/en/v1/manual/variables-and-scoping/#A-Common-Confusion-2479cb3548c466db) adapted from the Julia manual):
+
+```@eval
+using Markdown
+
+mktemp() do file, io
+    code = """
+    # Print the numbers 1 through 5
+    global i = 0
+    while i < 5
+        i += 1  # Assignment to `i` in soft scope is ambiguous (JETLS lowering/ambiguous-soft-scope)
+                # Variable `i` may be used before it is defined (JETLS lowering/undef-local-var)
+        println(i)
+    end
+    """
+    write(io, code)
+    close(io)
+    err = IOBuffer()
+    try
+        run(pipeline(`$(Base.julia_cmd()) --startup-file=no $file`; stderr=err))
+    catch
+    end
+    output = String(take!(err))
+    lines = split(output, '\n')
+    idx = findfirst(l -> startswith(l, "Stacktrace:"), lines)
+    if idx !== nothing
+        lines = lines[1:idx]
+    end
+    push!(lines, "...")
+    output = join(lines, '\n')
+    output = replace(output, file=>"ambiguous-scope.jl")
+
+    Markdown.parse("""
+    > `ambiguous-scope.jl`
+    ``````julia
+    $(code)
+    ``````
+
+    This diagnostic matches the warning that Julia itself emits at runtime.
+    Running the example above as a file produces:
+    > `julia ambiguous-scope.jl`
+    ``````
+    $(output)
+    ``````
+    """)
+end
+```
+
+!!! note "Why is `lowering/undef-local-var` also reported?"
+    Since `i += 1` desugars to `i = i + 1`, the new local `i` is read
+    before being assigned, which also triggers
+    [`lowering/undef-local-var`](@ref diagnostic/reference/lowering/undef-local-var)
+    and causes the `UndefVarError` shown above at runtime.
+
+!!! tip "Code actions available"
+    Two quick fixes are offered: "Insert `global i` declaration" (preferred)
+    to assign to the existing global, and "Insert `local i` declaration" to
+    explicitly mark the variable as local and suppress the warning.
+
+!!! note "Notebook mode"
+    This diagnostic is suppressed for [notebooks](@ref notebook), where soft
+    scope semantics are enabled (matching REPL behavior).
+
 ### [Top-level diagnostic (`toplevel/*`)](@id diagnostic/reference/toplevel)
 
 Top-level diagnostics are reported by JETLS's full analysis feature (source:

src/code-action.jl

@@ -41,6 +41,7 @@ function handle_CodeActionRequest(
     unused_import_code_actions!(code_actions, uri, diagnostics)
     unreachable_code_actions!(code_actions, uri, diagnostics)
     sort_imports_code_actions!(code_actions, uri, diagnostics)
+    ambiguous_soft_scope_code_actions!(code_actions, uri, diagnostics)
     return send(server,
         CodeActionResponse(;
             id = msg.id,
@@ -196,3 +197,36 @@ function sort_imports_code_actions!(
     end
     return code_actions
 end
+
+function ambiguous_soft_scope_code_actions!(
+        code_actions::Vector{Union{CodeAction,Command}}, uri::URI,
+        diagnostics::Vector{Diagnostic}
+    )
+    for diagnostic in diagnostics
+        diagnostic.code == LOWERING_AMBIGUOUS_SOFT_SCOPE_CODE || continue
+        data = diagnostic.data
+        data isa AmbiguousSoftScopeData || continue
+        insert_pos = Position(; line = diagnostic.range.start.line, character = 0)
+        insert_range = Range(; start = insert_pos, var"end" = insert_pos)
+        push!(code_actions, CodeAction(;
+            title = "Insert `global $(data.name)` declaration",
+            kind = CodeActionKind.QuickFix,
+            diagnostics = Diagnostic[diagnostic],
+            isPreferred = true,
+            edit = WorkspaceEdit(;
+                changes = Dict{URI,Vector{TextEdit}}(
+                    uri => TextEdit[TextEdit(;
+                        range = insert_range,
+                        newText = data.indent * "global $(data.name)\n")]))))
+        push!(code_actions, CodeAction(;
+            title = "Insert `local $(data.name)` declaration",
+            kind = CodeActionKind.QuickFix,
+            diagnostics = Diagnostic[diagnostic],
+            edit = WorkspaceEdit(;
+                changes = Dict{URI,Vector{TextEdit}}(
+                    uri => TextEdit[TextEdit(;
+                        range = insert_range,
+                        newText = data.indent * "local $(data.name)\n")]))))
+    end
+    return code_actions
+end

src/diagnostic.jl

@@ -960,6 +960,38 @@ function find_capture_sites(
     return @somereal relatedInformation Some(nothing)
 end
 
+function analyze_ambiguous_soft_scope!(
+        diagnostics::Vector{Diagnostic}, fi::FileInfo, ctx3::JL.VariableAnalysisContext,
+        reported::Set{LoweringDiagnosticKey}
+    )
+    for binfo in ctx3.bindings.info
+        binfo.is_ambiguous_local || continue
+        binfo.is_internal && continue
+        bn = binfo.name
+        startswith(bn, '#') && continue
+        provs = JS.flattened_provenance(JL.binding_ex(ctx3, binfo.id))
+        is_from_user_ast(provs) || continue
+        prov = last(provs)
+        range = jsobj_to_range(prov, fi)
+        key = LoweringDiagnosticKey(range, :ambiguous, bn)
+        key in reported ? continue : push!(reported, key)
+        indent = get_line_indent(fi, range.start.line)
+        push!(diagnostics, Diagnostic(;
+            range,
+            severity = DiagnosticSeverity.Warning,
+            message = "Assignment to `$bn` in soft scope is ambiguous " *
+                      "because a global variable by the same name exists: " *
+                      "`$bn` will be treated as a new local. " *
+                      "Disambiguate by using `local $bn` to suppress this " *
+                      "warning or `global $bn` to assign to the existing " *
+                      "global variable.",
+            source = DIAGNOSTIC_SOURCE_LIVE,
+            code = LOWERING_AMBIGUOUS_SOFT_SCOPE_CODE,
+            codeDescription = diagnostic_code_description(LOWERING_AMBIGUOUS_SOFT_SCOPE_CODE),
+            data = AmbiguousSoftScopeData(bn, indent)))
+    end
+end
+
 const SORT_IMPORTS_MAX_LINE_LENGTH = 92
 const SORT_IMPORTS_INDENT = "    "
 
@@ -1196,6 +1228,8 @@ function analyze_lowered_code!(
 
     has_implicit_args = ismacro[] || is_generated0(st0)
 
+    analyze_ambiguous_soft_scope!(diagnostics, fi, ctx3, reported)
+
     analyze_unused_bindings!(
         diagnostics, fi, st0, ctx3, binding_occurrences, has_implicit_args, reported,
         kwarg_type_names, kwarg_locations;
@@ -1218,7 +1252,9 @@ end
 
 function lowering_diagnostics!(
         diagnostics::Vector{Diagnostic}, uri::URI, fi::FileInfo, mod::Module, st0::JS.SyntaxTree;
-        skip_analysis_requiring_context::Bool = false, kwargs...
+        skip_analysis_requiring_context::Bool = false,
+        soft_scope::Bool = false,
+        kwargs...
     )
     @assert JS.kind(st0) ∉ JS.KSet"toplevel module"
 
@@ -1227,7 +1263,8 @@ function lowering_diagnostics!(
     (st0, _) = desugar_main_macrocall(st0)
     world = Base.get_world_counter()
     res = try
-        jl_lower_for_scope_resolution(mod, st0, world; recover_from_macro_errors=false, convert_closures=true)
+        jl_lower_for_scope_resolution(mod, st0, world;
+            recover_from_macro_errors=false, convert_closures=true, soft_scope)
     catch err
         if err isa JL.LoweringError
             if !err.internal
@@ -1488,12 +1525,14 @@ function toplevel_lowering_diagnostics(
     st0_top = build_syntax_tree(file_info)
     skip_analysis_requiring_context = !has_analyzed_context(server.state, uri; lookup_func)
     allow_unused_underscore = get_config(server, :diagnostic, :allow_unused_underscore)
+    soft_scope = is_notebook_cell_uri(server.state, uri)
     iterate_toplevel_tree(st0_top) do st0::JS.SyntaxTree
         is_cancelled(cancel_flag) && return traversal_terminator
         pos = offset_to_xy(file_info, JS.first_byte(st0))
         (; mod, analyzer, postprocessor) = get_context_info(server.state, uri, pos; lookup_func)
         lowering_diagnostics!(diagnostics, uri, file_info, mod, st0;
-            skip_analysis_requiring_context, allow_unused_underscore, analyzer, postprocessor)
+            skip_analysis_requiring_context, allow_unused_underscore, soft_scope,
+            analyzer, postprocessor)
     end
 
     if !skip_analysis_requiring_context

src/notebook.jl

@@ -227,6 +227,8 @@ end
 
 is_notebook_uri(state::ServerState, uri::URI) = haskey(load(state.notebook_cache), uri)
 
+is_notebook_cell_uri(state::ServerState, uri::URI) = haskey(load(state.cell_to_notebook), uri)
+
 function map_notebook_diagnostics!(uri2diagnostics::URI2Diagnostics, state::ServerState)
     notebook_uris_to_delete = URI[]
     for uri in keys(uri2diagnostics)

src/types.jl

@@ -394,6 +394,7 @@ const LOWERING_CAPTURED_BOXED_VARIABLE_CODE = "lowering/captured-boxed-variable"
 const LOWERING_UNSORTED_IMPORT_NAMES_CODE = "lowering/unsorted-import-names"
 const LOWERING_UNUSED_IMPORT_CODE = "lowering/unused-import"
 const LOWERING_UNREACHABLE_CODE = "lowering/unreachable-code"
+const LOWERING_AMBIGUOUS_SOFT_SCOPE_CODE = "lowering/ambiguous-soft-scope"
 const TOPLEVEL_ERROR_CODE = "toplevel/error"
 const TOPLEVEL_METHOD_OVERWRITE_CODE = "toplevel/method-overwrite"
 const TOPLEVEL_ABSTRACT_FIELD_CODE = "toplevel/abstract-field"
@@ -417,6 +418,7 @@ const ALL_DIAGNOSTIC_CODES = Set{String}(String[
     LOWERING_UNSORTED_IMPORT_NAMES_CODE,
     LOWERING_UNUSED_IMPORT_CODE,
     LOWERING_UNREACHABLE_CODE,
+    LOWERING_AMBIGUOUS_SOFT_SCOPE_CODE,
     TOPLEVEL_ERROR_CODE,
     TOPLEVEL_METHOD_OVERWRITE_CODE,
     TOPLEVEL_ABSTRACT_FIELD_CODE,

src/utils/binding.jl

@@ -29,12 +29,21 @@ function is_relevant(ctx3::JL.AbstractLoweringContext,
          || cursor > start)
 end
 
+function insert_softscope_marker(st1::JS.SyntaxTree)
+    g = JS.syntax_graph(st1)
+    marker = JS.newleaf(g, st1, JS.K"softscope")
+    children = JS.SyntaxList(g)
+    push!(children, marker, st1)
+    return JS.newnode(g, st1, JS.K"block", children)
+end
+
 """
     jl_lower_for_scope_resolution(
             mod::Module, st0::JS.SyntaxTree;
             trim_error_nodes::Bool = true,
             recover_from_macro_errors::Bool = true,
             convert_closures::Bool = false,
+            soft_scope::Bool = false,
         ) -> (; st0, st1, st2, st3, ctx3)
 
 Perform the first three passes of lowering.
@@ -43,6 +52,11 @@ Depending on keyword arguments, also attempt to handle junk input in the ways a
 - `recover_from_macro_errors`: If errors occur during macro expansion, trim macrocalls and retry.
   This may happen for several reasons; the analyzer may not have picked up the
   macro definition yet, or the user could be working on the macrocall.
+- `convert_closures`: Also run the closure conversion pass (pass 4),
+  returning `ctx4` and `st4` in addition to the scope resolution results.
+- `soft_scope`: Enable soft scope semantics (REPL/notebook behavior)
+  where assignments in `for`/`while`/`try` blocks at the top level assign to
+  existing globals instead of creating new locals.
 
 Throw if lowering fails otherwise.
 
@@ -53,6 +67,7 @@ function jl_lower_for_scope_resolution(
         trim_error_nodes::Bool = true,
         recover_from_macro_errors::Bool = true,
         convert_closures::Bool = false,
+        soft_scope::Bool = false,
     )
     if trim_error_nodes
         st0 = without_kinds(st0, JS.KSet"error")
@@ -67,14 +82,18 @@ function jl_lower_for_scope_resolution(
         st0 = remove_macrocalls(st0)
         JL.expand_forms_1(mod, st0, true, world)
     end
-    return _jl_lower_for_scope_resolution(ctx1, st0, st1; convert_closures)
+    return _jl_lower_for_scope_resolution(ctx1, st0, st1; convert_closures, soft_scope)
 end
 
 function _jl_lower_for_scope_resolution(
         ctx1::JL.MacroExpansionContext, st0::JS.SyntaxTree, st1::JS.SyntaxTree;
-        convert_closures::Bool = false
+        convert_closures::Bool = false,
+        soft_scope::Bool = false,
     )
     ctx2, st2 = JL.expand_forms_2(ctx1, st1)
+    if soft_scope
+        st2 = insert_softscope_marker(st2)
+    end
     ctx3, st3 = JL.resolve_scopes(ctx2, st2)
     convert_closures || return (; st0, st1, st2, st3, ctx3)
     ctx4, st4 = JL.convert_closures(ctx3, st3)