feat(parse): Strip frontmatter

compiler/rustc_parse/src/lexer/mod.rs

@@ -55,6 +55,12 @@ pub(crate) fn lex_token_trees<'psess, 'src>(
         start_pos = start_pos + BytePos::from_usize(shebang_len);
     }
 
+    // Skip frontmatter, if present.
+    if let Some(frontmatter_len) = rustc_lexer::strip_frontmatter(src) {
+        src = &src[frontmatter_len..];
+        start_pos = start_pos + BytePos::from_usize(frontmatter_len);
+    }
+
     let cursor = Cursor::new(src);
     let mut lexer = Lexer {
         psess,

src/doc/unstable-book/src/language-features/frontmatter.md

@@ -8,3 +8,33 @@ The tracking issue for this feature is: [#136889]
 
 The `frontmatter` feature adds support for a specialized and simplified attribute syntax
 intended for external tools to consume.
+
+For example, when used with Cargo:
+```rust
+#!/usr/bin/env -S cargo -Zscript
+
+---
+[dependencies]
+clap = "4"
+---
+
+use clap::Parser;
+
+#[derive(Parser)]
+struct Cli {
+}
+
+fn main () {
+    Cli::parse();
+}
+```
+
+A frontmatter may come after a shebang and must come before any other syntax except whitespace.
+The open delimiter is three or more dashes (`-`) at the start of a new line.
+The open delimiter may be followed by whitespace and / or an identifier to mark the interpretation of the frontmatter within an external tool.
+It is then concluded at a newline.
+The close delimiter is a series of dashes that matches the open delimiter, at the start of a line.
+The close delimiter may be followed by whitespace.
+Any other trailing content, including more dashes than the open delimiter, is an error.
+It is then concluded at a newline.
+All content between the open and close delimiter lines is ignored.

tests/ui/feature-gates/feature-gate-frontmatter.rs

@@ -1,6 +1,7 @@
 ---
-//~^ ERROR expected item, found `-`
 ---
 
+//@ check-pass
+
 pub fn main() {
 }

tests/ui/frontmatter/frontmatter-escaped.rs

@@ -1,11 +1,12 @@
 -----
-//~^ ERROR expected item, found `-`
 
 ---
 ---
 
 -----
 
+//@ check-pass
+
 #![feature(frontmatter)]
 
 fn main() {

tests/ui/frontmatter/frontmatter-ignored-space.rs

@@ -1,10 +1,10 @@
 
 
 ---  
-//~^ ERROR expected item, found `-`
 
 ---  
 
+//@ check-pass
 #![feature(frontmatter)]
 // ignore-tidy-end-whitespace
 // ignore-tidy-leading-newlines

tests/ui/frontmatter/frontmatter-invalid-multiple.rs

@@ -1,8 +1,8 @@
 ---cargo
-//~^ ERROR expected item, found `-`
 ---
 
 ---buck
+//~^ ERROR expected item, found `-`
 ---
 
 #![feature(frontmatter)]

tests/ui/frontmatter/frontmatter-invalid-multiple.stderr

@@ -1,7 +1,7 @@
 error: expected item, found `-`
-  --> $DIR/frontmatter-invalid-multiple.rs:1:1
+  --> $DIR/frontmatter-invalid-multiple.rs:4:1
    |
-LL | ---cargo
+LL | ---buck
    | ^ expected item
    |
    = note: for a full list of items that can appear in modules, see <https://doc.rust-lang.org/reference/items.html>

tests/ui/frontmatter/frontmatter-with-body.rs

@@ -1,8 +1,9 @@
 ---
-//~^ ERROR expected item, found `-`
 [dependencies]
 ---
 
+//@ check-pass
+
 #![feature(frontmatter)]
 
 fn main() {

tests/ui/frontmatter/frontmatter-with-infostring-spaces.rs

@@ -1,7 +1,8 @@
 --- cargo
-//~^ ERROR expected item, found `-`
 ---
 
+//@ check-pass
+
 #![feature(frontmatter)]
 
 fn main() {

tests/ui/frontmatter/frontmatter-with-infostring.rs

@@ -1,7 +1,8 @@
 ---cargo
-//~^ ERROR expected item, found `-`
 ---
 
+//@ check-pass
+
 #![feature(frontmatter)]
 
 fn main() {

tests/ui/frontmatter/frontmatter.rs

@@ -1,7 +1,8 @@
 ---
-//~^ ERROR expected item, found `-`
 ---
 
+//@ check-pass
+
 #![feature(frontmatter)]
 
 fn main() {