GitCorner

Code

ossartcraftcraftanything🌐
642d5a256791
//! Reading GraphQL documents and tRPC URLs from text. No parser and no I/O: the syntax-tree pass and
//! the token scan both hand their strings here, so they recognise the same things.
//!
//! All of this is inference from how code is written. A piece of text the program fills in at run
//! time is an unknown, never a guess: see [`HOLE`].

use crate::model::ApiOperation;

/// Stands for text only known at run time, where a document was built with `${…}`.
pub const HOLE: char = '\u{1}';

/// Most operations read from one document.
const MAX_DOC_OPERATIONS: usize = 64;
/// Longest document read, in bytes.
pub const MAX_DOCUMENT_BYTES: usize = 1024 * 1024;
const MAX_URL_BYTES: usize = 2048;

/// One operation found in a document. `name` is `None` for an anonymous operation and for one whose
/// name was only known at run time (`literal` false tells them apart).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DocOperation {
    pub kind: &'static str,
    pub name: Option<String>,
    pub literal: bool,
}

/// What a document held.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Document {
    pub operations: Vec<DocOperation>,
    /// Run-time text sits between definitions, so it may add operations nobody can see here.
    pub open_ended: bool,
}

/// Keywords that may open a top-level GraphQL executable or type-system definition.
const DOC_KEYWORDS: &[&str] =
    &["query", "mutation", "subscription", "fragment", "type", "schema", "extend", "input", "interface", "union", "enum", "scalar", "directive"];

fn is_name_start(c: char) -> bool {
    c.is_ascii_alphabetic() || c == '_'
}

fn is_name_char(c: char) -> bool {
    c.is_ascii_alphanumeric() || c == '_'
}

/// Skip GraphQL ignored tokens (`Whitespace`, `,`, BOM, `#` comments) and optionally [`HOLE`]s.
/// Returns `true` when at least one [`HOLE`] was skipped.
fn skip_trivia(chars: &mut std::iter::Peekable<std::str::CharIndices<'_>>, allow_hole: bool) -> bool {
    let mut saw_hole = false;
    while let Some(&(_, c)) = chars.peek() {
        if allow_hole && c == HOLE {
            saw_hole = true;
            chars.next();
        } else if c == '#' {
            for (_, d) in chars.by_ref() {
                if d == '\n' || d == '\r' {
                    break;
                }
            }
        } else if c.is_whitespace() || c == ',' || c == '\u{feff}' {
            chars.next();
        } else {
            break;
        }
    }
    saw_hole
}

/// Read a GraphQL `Name` token starting at the current cursor position.
fn read_name<'a>(chars: &mut std::iter::Peekable<std::str::CharIndices<'a>>, text: &'a str) -> Option<&'a str> {
    let &(start, first) = chars.peek()?;
    if !is_name_start(first) {
        return None;
    }
    let mut end = start;
    while let Some(&(i, c)) = chars.peek() {
        if !is_name_char(c) {
            break;
        }
        end = i + c.len_utf8();
        chars.next();
    }
    text.get(start..end)
}

/// Step over a balanced `(...)` argument list, skipping strings and comments inside.
fn skip_parens(chars: &mut std::iter::Peekable<std::str::CharIndices<'_>>, text: &str) -> Option<()> {
    chars.peek().filter(|&&(_, c)| c == '(')?;
    let mut depth = 0usize;
    while let Some(&(_, c)) = chars.peek() {
        match c {
            '(' => {
                depth = depth.checked_add(1)?;
                chars.next();
            }
            ')' => {
                depth = depth.checked_sub(1)?;
                chars.next();
                if depth == 0 {
                    return Some(());
                }
            }
            '"' => skip_string(chars, text)?,
            '#' => {
                for (_, d) in chars.by_ref() {
                    if d == '\n' || d == '\r' {
                        break;
                    }
                }
            }
            _ => {
                chars.next();
            }
        }
    }
    None
}

/// Step over zero or more `@directive(...)` annotations, returning how many were read.
fn skip_directives<'a>(chars: &mut std::iter::Peekable<std::str::CharIndices<'a>>, text: &'a str) -> Option<usize> {
    let mut count = 0usize;
    loop {
        let _ = skip_trivia(chars, false);
        let Some(&(_, '@')) = chars.peek() else { return Some(count) };
        chars.next();
        let _ = skip_trivia(chars, false);
        read_name(chars, text)?;
        let _ = skip_trivia(chars, false);
        if chars.peek().is_some_and(|&(_, c)| c == '(') {
            skip_parens(chars, text)?;
        }
        count += 1;
    }
}

/// Step over a `{ ... }` selection or field block; requires closing `}` and at least one named member/hole.
fn skip_braced_block<'a>(chars: &mut std::iter::Peekable<std::str::CharIndices<'a>>, text: &'a str) -> Option<()> {
    chars.peek().filter(|&&(_, c)| c == '{')?;
    let mut depth = 0usize;
    let mut selected = false;
    while let Some(&(_, c)) = chars.peek() {
        match c {
            '{' => depth = depth.checked_add(1)?,
            '}' => {
                depth = depth.checked_sub(1)?;
                if depth == 0 {
                    chars.next();
                    return selected.then_some(());
                }
            }
            '"' => {
                skip_string(chars, text)?;
                continue;
            }
            '#' => {
                for (_, d) in chars.by_ref() {
                    if d == '\n' || d == '\r' {
                        break;
                    }
                }
                continue;
            }
            c if is_name_start(c) || c == HOLE => selected = true,
            _ => {}
        }
        chars.next();
    }
    None
}

/// Step over a `scalar Name Directives?` tail after the `scalar` keyword.
fn skip_scalar_def<'a>(chars: &mut std::iter::Peekable<std::str::CharIndices<'a>>, text: &'a str) -> Option<()> {
    let _ = skip_trivia(chars, false);
    read_name(chars, text)?;
    skip_directives(chars, text).map(|_| ())
}

/// Step over a `union Name Directives? (= |? Type (| Type)*)?` tail after the `union` keyword.
fn skip_union_def<'a>(chars: &mut std::iter::Peekable<std::str::CharIndices<'a>>, text: &'a str) -> Option<()> {
    let _ = skip_trivia(chars, false);
    read_name(chars, text)?;
    skip_directives(chars, text)?;
    let _ = skip_trivia(chars, false);
    if chars.peek().is_some_and(|&(_, c)| c == '=') {
        chars.next();
        let _ = skip_trivia(chars, false);
        if chars.peek().is_some_and(|&(_, c)| c == '|') {
            chars.next();
            let _ = skip_trivia(chars, false);
        }
        read_name(chars, text)?;
        loop {
            let _ = skip_trivia(chars, false);
            if chars.peek().is_some_and(|&(_, c)| c == '|') {
                chars.next();
                let _ = skip_trivia(chars, false);
                read_name(chars, text)?;
            } else {
                break;
            }
        }
    }
    Some(())
}

/// Step over a `directive @Name (Args)? repeatable? on |? Loc (| Loc)*` tail after `directive`.
fn skip_directive_def<'a>(chars: &mut std::iter::Peekable<std::str::CharIndices<'a>>, text: &'a str) -> Option<()> {
    let _ = skip_trivia(chars, false);
    chars.peek().filter(|&&(_, c)| c == '@')?;
    chars.next();
    let _ = skip_trivia(chars, false);
    read_name(chars, text)?;
    let _ = skip_trivia(chars, false);
    if chars.peek().is_some_and(|&(_, c)| c == '(') {
        skip_parens(chars, text)?;
        let _ = skip_trivia(chars, false);
    }
    let mut word = read_name(chars, text)?;
    if word == "repeatable" {
        let _ = skip_trivia(chars, false);
        word = read_name(chars, text)?;
    }
    if word != "on" {
        return None;
    }
    let _ = skip_trivia(chars, false);
    if chars.peek().is_some_and(|&(_, c)| c == '|') {
        chars.next();
        let _ = skip_trivia(chars, false);
    }
    read_name(chars, text)?;
    loop {
        let _ = skip_trivia(chars, false);
        if chars.peek().is_some_and(|&(_, c)| c == '|') {
            chars.next();
            let _ = skip_trivia(chars, false);
            read_name(chars, text)?;
        } else {
            break;
        }
    }
    Some(())
}

/// Step over an `extend ...` type-system extension after the `extend` keyword.
fn skip_extend_def<'a>(chars: &mut std::iter::Peekable<std::str::CharIndices<'a>>, text: &'a str) -> Option<()> {
    let _ = skip_trivia(chars, false);
    match read_name(chars, text)? {
        "scalar" => skip_scalar_def(chars, text),
        "union" => skip_union_def(chars, text),
        "schema" => {
            let dirs = skip_directives(chars, text)?;
            let _ = skip_trivia(chars, false);
            if chars.peek().is_some_and(|&(_, c)| c == '{') { skip_braced_block(chars, text) } else { (dirs > 0).then_some(()) }
        }
        "type" | "interface" | "input" | "enum" => {
            let _ = skip_trivia(chars, false);
            read_name(chars, text)?;
            let _ = skip_trivia(chars, false);
            let mut has_clause = false;
            let mut lookahead = chars.clone();
            if read_name(&mut lookahead, text) == Some("implements") {
                *chars = lookahead;
                has_clause = true;
                let _ = skip_trivia(chars, false);
                if chars.peek().is_some_and(|&(_, c)| c == '&') {
                    chars.next();
                    let _ = skip_trivia(chars, false);
                }
                read_name(chars, text)?;
                loop {
                    let _ = skip_trivia(chars, false);
                    if chars.peek().is_some_and(|&(_, c)| c == '&') {
                        chars.next();
                        let _ = skip_trivia(chars, false);
                        read_name(chars, text)?;
                    } else {
                        break;
                    }
                }
            }
            let dirs = skip_directives(chars, text)?;
            let _ = skip_trivia(chars, false);
            if chars.peek().is_some_and(|&(_, c)| c == '{') { skip_braced_block(chars, text) } else { (has_clause || dirs > 0).then_some(()) }
        }
        _ => None,
    }
}

/// Read the definitions of a GraphQL document. `None` when the text isn't one: it must start with a
/// definition, and its brackets and strings must close. Fragments count as definitions but aren't
/// operations. `{ a }` is valid GraphQL, but also plenty of other things, so it counts only when
/// `allow_shorthand` says the context already proved this is a document.
pub fn read_document(text: &str, allow_shorthand: bool) -> Option<Document> {
    if text.len() > MAX_DOCUMENT_BYTES {
        return None;
    }
    let mut doc = Document::default();
    let mut chars = text.char_indices().peekable();
    let mut definitions = 0usize;
    loop {
        if skip_trivia(&mut chars, true) {
            doc.open_ended = true;
        }
        let Some(&(_, first)) = chars.peek() else { break };
        let had_description = if first == '"' {
            skip_string(&mut chars, text)?;
            let _ = skip_trivia(&mut chars, false);
            true
        } else {
            false
        };
        let &(_, first) = chars.peek()?;
        let (kind, is_operation) = if first == '{' {
            if !allow_shorthand || had_description {
                return None;
            }
            ("query", true)
        } else if is_name_start(first) {
            match read_name(&mut chars, text)? {
                "query" => ("query", true),
                "mutation" => ("mutation", true),
                "subscription" => ("subscription", true),
                "fragment" => ("fragment", false),
                "scalar" => {
                    skip_scalar_def(&mut chars, text)?;
                    definitions += 1;
                    continue;
                }
                "union" => {
                    skip_union_def(&mut chars, text)?;
                    definitions += 1;
                    continue;
                }
                "directive" => {
                    skip_directive_def(&mut chars, text)?;
                    definitions += 1;
                    continue;
                }
                "extend" if !had_description => {
                    skip_extend_def(&mut chars, text)?;
                    definitions += 1;
                    continue;
                }
                // Braced type-system definitions are GraphQL too, though they name no client operation.
                "type" | "schema" | "input" | "interface" | "enum" => ("other", false),
                _ => return None,
            }
        } else {
            return None;
        };

        // The header, up to the selection set.
        let mut name: Option<String> = None;
        let mut name_is_hole = false;
        let mut saw_anything = false;
        let mut parens = 0usize;
        while let Some(&(_, c)) = chars.peek() {
            // Ignored tokens may separate any header tokens, including the name.
            if c == '#' {
                for (_, d) in chars.by_ref() {
                    if d == '\n' || d == '\r' {
                        break;
                    }
                }
                continue;
            }
            if c.is_whitespace() || c == ',' || c == '\u{feff}' {
                chars.next();
                continue;
            }
            if c == '{' && parens == 0 {
                break;
            }
            match c {
                '(' => parens += 1,
                ')' => parens = parens.checked_sub(1)?,
                HOLE if !saw_anything => name_is_hole = true,
                '"' => {
                    skip_string(&mut chars, text)?;
                    saw_anything = true;
                    continue;
                }
                _ => {}
            }
            if !saw_anything && is_name_start(c) && is_operation {
                name = read_name(&mut chars, text).map(String::from);
                saw_anything = true;
                // A name running straight into run-time text isn't all of the name.
                if chars.peek().is_some_and(|&(_, d)| d == HOLE) {
                    name = None;
                    name_is_hole = true;
                }
                continue;
            }
            if !c.is_whitespace() {
                saw_anything = true;
            }
            chars.next();
        }
        skip_braced_block(&mut chars, text)?;
        definitions += 1;
        if is_operation && doc.operations.len() < MAX_DOC_OPERATIONS {
            doc.operations.push(DocOperation { kind, literal: !name_is_hole, name: if name_is_hole { None } else { name } });
        }
    }
    (definitions > 0 || (allow_shorthand && doc.open_ended)).then_some(doc)
}

/// Step over a `"…"` or `"""…"""` string, leaving the iterator after it. `None` if it never closes.
fn skip_string(chars: &mut std::iter::Peekable<std::str::CharIndices<'_>>, text: &str) -> Option<()> {
    let (start, _) = chars.next()?;
    if text.get(start..start + 3) == Some("\"\"\"") {
        chars.next();
        chars.next();
        let mut quotes = 0;
        while let Some((i, c)) = chars.next() {
            if c == '\\' && text.get(i..).is_some_and(|rest| rest.starts_with("\\\"\"\"")) {
                chars.nth(2);
                quotes = 0;
                continue;
            }
            quotes = if c == '"' { quotes + 1 } else { 0 };
            if quotes == 3 {
                return Some(());
            }
        }
        return None;
    }
    let mut escaped = false;
    for (_, c) in chars.by_ref() {
        match c {
            '\r' | '\n' => return None,
            _ if escaped => escaped = false,
            '\\' => escaped = true,
            '"' => return Some(()),
            _ => {}
        }
    }
    None
}

/// Where a document may start, after the whitespace, commas, byte-order mark and `#` comments
/// that may come first (the non-run-time part of the trivia [`read_document`] skips).
fn document_start(text: &str) -> &str {
    let mut rest = text;
    loop {
        let trimmed = rest.trim_start_matches(|c: char| c.is_whitespace() || c == ',' || c == '\u{feff}');
        let Some(after) = trimmed.strip_prefix('#') else { return trimmed };
        rest = after.find(['\n', '\r']).and_then(|i| after.get(i + 1..)).unwrap_or("");
    }
}

/// Could this text be a whole document? A quick test before the real read, on every string.
/// A document may begin with a comment or GraphQL description string.
pub fn may_be_document(text: &str) -> bool {
    if !text.contains('{') {
        return false;
    }
    let mut t = document_start(text);
    if t.starts_with('"') {
        let mut chars = t.char_indices().peekable();
        if skip_string(&mut chars, t).is_none() {
            return false;
        }
        let after = chars.peek().map_or(t.len(), |&(i, _)| i);
        t = document_start(t.get(after..).unwrap_or(""));
    }
    DOC_KEYWORDS.iter().any(|kw| t.strip_prefix(kw).is_some_and(|rest| !rest.chars().next().is_some_and(is_name_char)))
}

/// What a URL says about an API, as `(protocol, procedures)`: a GraphQL endpoint, or a tRPC one with
/// the procedures named in its path. `None` when it's neither. A procedure part with run-time text
/// in it comes back as `None`, because only part of its name is known; `holes` are the marks a
/// partly literal URL uses for that text (`{…}`).
pub fn url_api(url: &str) -> Option<UrlApi> {
    // A scheme comes before any `/`, `?` or `#`: in `/graphql?next=https://x.test` the `://`
    // is in the query. The host then ends at the first `/`, `?` or `#`, so a slash in the query
    // or fragment (`https://x.test?next=/graphql`) is not the path. Run-time text in holes
    // (`{document.querySelector(#api).value}`) ends nothing.
    let from_path = match scheme_end(url) {
        Some(i) => {
            let rest = url.get(i + 3..).unwrap_or("");
            match outside_holes(rest, b"/?#") {
                Some(j) if rest.as_bytes().get(j) == Some(&b'/') => rest.get(j + 1..).unwrap_or(""),
                _ => "",
            }
        }
        None if url.starts_with('/') => url,
        None => return None,
    };
    let path = from_path.get(..outside_holes(from_path, b"?#").unwrap_or(from_path.len())).unwrap_or(from_path);
    // A slash inside a hole (`{pick(/trpc/user.list)}`) is not a segment boundary.
    let mut segs: Vec<&str> = Vec::new();
    let mut rest = path;
    while let Some(i) = outside_holes(rest, b"/") {
        segs.extend(rest.get(..i).filter(|s| !s.is_empty()));
        rest = rest.get(i + 1..).unwrap_or("");
    }
    segs.extend(Some(rest).filter(|s| !s.is_empty()));
    if let Some(i) = segs.iter().position(|s| *s == "trpc") {
        let rest: Vec<&str> = segs.iter().skip(i + 1).copied().collect();
        return Some(match rest.as_slice() {
            [] => UrlApi::Trpc { procedures: Vec::new() },
            [one] => UrlApi::Trpc { procedures: one.split(',').take(MAX_DOC_OPERATIONS).map(|p| (is_procedure_path(p)).then(|| p.to_string())).collect() },
            // tRPC paths are dotted, so a further slash isn't one of its URLs as far as we can read.
            _ => UrlApi::Trpc { procedures: vec![None] },
        });
    }
    (segs.last().is_some_and(|s| *s == "graphql" || *s == "gql")).then_some(UrlApi::Graphql)
}

/// Where a URL's scheme separator `://` starts: the first one outside holes, and only before any
/// `/`, `?` or `#` outside holes. `None` for a relative URL.
fn scheme_end(url: &str) -> Option<usize> {
    let mut from = 0;
    loop {
        let i = from + outside_holes(url.get(from..)?, b":/?#")?;
        if url.as_bytes().get(i) != Some(&b':') {
            return None;
        }
        if url.get(i..).is_some_and(|r| r.starts_with("://")) {
            return Some(i);
        }
        from = i + 1;
    }
}

/// The first of `stops` in `s` that is not inside a `{…}` hole.
fn outside_holes(s: &str, stops: &[u8]) -> Option<usize> {
    let mut depth = 0usize;
    for (i, &b) in s.as_bytes().iter().enumerate() {
        match b {
            b'{' => depth += 1,
            b'}' => depth = depth.saturating_sub(1),
            _ if depth == 0 && stops.contains(&b) => return Some(i),
            _ => {}
        }
    }
    None
}

/// What [`url_api`] found.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum UrlApi {
    Graphql,
    /// Empty for the endpoint itself; `None` for a procedure whose name isn't fully known.
    Trpc {
        procedures: Vec<Option<String>>,
    },
}

/// `post.byId`: dotted names, nothing else.
pub fn is_procedure_path(p: &str) -> bool {
    !p.is_empty()
        && p.len() <= 200
        && p.split('.').all(|part| {
            part.chars().next().is_some_and(|c| c.is_ascii_alphabetic() || c == '_' || c == '$')
                && part.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '$' || c == '-')
        })
}

/// A row before it has a place in the source.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct Row {
    pub protocol: &'static str,
    pub kind: &'static str,
    pub name: Option<String>,
    pub url: Option<String>,
    pub literal: bool,
}

impl Row {
    /// Something of this protocol is here, but what it is depends on the run.
    pub fn unknown(protocol: &'static str) -> Row {
        Row { protocol, kind: "unknown", name: None, url: None, literal: false }
    }
}

/// The rows a document gives. Run-time text between definitions adds an unknown one, because it may
/// hold operations of its own.
pub(crate) fn document_rows(doc: &Document) -> Vec<Row> {
    let mut rows: Vec<Row> = doc
        .operations
        .iter()
        .map(|o| {
            if o.literal {
                Row { protocol: "graphql", kind: o.kind, name: o.name.clone(), url: None, literal: true }
            } else {
                Row { kind: o.kind, ..Row::unknown("graphql") }
            }
        })
        .collect();
    if doc.open_ended {
        rows.push(Row::unknown("graphql"));
    }
    rows
}

/// The rows a URL gives.
pub(crate) fn url_rows(url: &str) -> Vec<Row> {
    if url.len() > MAX_URL_BYTES || !(url.contains("graphql") || url.contains("gql") || url.contains("trpc")) {
        return Vec::new();
    }
    let literal = !url.contains('{');
    let at = || Some(url.to_string());
    match url_api(url) {
        Some(UrlApi::Graphql) => vec![Row { protocol: "graphql", kind: "endpoint", name: None, url: at(), literal }],
        Some(UrlApi::Trpc { procedures }) if procedures.is_empty() => vec![Row { protocol: "trpc", kind: "endpoint", name: None, url: at(), literal }],
        Some(UrlApi::Trpc { procedures }) => procedures
            .into_iter()
            .map(|p| match p {
                Some(n) => Row { protocol: "trpc", kind: "operation", name: Some(n), url: at(), literal },
                None => Row { url: at(), ..Row::unknown("trpc") },
            })
            .collect(),
        None => Vec::new(),
    }
}

/// The rows a whole string gives: it may be a document, or a URL.
pub(crate) fn text_rows(text: &str) -> Vec<Row> {
    if may_be_document(text)
        && let Some(doc) = read_document(text, false)
    {
        return document_rows(&doc);
    }
    url_rows(text)
}

/// The kind a client hook asks for: `useQuery` and its relatives, on a procedure's path.
pub fn client_hook(name: &str) -> Option<&'static str> {
    match name {
        "useQuery" | "useSuspenseQuery" | "useInfiniteQuery" | "useSuspenseInfiniteQuery" | "usePrefetchQuery" => Some("query"),
        "useMutation" => Some("mutation"),
        "useSubscription" => Some("subscription"),
        _ => None,
    }
}

/// Adds a row and says whether the list had room. A row is a repeat if it's the same thing at the same
/// place; a URL is the same thing wherever it's written.
pub(crate) fn push_operation(list: &mut Vec<ApiOperation>, op: ApiOperation, cap: usize) -> bool {
    if list
        .iter()
        .any(|o| o.protocol == op.protocol && o.kind == op.kind && o.name == op.name && o.url == op.url && (op.url.is_some() || o.offset == op.offset))
    {
        return true;
    }
    if list.len() >= cap {
        return false;
    }
    list.push(op);
    true
}

#[cfg(test)]
mod tests {
    use super::*;

    fn names(text: &str) -> Vec<(&'static str, Option<String>, bool)> {
        read_document(text, false).unwrap().operations.into_iter().map(|o| (o.kind, o.name, o.literal)).collect()
    }

    #[test]
    fn reads_named_operations_with_variables_directives_and_fragments() {
        assert_eq!(names("query GetUser($id: ID!) { user(id: $id) { name } }"), [("query", Some("GetUser".to_string()), true)]);
        assert_eq!(names("mutation M{a}"), [("mutation", Some("M".to_string()), true)]);
        assert_eq!(names("subscription S @live { a }"), [("subscription", Some("S".to_string()), true)]);
        assert_eq!(
            names("# leading\nfragment F on U { id }\nquery A { ...F }\nmutation B($x: String = \"}\") { b(x: $x) }"),
            [("query", Some("A".to_string()), true), ("mutation", Some("B".to_string()), true)]
        );
        assert_eq!(names("query { a }"), [("query", None, true)], "anonymous is known to be anonymous");
        assert_eq!(names("query($a: Int) { a }"), [("query", None, true)]);
    }

    #[test]
    fn text_that_only_looks_like_a_document_is_not_one() {
        for t in [
            "query the database for results",
            "mutation",
            "query {",
            "query { }",
            "query Foo",
            "{ a }",
            "queryFoo { a }",
            "mutations happen { often",
            "select * from t where {x}",
            "query Foo { a } trailing words",
            "query Foo(a: \"never closed) { a }",
            "}{",
            "",
            "query )( { a }",
        ] {
            assert!(read_document(t, false).is_none(), "{t}");
        }
        assert_eq!(read_document("{ a }", true).unwrap().operations.len(), 1, "a gql tag has already said it's a document");
    }

    #[test]
    fn run_time_text_makes_a_name_unknown_not_guessed() {
        let h = HOLE;
        assert_eq!(names(&format!("query {h} {{ a }}")), [("query", None, false)]);
        assert_eq!(names(&format!("query Get{h} {{ a }}")), [("query", None, false)], "only part of the name is known");
        let d = read_document(&format!("query A {{ ...F }} {h}"), false).unwrap();
        assert!(d.open_ended, "a fragment or another operation may be in there");
        assert_eq!(d.operations.len(), 1);
        assert!(!read_document("query A { a }", false).unwrap().open_ended);
        assert_eq!(names(&format!("query A {{ {h} }}")), [("query", Some("A".to_string()), true)], "run-time fields don't change the name");
        let only = read_document(&format!("{h}"), true).unwrap();
        assert!(only.operations.is_empty() && only.open_ended);
        assert!(read_document(&format!("{h}"), false).is_none());
    }

    #[test]
    fn a_document_may_begin_with_a_comment() {
        assert!(may_be_document("# note\nquery Q { a }"));
        assert!(may_be_document("  # one\n# two\nmutation M { a }"));
        assert!(may_be_document("# note\r\nquery Q { a }"));
        assert!(may_be_document("# note\rquery Q { a }"), "a lone CR ends a comment too");
        assert_eq!(read_document("# note\rquery Q { a }", false).and_then(|d| d.operations.first().and_then(|o| o.name.clone())).as_deref(), Some("Q"));
        assert!(may_be_document("\u{feff}# c\n, query Q { a }"));
        assert!(!may_be_document("# note\nconst a = { b: 1 }"));
        assert!(!may_be_document("# only a comment"));
        assert!(!may_be_document("# query Q { a }"), "no newline means the whole text is the comment");
        let doc = read_document("query Q { a # note\r b }", false).expect("a comment in a selection set ends at a lone CR");
        assert_eq!(doc.operations.first().and_then(|o| o.name.as_deref()), Some("Q"));
    }

    #[test]
    fn hostile_documents_are_bounded() {
        assert!(read_document(&"{".repeat(100_000), true).is_none());
        assert!(read_document(&"query ".repeat(100_000), false).is_none());
        assert!(read_document(&format!("query A {{ {} }}", "a ".repeat(MAX_DOCUMENT_BYTES)), false).is_none());
        let many: String = (0..1000).map(|i| format!("query Q{i} {{ a }}\n")).collect();
        assert_eq!(read_document(&many, false).unwrap().operations.len(), MAX_DOC_OPERATIONS);
        assert!(read_document("query A { \"é", false).is_none());
        assert!(read_document("é", false).is_none());
    }

    #[test]
    fn urls() {
        assert_eq!(url_api("/graphql"), Some(UrlApi::Graphql));
        assert_eq!(url_api("https://api.example.test/v1/graphql?x=1"), Some(UrlApi::Graphql));
        assert_eq!(url_api("/api/gql"), Some(UrlApi::Graphql));
        assert_eq!(url_api("/docs/graphql/intro"), None);
        assert_eq!(url_api("graphql"), None, "a word, not a URL");
        assert_eq!(url_api("/api/graphql-tools"), None);
        assert_eq!(url_api("/api/trpc"), Some(UrlApi::Trpc { procedures: vec![] }));
        assert_eq!(url_api("/api/trpc/post.byId?input=1"), Some(UrlApi::Trpc { procedures: vec![Some("post.byId".into())] }));
        assert_eq!(url_api("https://x.test/trpc/a.b,c.d?batch=1"), Some(UrlApi::Trpc { procedures: vec![Some("a.b".into()), Some("c.d".into())] }));
        assert_eq!(url_api("/trpc/{path}"), Some(UrlApi::Trpc { procedures: vec![None] }));
        assert_eq!(url_api("/trpc/post.{x}"), Some(UrlApi::Trpc { procedures: vec![None] }));
        assert_eq!(url_api("/api/users"), None);
        assert_eq!(url_api("https://trpc.io/docs"), None, "the host isn't the path");
    }
}