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:
1 parent
361a6cc341
commit
d5002ac826
9 files changed
+104
-52
No files matched your search
@@ -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"));
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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};
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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>,
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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";
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in new issue
Block a user