docs(code): remove stale pre-RFC role wording and fix review aid

Follow-up cleanup of text left by the concurrent implementation:

- marqdo-markdown AST, marqdo-ir statements/branch arms, frontend units,
  payload and signature module docs now describe RFC-LANG-0002 roles
  (payload carriers, heading modes, if/else groups, while/end, params)
- marqdo-expression public docs list parse_payload_statement and stop
  describing a Markdown-link call that no longer exists
- retired markdown.invalid_construct/markdown.inert_executable constants
  are documented as decode-only history for old Analysis/Trace JSON
- drop the stale 'expected red' comment in the CLI integration test
- the dev-only .mq.md review aid no longer reports semicolons inside
  string literals, and skips AST baselines / expected-invalid negatives

Verified: fmt, clippy -D warnings and cargo test --workspace --locked green.
This commit is contained in:
cflmy committed 2026-11-21 15:44:31 +08:00
1 parent 361a6cc341
commit d5002ac826
9 files changed
+104 -52

No files matched your search

+2 -3
View File
@@ -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"));
+24 -14
View File
@@ -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 <expr>`, `else`, `while <expr>`, `end`, `return <expr>`,
//! `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<Statement, ParseError> {
/// 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<Vec<Arg>, ParseError> {
parser::parse_arguments(source)
}
+5 -3
View File
@@ -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.
+5 -3
View File
@@ -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};
+13 -12
View File
@@ -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 {
+9 -8
View File
@@ -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<BranchArm>,
/// 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<Stmt>,
/// 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<Stmt>,
+2 -2
View File
@@ -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,
+5 -3
View File
@@ -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";
+39 -4
View File
@@ -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: