document missing import restrictions

[tshepang]

No description provided.

[PLeVasseur]

These comments are blocking because the PR currently adds only part of the upstream keyword-import model. In particular, the existing self and super legality rules still conflict with the new restriction paragraphs, so the FLS would remain internally inconsistent after merge. The remaining comments cover precision of the extern-prelude wording, preservation of the $crate distinction, and changelog classification.

View changes since this review

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[PLeVasseur]

I rechecked this against rust-lang/rust#146972, rust-lang/reference#2136, the current Reference text, and the FLS path/import model. The PR is pointed at the right upstream change. I think there are a few alignment points left where the new restriction paragraphs and the older path/import rules would otherwise disagree.

The main thing I am trying to preserve is that the new restriction paragraphs line up with the surrounding path/import rules. The current Reference text and the post-rust-lang/rust#146972 resolver model also rely on the surrounding self, super, $crate, and :: path rules lining up with the import restrictions. The FLS currently still has older rules that conflict with the new paragraphs, especially around use self as name;, use self::{self};, braced parent-entity imports such as use a::b::{self as name}; and use a::{b::self as name};, and use self::super as name;.

The remaining alignment points I see are:

1. Use the meeting outcome/Hristian follow-up wording: the :t:entity imported by the related :t:simple import is subject to the :t:renaming, not the textual path segment.
2. Update the existing self import rules so renamed current-module imports are accepted and unrenamed current-module imports remain rejected.
3. Update fls_opn5n5t2mo3m for Rust 2021 use paths so self is still restricted in ordinary paths, while braced/nesting-import parent-entity imports such as use a::b::{self};, use a::b::{self as name};, use a::{b::self};, and use a::{b::self as name}; remain valid. Direct final-self paths such as use a::b::self as name; are still rejected by Rust 1.95.0 with E0429; rust-lang/rust#146972 leaves general support for self at the end of paths as future work.
4. Update fls_7k88ypcgaoff so super is permitted to follow an initial self, while still rejecting non-leading super in paths such as foo::super or crate::super.
5. Preserve the existing FLS distinction between crate and $crate; $crate resolves to the crate that declares the macro being expanded, not simply to the current crate in the same way as crate.
6. Keep the Rust 2021 :: rule narrow: use ::std::io; remains valid, while importing the extern-prelude root itself is not valid. The constructed import-prefix model should preserve leading :: rather than treating a bare :: prefix as an empty local prefix.
7. Avoid saying that a :t:simple import brings a path into scope. Paths are syntax; imports bring entities/names into scope. Also update the simple-import semantics for final-self nesting imports, make empty non-global import prefixes resolve to the current module, preserve global :: import prefixes, and update the existing underscore-renaming rule so it is not trait-specific.
8. The enum-variant-through-type-alias changelog classification is addressed by moving fls_LV94x3HlpBWk to FLS corrections; the final changelog needs to account for the paragraph and glossary changes after this source-shape pass.

The changelog should account for IDs relative to the merge base rather than earlier PR revisions. With the source shape from the thread comments, fls_sUhnfV62HJrb, fls_QGdeRTe0H1Uc, fls_aam34hsRmKU2, fls_P6dFw89ZDKv2, and fls_61qKMG5tuv12 are new paragraphs; fls_opn5n5t2mo3m, fls_WAA4WmohGu6T, fls_2bkcn83smy2y, fls_iuzvtr3oax1o, fls_90hQvSh7Bfyg, fls_wRmvtgQkFA6w, fls_kz2Gij5wHXnl, fls_ar03D5rxjzy0, fls_iQOgxNihUEr7, fls_RUiFQ17bmRLt, and fls_7k88ypcgaoff are changed; fls_cw006jhlboa, fls_yY58pFpkig9o, fls_Pxc0Ts8Y7pfW, and fls_hv3xT2CjZuxc are removed; and the :t:simple import glossary entry is updated.

I trial-applied this source shape together, expanded the Rust 1.95.0 edition-2021 test matrix for braced final-self imports, and ./make.py --clear builds. The snippets should be copy-paste-ready as a combined patch.

I left the detailed suggestions in individual threads/comments; they are intended to be applied as one source shape.

View changes since this review

[PLeVasseur]

Thanks, this has handled most of my earlier review. I think the remaining issues are narrower now, so I tried to leave some focused comments.

View changes since this review

[PLeVasseur]

Thinking over what we talked about last week, I could see the rationale of approving and merging this, and opening up a follow-up issue.

So -- I'm approving with the intention that is what we do.

View changes since this review

[PLeVasseur]

I think we can separate this from the remaining PR 694 work.

There is a real FLS issue here: the import-prefix model mostly describes prefixes in terms of path segments, but a leading :: is not a path segment. That means the current text does not clearly preserve the difference between an empty local prefix, as in use {self as this_module};, and a global/external-prelude prefix, as in use ::{self as root}; or use ::std::{self as std_alias};. This matters because dropping :: can change resolution from extern-prelude lookup to local lookup, and it also makes rules like "the import path prefix consists only of ::" hard to apply rigorously.

After digging through the history, though, this looks like an existing FLS modeling problem rather than something introduced by this PR. The same issue is already present in the pre-PR SimplePathPrefix ::= SimplePath? "::" grammar and the existing fls_WAA4WmohGu6T construction rule, which builds prefixes from path segments. PR 694 mostly exposes the problem because it adds rules that refer directly to a bare :: import prefix.

So I do not think we need to make this PR solve the whole import-prefix model.

Based on our discussion in last week's t-fls meeting we could do the following:

1. Keep this PR focused on the Rust 1.95 keyword-import restrictions.
2. Open a follow-up issue for the inherited import-prefix/leading-:: modeling problem.
3. Merge this PR

What do y'all think? @tshepang @kirtchev-adacore

[kirtchev-adacore]

I like the approach.

[PLeVasseur]

Filed #711 to track the inherited leading-:: import-prefix modeling issue. That leaves #694 scoped to the Rust 1.95 keyword-import restrictions as agreed.