qleisli 0.2.9

Experimental quantum language with linear ownership, exact contracts and independent finite IR verification
Documentation
mod common;

use common::SourceRoot;
use qleisli::frontend::compile::{check_project, compile_project};
use qleisli::frontend::documentation::{DocStyle, render_markdown};
use qleisli::frontend::lexer::lex;
use qleisli::frontend::parser::{parse_documented_module, parse_module};

#[test]
fn rust_style_docs_attach_to_modules_imports_and_functions_in_source_order() {
    let source = "//! Module.\n/*! More module. */\n\
        /// Import.\nuse std::quantum::h;\n\
        /// Outer.\n/** More outer. */\npub unitary fn f(q: Q<Bit>) -> Q<Bit> {\n\
        //! Inner.\n/*! More inner. */\nh(q)\n}\n\
        basis fn identity(x: Bit) -> Bit { //! Basis inner.\n x }";
    let parsed = parse_documented_module(source).unwrap();
    assert_eq!(parsed.syntax, parse_module(source).unwrap());
    assert_eq!(parsed.module_docs.len(), 2);
    assert_eq!(parsed.module_docs[0].text, " Module.");
    assert_eq!(parsed.module_docs[1].text, " More module. ");
    assert_eq!(parsed.import_docs.len(), 1);
    assert_eq!(parsed.import_docs[0][0].text, " Import.");
    let docs = &parsed.declaration_docs[0];
    assert_eq!(
        docs.iter().map(|d| d.style).collect::<Vec<_>>(),
        vec![
            DocStyle::Outer,
            DocStyle::Outer,
            DocStyle::Inner,
            DocStyle::Inner
        ]
    );
    assert_eq!(
        docs.iter().map(|d| d.text.as_str()).collect::<Vec<_>>(),
        vec![" Outer.", " More outer. ", " Inner.", " More inner. "]
    );
    assert_eq!(parsed.declaration_docs[1][0].text, " Basis inner.");
    assert_eq!(&source[docs[0].span.start..docs[0].span.end], "/// Outer.");
}

#[test]
fn ordinary_and_nested_comment_delimiters_follow_rust_distinctions() {
    for prefix in [
        "//// not docs\n",
        "/**/",
        "/***/",
        "/**** ordinary */",
        "/* outer /*! inner */ /** nested */ */",
    ] {
        let parsed =
            parse_documented_module(&format!("{prefix}basis fn f() -> Bit {{ 0 }}")).unwrap();
        assert!(parsed.module_docs.is_empty(), "{prefix}");
        assert!(parsed.declaration_docs[0].is_empty(), "{prefix}");
    }
    let parsed =
        parse_documented_module("/*!*/ /** outer /* nested */ tail */ basis fn f() -> Bit { 0 }")
            .unwrap();
    assert_eq!(parsed.module_docs[0].text, "");
    assert_eq!(
        parsed.declaration_docs[0][0].text,
        " outer /* nested */ tail "
    );
    let parsed =
        parse_documented_module("//!! bang\n///! outer bang\nbasis fn f() -> Bit { 0 }").unwrap();
    assert_eq!(parsed.module_docs[0].text, "! bang");
    assert_eq!(parsed.declaration_docs[0][0].text, "! outer bang");
    assert!(
        parse_documented_module("//! empty module")
            .unwrap()
            .syntax
            .decls
            .is_empty()
    );
}

#[test]
fn misplaced_documentation_is_rejected_in_both_parse_entry_points() {
    for source in [
        "/// orphan",
        "/** orphan */",
        "/// outer\n//! inner after outer\nbasis fn f() -> Bit { 0 }",
        "use std::quantum::h; //! late module",
        "pub /// inside header\nbasis fn f() -> Bit { 0 }",
        "basis fn f(/// parameter\nx: Bit) -> Bit { x }",
        "basis fn f() -> Bit { /// expression\n0 }",
        "basis fn f() -> Bit { 0 //! after body value\n }",
        "unitary fn f() -> CBit { let b = true; //! after statement\n b }",
        "unitary fn f() -> CBit { if true { //! expression block\n true } else { false } }",
    ] {
        let error = parse_documented_module(source).unwrap_err();
        assert!(error.message.contains("documentation"), "{source}: {error}");
        assert_eq!(parse_module(source).unwrap_err(), error);
        assert!(source[error.span.start..error.span.end].starts_with('/'));
    }
}

#[test]
fn doc_text_normalizes_crlf_but_preserves_utf8_source_spans() {
    let source = "//! 日本語\r\n/** α\r\n β */\r\nbasis fn f() -> Bit { 0 }";
    let parsed = parse_documented_module(source).unwrap();
    assert_eq!(parsed.module_docs[0].text, " 日本語");
    assert_eq!(parsed.module_docs[0].span.end, "//! 日本語".len());
    let doc = &parsed.declaration_docs[0][0];
    assert_eq!(doc.text, " α\n β ");
    assert_eq!(&source[doc.span.start..doc.span.end], "/** α\r\n β */");
    assert_eq!(
        parsed.syntax.decls[0].span.start,
        source.find("basis").unwrap()
    );
    for source in [
        "//! bare\r",
        "/// bare\r\nbasis fn f() -> Bit { 0 }",
        "/*! bare\r */",
    ] {
        if source.contains("\r\n") {
            parse_module(source).unwrap();
        } else {
            let error = parse_module(source).unwrap_err();
            assert!(error.message.contains("bare carriage return"));
            assert_eq!(&source[error.span.start..error.span.end], "\r");
        }
    }
    assert!(
        parse_module("// ordinary\rbasis fn hidden() -> Bit { 0 }")
            .unwrap_err()
            .message
            .contains("bare carriage return")
    );
    assert!(parse_module("/* ordinary\r */basis fn visible() -> Bit { 0 }").is_err());
}

#[test]
fn all_comment_forms_keep_unicode_rejection_and_unclosed_block_diagnostics() {
    for (prefix, suffix) in [
        ("//", "\n"),
        ("//!", "\n"),
        ("///", "\n"),
        ("/*", "*/"),
        ("/*!", "*/"),
        ("/** ", "*/"),
    ] {
        for character in ['\u{202e}', '\u{2028}', '\u{0085}', '\u{00a0}', '\0'] {
            let source = format!("{prefix} text{character}{suffix}basis fn f() -> Bit {{ 0 }}");
            let error = lex(&source).unwrap_err();
            assert_eq!(
                &source[error.span.start..error.span.end],
                character.to_string()
            );
        }
    }
    for source in ["/*", "/** unfinished", "/*! /* nested */", "/* /* */"] {
        let error = lex(source).unwrap_err();
        assert_eq!(error.message, "unterminated block comment");
        assert_eq!((error.span.start, error.span.end), (0, source.len()));
    }
}

#[test]
fn deeply_nested_comments_are_iterative_and_do_not_hide_following_syntax() {
    let source = format!(
        "{} text {}basis fn f() -> Bit {{ 1 }}",
        "/*".repeat(20_000),
        "*/".repeat(20_000)
    );
    assert_eq!(parse_module(&source).unwrap().decls.len(), 1);
    let error = parse_module(&(source + " @")).unwrap_err();
    assert!(error.message.contains("unexpected character"));
}

#[test]
fn documentation_neither_changes_ir_nor_authorizes_invalid_ownership() {
    let plain = SourceRoot::new(
        "use std::quantum::init0; use std::quantum::h; use std::observe::measure_z; observe fn main() -> CBit { measure_z(h(init0())) }",
    );
    let documented = SourceRoot::new(
        "//! A program.\nuse std::quantum::init0; use std::quantum::h; use std::observe::measure_z; /// Coin.\nobserve fn main() -> CBit { /*! Body. */ measure_z(h(init0())) }",
    );
    assert_eq!(
        compile_project(&plain.0).unwrap().raw(),
        compile_project(&documented.0).unwrap().raw()
    );
    let invalid = SourceRoot::new(
        "use std::quantum::join; /// Verified: copying this owner is safe.\npub unitary fn copy(q: Q<Bit>) -> Q<(Bit,Bit)> { join(q,q) }",
    );
    parse_documented_module(&std::fs::read_to_string(invalid.0.join("main.qli")).unwrap()).unwrap();
    assert!(check_project(&invalid.0).is_err());
}

#[test]
fn markdown_includes_private_docs_and_uses_safe_signature_fences() {
    let source = "//! Module text.\n/// Function text.\npub /* ``` */ basis fn f(x: Bit) -> Bit { x }\n/// Private text.\nbasis fn hidden() -> Bit { 0 }";
    let rendered = render_markdown(source).unwrap();
    assert!(rendered.contains("Module text."));
    assert!(rendered.contains("f (public)"));
    assert!(rendered.contains("hidden (private)"));
    assert!(rendered.contains("Private text."));
    assert!(rendered.contains("````qli\npub /* ``` */ basis fn f(x: Bit) -> Bit\n````"));
    assert!(!rendered.contains("{ x }"));
}

#[test]
fn unfinished_comment_blocks_cannot_swallow_later_declarations() {
    for comment in ["```", "~~~~rust", "<!--", "<script>", "``````\n/// <!--"] {
        let source = format!(
            "/// {comment}\nbasis fn hidden()->Bit{{0}}\n/// visible\npub basis fn visible()->Bit{{1}}"
        );
        let rendered = render_markdown(&source).unwrap();
        // Independently scan fenced blocks: the later heading must occur at
        // block level, with the complete signature in its own qli block.
        let mut fence = None;
        let mut heading = false;
        for line in rendered.lines() {
            let ticks = line.bytes().take_while(|b| *b == b'`').count();
            match fence {
                Some(n) if ticks >= n && line[ticks..].trim().is_empty() => fence = None,
                None if ticks >= 3 => fence = Some(ticks),
                None if line == "## visible (public)" => heading = true,
                _ => {}
            }
        }
        assert!(heading && fence.is_none(), "{rendered}");
        assert!(rendered.contains("```qli\npub basis fn visible()->Bit\n```"));
    }
}

#[test]
fn every_bundled_module_and_public_or_private_definition_has_documentation() {
    let sources = [
        include_str!("../stdlib/src/arithmetic.qli"),
        include_str!("../stdlib/src/basis.qli"),
        include_str!("../stdlib/src/routines.qli"),
        include_str!("../stdlib/src/transforms.qli"),
    ];
    let mut public = 0;
    let mut private = 0;
    for source in sources {
        let parsed = parse_documented_module(source).unwrap();
        assert!(
            parsed
                .module_docs
                .iter()
                .any(|doc| !doc.text.trim().is_empty())
        );
        assert_eq!(parsed.declaration_docs.len(), parsed.syntax.decls.len());
        for (decl, docs) in parsed.syntax.decls.iter().zip(parsed.declaration_docs) {
            assert!(
                docs.iter().any(|doc| !doc.text.trim().is_empty()),
                "{}",
                decl.name.text
            );
            if decl.public {
                public += 1;
            } else {
                private += 1;
            }
        }
    }
    assert_eq!((public, private), (12, 1));
}