diff --git a/crates/cli/tests/integration_cli.rs b/crates/cli/tests/integration_cli.rs index 57c283e..aea125e 100644 --- a/crates/cli/tests/integration_cli.rs +++ b/crates/cli/tests/integration_cli.rs @@ -211,9 +211,8 @@ fn check_exit_codes_and_diagnostics() { assert!(stderr_text(&bad_json).is_empty()); // RFC-LANG-0002: a Strong at the Knowledge root is inert prose, not an - // executable shape. There is no `markdown.inert_executable` warning; the - // pre-RFC frontend still emits it, so this assertion is expected red until - // the frontend migration lands. + // executable shape, and the old `markdown.inert_executable` warning no + // longer exists. let inert = cli(dir.path(), &["check", "warning.mq.md"]); assert_exit(&inert, 0, "inert Knowledge prose does not fail check"); assert!(stdout_text(&inert).contains("checked 1 module(s): ok")); diff --git a/crates/marqdo-expression/src/lib.rs b/crates/marqdo-expression/src/lib.rs index a40ff79..e1d0883 100644 --- a/crates/marqdo-expression/src/lib.rs +++ b/crates/marqdo-expression/src/lib.rs @@ -1,10 +1,12 @@ -//! Strict, independent expression and statement parser for executable Markdown -//! payloads. +//! Strict, independent payload statement and expression parser for executable +//! Markdown payloads. //! //! This crate is the only grammar for Marqdo executable payloads. It knows //! nothing about Markdown and nothing about the runtime: the Markdown AST //! decides *where* a payload exists, this crate decides *what the payload -//! means* (see `spec/expression.ebnf` and `spec/evaluation.md`). +//! means* (see `spec/expression.ebnf` and `spec/evaluation.md`). The +//! [`statement`] module owns the `if`/`else`/`while`/`end`/`return`/`params` +//! statement keywords; the parser here owns their expressions. //! //! # Public API //! @@ -21,10 +23,15 @@ //! The contractual surface is: //! //! * [`parse_expression`] — parse a complete expression payload. -//! * [`parse_statement`] — parse a complete statement payload (assignment or -//! expression). -//! * [`parse_arguments`] — parse a leading `( ... )` argument list, used for -//! Markdown-link calls such as `> [计算面积](./math.mq.md#计算面积)(r=3)`. +//! * [`parse_payload_statement`]/[`PayloadStatement`] — parse one complete +//! payload under the v2 statement grammar (control keyword, `params`, or an +//! ordinary assignment/expression). +//! * [`parse_statement`] — parse a complete assignment/expression payload +//! (without control keywords). +//! * [`parse_arguments`] — parse a leading `( ... )` argument list. There is no +//! Markdown-link call in the current language; this remains the shared +//! argument-list grammar used by callers that must parse arguments without a +//! callee (for example builtin signature validation tests). //! * the [`ast`] module (re-exported at the crate root). //! * [`ParseError`] — structured `expr.parse` diagnostics with byte spans. //! @@ -33,11 +40,14 @@ //! //! # Grammar summary //! -//! The grammar is frozen in `spec/expression.ebnf`. In order of decreasing -//! precedence: prefix `not` / `-` / `+`, `**` (right associative), postfix -//! calls `.name` / `[index]`, `* / // %`, `+ -`, a single non-associative -//! comparison, `and`, `or`. Assignment is only available at statement start; -//! its target is a bare identifier or an index expression (`m[8] = 42`). +//! The grammar is frozen in `spec/expression.ebnf`. One payload is exactly one +//! statement: `if `, `else`, `while `, `end`, `return `, +//! `params(...)`, an assignment or a bare expression. Within an expression, in +//! order of decreasing precedence: prefix `not` / `-` / `+`, `**` (right +//! associative), postfix calls `.name` / `[index]`, `* / // %`, `+ -`, a single +//! non-associative comparison, `and`, `or`. Assignment is only available at +//! statement start; its target is a bare identifier or an index expression +//! (`m[8] = 42`). //! //! Notable lexical rules: //! @@ -156,8 +166,8 @@ pub fn parse_statement(source: &str) -> Result { /// positional arguments precede named arguments, named arguments are unique, /// and a single trailing comma is allowed. Trailing tokens are an error. /// -/// This exists so the frontend can parse Markdown-link calls of the form -/// `> [计算面积](./math.mq.md#计算面积)(r=3)` without re-lexing the payload. +/// This is the shared argument-list grammar (call postfixes and callers that +/// validate arguments without a callee expression). pub fn parse_arguments(source: &str) -> Result, ParseError> { parser::parse_arguments(source) } diff --git a/crates/marqdo-frontend/src/payload.rs b/crates/marqdo-frontend/src/payload.rs index 90060fa..4216b50 100644 --- a/crates/marqdo-frontend/src/payload.rs +++ b/crates/marqdo-frontend/src/payload.rs @@ -1,7 +1,9 @@ -//! Executable payload extraction with a payload → file span map. +//! Payload extraction with a payload → file span map. //! -//! A payload is the concatenation of the direct `text` and `code` children of -//! an executable node. The expression parser sees only that concatenated +//! Inside an `@exec` scope, `Strong`, `Emph` and inline `Code` are equivalent +//! one-statement carriers. For `Strong`/`Emph` the payload is the +//! concatenation of their direct `text` and `code` children; a nested carrier +//! is an error. The expression/statement parser sees only the concatenated //! string, so its spans are payload-relative; this module maps them back to the //! original file so diagnostics point at real source. diff --git a/crates/marqdo-frontend/src/signature.rs b/crates/marqdo-frontend/src/signature.rs index 3d8ea61..5c4f7d5 100644 --- a/crates/marqdo-frontend/src/signature.rs +++ b/crates/marqdo-frontend/src/signature.rs @@ -1,8 +1,10 @@ //! Optional explicit function signatures. //! -//! `` `(r: Number, precision: Int = 2)` `` as the first paragraph of a -//! function body declares the public parameter list. It is a *declaration*: -//! it does not execute. Without it, parameters are inferred from free reads. +//! `` `params(r: Number, precision: Int = 2)` `` as the first function-wide +//! direct payload of an Exec H2 declares the public parameter list. It is a +//! *declaration*: it does not execute. Without it, parameters are inferred from +//! free reads (and an inferred signature keeps the named-arguments-only rule). +//! See RFC-LANG-0002 and `spec/mapping.md` §6. use marqdo_expression::{parse_expression, Expr, Statement, StatementKind}; use marqdo_ir::{Param, SignatureKind}; diff --git a/crates/marqdo-frontend/src/units.rs b/crates/marqdo-frontend/src/units.rs index 21d40e5..cb9742c 100644 --- a/crates/marqdo-frontend/src/units.rs +++ b/crates/marqdo-frontend/src/units.rs @@ -1,17 +1,19 @@ -//! Heading scope index. +//! Heading scope and semantic-mode index (RFC-LANG-0002). //! -//! Markdown headings are sibling blocks, so function scopes are derived from -//! heading levels, not from container nesting: +//! Markdown headings are sibling blocks, so scopes are derived from heading +//! levels, not from container nesting: //! -//! * `heading(level=1)` -> namespace / object domain (blueprint 1.2, 2.1) -//! * `heading(level=2)` -> function -//! * `heading(level>=3)` -> named section inside the enclosing unit, never a -//! new callable function +//! * `heading(level=1)` -> namespace / top-level unit +//! * `heading(level=2, mode=Exec)` -> callable function +//! * `heading(level=2, mode=Knowledge)` -> inert knowledge unit +//! * `heading(level>=3)` -> section of the enclosing unit, never a callable +//! function //! -//! The range of a heading extends to the next heading of the same or a lower -//! level (same or smaller number). Headings inside block quotes, list items or -//! code fences cannot appear as direct children of the document, hence they can -//! never create functions. +//! Each heading declares `@exec`/`@knowledge` or inherits the nearest ancestor +//! heading's mode; the document root is Knowledge. The range of a heading +//! extends to the next heading of the same or a lower level (same or smaller +//! number). Headings inside block quotes, list items or code fences cannot +//! appear as direct children of the document, hence they never create units. use std::collections::BTreeMap; @@ -105,7 +107,6 @@ fn has_payload(node: &MdNode) -> bool { } } -/// Build the heading/function index for a parsed document. /// Semantic mode declared or inherited by a heading (RFC-LANG-0002). #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum SemanticMode { diff --git a/crates/marqdo-ir/src/lib.rs b/crates/marqdo-ir/src/lib.rs index 20829dd..e6073fc 100644 --- a/crates/marqdo-ir/src/lib.rs +++ b/crates/marqdo-ir/src/lib.rs @@ -228,8 +228,9 @@ pub struct Function { /// Writable place of an assignment (ADR-0022). /// -/// The Markdown surface is unchanged: both variants are `strong` nodes whose -/// payload contains `target = expression`. `Local` rebinds a frame slot; +/// Both variants come from an executable payload whose text is +/// `target = expression` (any carrier: `Strong`, `Emph` or inline `Code`). +/// `Local` rebinds a frame slot; /// `Index` writes one byte into an addressable runtime `Memory` region and is /// rejected for every other base value. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] @@ -283,14 +284,14 @@ pub enum Stmt { /// Span of the whole statement. span: Span, }, - /// Ordered list: first matching condition wins. + /// `if`/`else` group: the first true arm wins. Branch { /// Arms in AST order. arms: Vec, /// Span of the list node. span: Span, }, - /// Bullet list item: a `while` loop. + /// `while`/`end` group. Loop { /// Loop condition. condition: Expr, @@ -298,10 +299,10 @@ pub enum Stmt { condition_span: Span, /// Loop body. body: Vec, - /// Span of the list item. + /// Span of the whole `while` statement. span: Span, }, - /// Return from the enclosing function (`emph` node). + /// Return from the enclosing function (`return` statement). Return { /// Returned expression. value: Expr, @@ -323,12 +324,12 @@ impl Stmt { } } -/// One arm of a branch (ordered list item). +/// One arm of an `if`/`else` group. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct BranchArm { /// Boolean condition expression. pub condition: Expr, - /// Span of the condition code span. + /// Span of the condition payload. pub condition_span: Span, /// Statements executed when the condition is true. pub body: Vec, diff --git a/crates/marqdo-markdown/src/ast.rs b/crates/marqdo-markdown/src/ast.rs index 64793d3..1d523f5 100644 --- a/crates/marqdo-markdown/src/ast.rs +++ b/crates/marqdo-markdown/src/ast.rs @@ -72,9 +72,9 @@ pub enum MdKind { Paragraph, /// Literal text. Text, - /// Strong emphasis: an execution statement in executable position. + /// Strong emphasis: one payload carrier in an `@exec` scope. Strong, - /// Emphasis: a return statement in executable position. + /// Emphasis: one payload carrier in an `@exec` scope. Emph, /// GFM strikethrough. Strikethrough, diff --git a/crates/marqdo-value/src/diagnostic.rs b/crates/marqdo-value/src/diagnostic.rs index b12af11..4c36cc0 100644 --- a/crates/marqdo-value/src/diagnostic.rs +++ b/crates/marqdo-value/src/diagnostic.rs @@ -6,10 +6,12 @@ use serde::{Deserialize, Serialize}; /// Stable diagnostic codes. CI may depend on these strings; they must not be /// renamed without an ADR because they are part of the CLI contract. pub mod codes { - /// A Markdown AST node occupies an executable position but has an invalid shape. + /// Retired by RFC-LANG-0002: executable payload shapes are reported as + /// `sem.*` instead. Kept only for decoding historical Analysis/Trace JSON. pub const MARKDOWN_INVALID_CONSTRUCT: &str = "markdown.invalid_construct"; - /// A node that would be executable appears outside any function body and is - /// therefore inert document content. + /// Retired by RFC-LANG-0002: a payload with no owning Exec H2 is + /// `sem.exec_without_function`, and Knowledge content is inert without a + /// warning. Kept only for decoding historical Analysis/Trace JSON. pub const MARKDOWN_INERT_EXECUTABLE: &str = "markdown.inert_executable"; /// Front matter is malformed or appears somewhere other than the document start. pub const FRONTMATTER_INVALID: &str = "frontmatter.invalid"; diff --git a/tools/dev-only/check-mq-syntax.py b/tools/dev-only/check-mq-syntax.py index d1e82ef..0f46ab3 100644 --- a/tools/dev-only/check-mq-syntax.py +++ b/tools/dev-only/check-mq-syntax.py @@ -28,6 +28,33 @@ HEADING = re.compile(r"^(#{1,6})\s+(.*)$") MODE = re.compile(r"^@(exec|knowledge)\b\s*(.*)$") +def split_semicolons(text: str) -> list[str]: + """Split a payload on `;` outside text literals and backtick spans.""" + parts, current = [], [] + in_text = in_code = False + escaped = False + for ch in text: + if escaped: + current.append(ch) + escaped = False + continue + if ch == "\\" and in_text: + current.append(ch) + escaped = True + continue + if ch == '"' and not in_code: + in_text = not in_text + elif ch == "`" and not in_text: + in_code = not in_code + if ch == ";" and not in_text and not in_code: + parts.append("".join(current)) + current = [] + continue + current.append(ch) + parts.append("".join(current)) + return parts + + def payload_of(line: str): s = line.strip() while True: @@ -46,6 +73,14 @@ def payload_of(line: str): def check(path: Path) -> list[str]: + # AST fixtures pin the native Markdown profile, not the language mapping; + # several intentionally contain empty/invalid carriers as raw Markdown. + if "conformance/ast" in path.as_posix(): + return [] + # Negative fixtures intentionally contain invalid declarations and broken + # control stacks; their expected diagnostics are asserted by the Rust + # negative harness, so this review aid only checks them structurally. + expected_invalid = "tests/negative" in path.as_posix() errors: list[str] = [] stack: list[tuple[str, int]] = [] headings: list[tuple[int, str | None, int]] = [] # level, explicit mode @@ -74,9 +109,9 @@ def check(path: Path) -> list[str]: mm = MODE.match(body) mode = mm.group(1) if mm else None name = mm.group(2).strip() if mm else body.strip() - if mm and not name: + if mm and not name and not expected_invalid: errors.append(f"{path}:{i}: mode without heading name") - if not mm and re.match(r"^@[A-Za-z]", name): + if not mm and re.match(r"^@[A-Za-z]", name) and not expected_invalid: errors.append(f"{path}:{i}: unknown mode marker {name.split()[0]}") while headings and headings[-1][0] >= level: headings.pop() @@ -97,8 +132,8 @@ def check(path: Path) -> list[str]: break if not owning: continue - if ";" in text: - errors.append(f"{path}:{i}: semicolon in one payload: {text!r}") + if len(split_semicolons(text)) > 1: + errors.append(f"{path}:{i}: semicolon-separated statements in one payload: {text!r}") first = text.split(None, 1)[0] if first in ("if", "while"): if len(text.split()) == 1: