Fix incorrect shadow warning for variables in non-overlapping scopes

[heathdutton]

Fixes #16190

When a local variable is declared in a block that ends before another local variable with the same name is declared at function scope, the compiler incorrectly warns that the first variable shadows the second.

This PR skips shadow warnings for local variables where the outer declaration appears after the inner declaration in source order, since the outer variable was not visible when the inner one was declared.

[github-actions]

Thank you for your contribution to the Solidity compiler! A team member will follow up shortly.

If you haven't read our contributing guidelines and our review checklist before, please do it now, this makes the reviewing process and accepting your contribution smoother.

If you have any questions or need our help, feel free to post them in the PR or talk to us directly on the #solidity-dev channel on Matrix.

[cameel]

Thanks for the contribution! There are a few things we need here, most notably more complete test coverage of this and similar cases of declaration shadowing that may be affected (or work but could be broken by an incorrect fix).

[cameel]

I don't think it's a good idea for semantics to be dependent on exact locations in the source file. Locations are just debug information and might be unavailable or imprecise. It's easy to mess with them e.g. in the AST import mode. We must have some more direct way to determine the order of declarations without locations.

Though I see that this is not a new thing we already have code that does this, e.g. in NameAndTypeResolver::importInheritedScope() so perhaps we can accept this for the purposes of the fix.

[cameel]

This PR needs more tests, both for the cases that should now be fixed and the ones where we want to ensure we still have the warning:

• Shadowing function and function pointer parameters
• Shadowing loop variables
• Shadowing try/catch variables
• Shadowing variables with a tuple declaration
• Shadowing named mapping key/value
• Shadowing file-level constants
• Shadowing field types in a struct
• The reverse situation in each case

I posted some of those in #16190 (comment), #16190 (comment) and #16190 (comment).

But please also look at the existing test we have for shadowing and see if there might be some other gaps in our coverage.

[cameel]

For some of those cases it would also be good to have equivalent semantic tests.

For example in the constant case from #16190 (comment) we would be interested not only whether the analysis produces the warning but also that the code generator follows the same logic and uses the right constant in calculations inside and outside of the contract:

contract C {
    uint256 constant X = 0x1234;

    function getInnerX() internal returns (uint) { return X; }
    function f() public returns (uint, uint) { return (getInnerX(), getOuterX()); }
}

uint256 constant X = 0x5678;

function getOuterX() returns (uint) { return X; }

[cameel]

The PR needs a changelog entry.

[heathdutton]

Thanks @cameel I'll get to this shortly.

[heathdutton]

The core fix and original test update are passing CI. I've had difficulty getting additional tests to pass. The fix specifically targets local variables in non-overlapping scopes - it checks if a homonym (same-name declaration in outer scope) is a local variable declared after the current declaration, and skips the warning in that case.

Could you provide guidance on:

1. The exact test format expected for the additional cases?
2. Which specific scenarios you'd like covered?

Happy to iterate on this.