lowering: Fix captured vars shadowed by an inner global declaration

[mlechu]

Bug

As discovered in #57547, lowering isn't resolving references to captured
variables when a global of the same name is declared in any scope in the
current function:

julia> let
            g = 1
            function f()
                let; global g = 2; end;
                return g    # g is not resolved
            end; f()
        end
ERROR: Found raw symbol in code returned from lowering. Expected all symbols to
have been resolved to GlobalRef or slots.

resolve-scopes correctly detects that we're returning the local, but
scope-blocks are removed in this pass. As a result, analyze-vars-lambda finds
more globals than resolve-scopes did when calling find-global-decls (which
does not peek inside nested scopes) on f. analyze-vars-lambda then
calculates the set of captured variables in f to be:

captvars = (current_env ∩ free_vars) - (new_staticparams ∪ wrong_globals)

so g in this case is never captured.

As one might expect from the diff, static parameters were affected too:

julia> let
           function f(x::T) where T
               function g(x)
                   let; global T = 1; end
                   x::T
               end
           end
       end
ERROR: Found raw symbol in code returned from lowering. Expected all symbols to
have been resolved to GlobalRef or slots.

This bug was introduced (revealed, maybe) in #57051---the whole resolution step
used to happen after lowering, so lowering passes disagreeing on scopes would be
less visible.

Fix

Omit globals from the free variable list in analyze-vars-lambda in the first
place. This way we don't need to call the scope-block-dependant
find-global-decls.

After:

julia> let
            g = 1
            function f()
                let; global g = 2; end;
                return g
            end; f()
        end
1

julia> let
           function f(x::T) where T
               function g(x)
                   let; global T = 1; end
                   x::T
               end
           end
       end
(::var"#f#f##1") (generic function with 1 method)

Also in this PR:

• To handle our new ability to shadow a captured variable with a global, prevent
  tampering with globals in cl-convert-
• Update the manual slightly

[topolarity]

Can you spell out the ambiguity? What might it do / not do?

[mlechu]

This test (and comment) was added a while ago in #35536, which special-cases globals shadowing locals if we're not in a lambda(?). If we know global declarations belong to scope-blocks instead of lambdas, maybe this special case can be removed? @JeffBezanson

[topolarity]

Thank you for this!

[topolarity]

It looks like this is a breaking change to our global behavior up until now, is that right?

On Julia 1.6-1.11:

julia> let
           g3 = 1
           function f()
               let; global g3 = 2; end;
               return g3
           end
           (f(), g3)
       end
(2, 1)

[mlechu]

Looks like it; I should have checked.

The new behaviour is more consistent with the documentation on global and Jeff's comments, but if it's too breaking I'll see what I can do. Other options are scoping global declarations to lambdas (discussed, would break the case where g3 = 1 is moved into f) or trying to reimplement the "my scope > inner scopes with globals > outer scopes" resolution.

[Keno]

I agree it's breaking, but it was also a bug. There were a few other places in lowering where we accidentally got the scope wrong. That's why I made that an error. My preference would be to try it with the bug fixed. I think the problem with changing the scope semantics to try to match what we did before is that the behavior before was not particularly well defined, so we risk breaking changes in the opposite direction if the try to choose a principled semantics that matches the old behavior.