feat(frontend): heading scopes, semantic mapping, inference and call validation

Implement the P0/P1 frontend from spec/mapping.md, spec/evaluation.md:

- units: heading scope index (level-1 namespace, level-2 function, level>=3
  section), range computation, duplicate/empty-name diagnostics, GitHub anchor
  table kept separate from canonical ids, and warnings for would-be execution
  nodes outside function bodies.
- map: AST-to-IR mapping where role comes from node kind + position. Strong is
  an execution statement, Emph a return, ordered list a branch, bullet list a
  loop sequence, block quote a call; invalid shapes are hard
  markdown.invalid_construct errors, never prose fallback. Payload parsing
  errors are mapped from payload-relative to file-relative spans.
- payload: strict text/code payload concatenation with exact span mapping
  (including code-span delimiter handling) used to rewrite expression spans
  onto the source file.
- signature: optional `(name: Type = const)` paragraph declaration; defaults
  must be compile-time constants; duplicates and malformed declarations are
  errors.
- infer: definite-assignment data-flow parameter inference (must/may/ambiguous
  states, loop first-iteration handling, branch joins) per blueprint S-04.
- calls: static call validation of arity/named arguments/builtin signatures
  after all signatures are known; inferred signatures accept named args only.
- resources: inert Formula/Code resources with owning units and SHA-256
  content hashes.
- analyze: pipeline (parse -> units -> frontmatter imports -> map -> signature/
  inference -> module -> call checks) that never executes anything.

Tests include factorial recursion, loop counter, prose-invariance (IR equal
modulo spans), and hard-error cases.
This commit is contained in:
cflmy committed 2026-11-20 10:36:12 +08:00
1 parent 62a9af05fd
commit 8003907f4e
10 files changed
+2763 -3

No files matched your search

+5 -3
View File
@@ -11,11 +11,13 @@ authors.workspace = true
[dependencies]
unicode-normalization = { workspace = true }
marqdo-span = { workspace = true }
unicode-ident = { workspace = true }
sha2 = { workspace = true }
marqdo-markdown = { workspace = true }
marqdo-expression = { workspace = true }
marqdo-ir = { workspace = true }
marqdo-value = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
[dev-dependencies]
serde_json = { workspace = true }
+263
View File
@@ -0,0 +1,263 @@
//! Compilation pipeline for one document: Markdown AST → unit index → IR.
//!
//! `analyze_source` never executes anything and never loads third-party code.
//! It is the entry point used by `check`, `inspect` and (before running) `run`.
use std::collections::BTreeSet;
use marqdo_ir::{Function, ImportDecl, Module, ModuleId, Param, SignatureKind};
use marqdo_markdown::MarkdownDocument;
use marqdo_value::{codes, Diagnostic};
use crate::calls;
use crate::infer;
use crate::map;
use crate::resources;
use crate::signature;
use crate::units::{self, UnitIndex};
/// Result of analyzing one source document.
#[derive(Debug, Clone)]
pub struct AnalysisResult {
/// Canonical module AST (available even when diagnostics contain errors).
pub module: Module,
/// Parsed Markdown document.
pub document: MarkdownDocument,
/// Unit index for inspection.
pub units: UnitIndex,
/// All diagnostics, in deterministic order.
pub diagnostics: Vec<Diagnostic>,
}
impl AnalysisResult {
/// Whether any diagnostic is an error.
pub fn has_errors(&self) -> bool {
self.diagnostics.iter().any(Diagnostic::is_error)
}
}
/// Analyze one Markdown source as a Marqdo module.
///
/// `module_id` is the canonical project-relative identity (e.g. `index.mq.md`).
pub fn analyze_source(module_id: &str, source: &str) -> AnalysisResult {
let id = ModuleId::from(module_id);
let document = marqdo_markdown::parse(source);
let units = units::build_units(&document, &id);
let mut diagnostics = units.diagnostics.clone();
// Explicit front matter imports. Nothing is inferred.
let mut imports: Vec<ImportDecl> = Vec::new();
if let Some(frontmatter) = document.frontmatter() {
if let Err(error) = &frontmatter.yaml {
diagnostics.push(
Diagnostic::error(
codes::FRONTMATTER_INVALID,
Some(frontmatter.yaml_span),
format!("invalid YAML front matter: {error}"),
)
.with_hint("front matter must be valid YAML between `---` delimiters"),
);
}
match frontmatter.imports() {
Ok(mapping) => {
for (alias, target) in mapping {
imports.push(ImportDecl {
alias,
target,
span: frontmatter.span,
});
}
}
Err(error) => diagnostics.push(
Diagnostic::error(
codes::FRONTMATTER_INVALID,
Some(frontmatter.span),
format!("invalid import declaration: {error}"),
)
.with_hint("imports are an explicit mapping: `import: { alias: \"@module\" }`"),
),
}
}
let resources = resources::collect(&document, &units, &id);
let import_names: BTreeSet<String> =
imports.iter().map(|import| import.alias.clone()).collect();
let mut functions: Vec<Function> = Vec::new();
for scope in &units.functions {
let blocks: Vec<&marqdo_markdown::MdNode> = document.root.children
[scope.body_start..scope.body_end]
.iter()
.collect();
let signature = signature::detect(&document, &blocks);
let explicit = signature.as_ref().map(|(_, sig)| sig);
let mut mapped = map::map_function(&document, &units, &imports, scope);
diagnostics.append(&mut mapped.diagnostics);
let mut params: Vec<Param> = Vec::new();
let mut kind = SignatureKind::Inferred;
if let Some(sig) = explicit {
kind = SignatureKind::Explicit;
diagnostics.extend(sig.diagnostics.clone());
params = sig.params.clone();
}
let inference = infer::infer(&mapped.stmts, explicit, &import_names);
diagnostics.extend(inference.diagnostics);
if kind == SignatureKind::Inferred {
params = inference
.params
.into_iter()
.map(|candidate| Param {
name: candidate.name,
span: candidate.span,
type_annotation: None,
default: None,
})
.collect();
}
functions.push(Function {
id: scope.id.clone(),
local_name: scope.local_name.clone(),
namespace: scope.namespace.clone(),
unit: scope.unit.clone(),
heading_span: scope.heading_span,
span: scope.span,
params,
signature: kind,
body: mapped.stmts,
});
}
let module = Module {
id,
units: units.units.clone(),
functions,
imports,
resources,
anchors: units.anchors.clone(),
};
diagnostics.extend(calls::validate_module(&module));
AnalysisResult {
module,
document,
units,
diagnostics,
}
}
#[cfg(test)]
mod tests {
use super::*;
fn analyze(source: &str) -> AnalysisResult {
analyze_source("index.mq.md", source)
}
#[test]
fn maps_recursive_factorial() {
let source = r#"# 数学
## 阶乘
1. `n <= 1`
*1*
2. `n > 1`
**结果 = n * 阶乘(n=n-1)**
*结果*
"#;
let result = analyze(source);
assert!(
!result.has_errors(),
"unexpected diagnostics: {:#?}",
result.diagnostics
);
let function = result.module.function("数学.阶乘").expect("factorial");
assert_eq!(function.signature, SignatureKind::Inferred);
assert_eq!(function.params.len(), 1);
assert_eq!(function.params[0].name, "n");
assert!(matches!(function.body[0], marqdo_ir::Stmt::Branch { .. }));
}
#[test]
fn maps_countdown_loop() {
let source = r#"## 倒计时
**n = 3**
- `n > 0`
> 打印(n)
**n = n - 1**
*n*
"#;
let result = analyze(source);
assert!(!result.has_errors(), "{:#?}", result.diagnostics);
let function = result.module.function("倒计时").expect("countdown");
assert!(function.params.is_empty());
assert!(matches!(function.body[1], marqdo_ir::Stmt::Loop { .. }));
}
#[test]
fn invalid_strong_payload_is_a_hard_error() {
let result = analyze("## f\n\n**a *b* c**\n");
assert!(result.has_errors());
assert!(result
.diagnostics
.iter()
.any(|d| d.code == codes::MARKDOWN_INVALID_CONSTRUCT));
}
#[test]
fn invalid_list_header_is_a_hard_error() {
let result = analyze("## f\n\n1. 没有条件\n");
assert!(result.has_errors());
assert!(result
.diagnostics
.iter()
.any(|d| d.code == codes::MARKDOWN_INVALID_CONSTRUCT));
}
/// Strip source spans so that pure narrative edits (which shift byte
/// offsets) still compare equal, as required by blueprint 14.2.
fn without_spans(value: &serde_json::Value) -> serde_json::Value {
match value {
serde_json::Value::Object(map) => {
let mut out = serde_json::Map::new();
for (key, value) in map {
if key == "span"
|| key == "heading_span"
|| key == "name_span"
|| key == "condition_span"
{
continue;
}
out.insert(key.clone(), without_spans(value));
}
serde_json::Value::Object(out)
}
serde_json::Value::Array(items) => {
serde_json::Value::Array(items.iter().map(without_spans).collect())
}
other => other.clone(),
}
}
#[test]
fn prose_changes_do_not_change_ir() {
let base = "## f\n\n说明文字。\n\n**x = 1**\n\n更多说明。\n\n*x*\n";
let edited = "## f\n\n另一段完全不同的叙述。\n\n**x = 1**\n\n继续叙述。\n\n*x*\n";
let a = analyze(base);
let b = analyze(edited);
let a_ir = serde_json::to_value(&a.module.functions).unwrap();
let b_ir = serde_json::to_value(&b.module.functions).unwrap();
assert_eq!(without_spans(&a_ir), without_spans(&b_ir));
}
}
+404
View File
@@ -0,0 +1,404 @@
//! Static call validation.
//!
//! Calls are resolved after all functions have signatures (including inferred
//! ones), so arity/name mistakes are compile errors with source spans instead
//! of surprises at runtime. Type errors stay runtime concerns: v1 has no static
//! type inference beyond literal checks.
use std::collections::{BTreeMap, BTreeSet};
use marqdo_expression::{Arg, Expr, Ident};
use marqdo_ir::{builtins, Module, Param, SignatureKind, Stmt};
use marqdo_span::Span;
use marqdo_value::{codes, Diagnostic};
/// Signature information needed to validate a call.
#[derive(Debug, Clone)]
pub struct CallableSignature {
/// Parameter list.
pub params: Vec<Param>,
/// Explicit signatures allow positional arguments; inferred do not.
pub kind: SignatureKind,
}
/// Build the callable signature table for a module.
pub fn signature_table(module: &Module) -> BTreeMap<String, CallableSignature> {
let mut table = BTreeMap::new();
for function in &module.functions {
table.insert(
function.id.name.clone(),
CallableSignature {
params: function.params.clone(),
kind: function.signature,
},
);
}
table
}
/// Validate every call in every function body of the module.
pub fn validate_module(module: &Module) -> Vec<Diagnostic> {
let table = signature_table(module);
let mut diagnostics = Vec::new();
for function in &module.functions {
let mut locals: BTreeSet<String> = function
.params
.iter()
.map(|param| param.name.clone())
.collect();
collect_assigned(&function.body, &mut locals);
let mut check = CallChecker {
current_namespace: function.namespace.clone(),
locals: &locals,
table: &table,
imports: module
.imports
.iter()
.map(|import| import.alias.clone())
.collect(),
diagnostics: Vec::new(),
};
check.stmts(&function.body);
diagnostics.extend(check.diagnostics);
}
diagnostics
}
fn collect_assigned(stmts: &[Stmt], out: &mut BTreeSet<String>) {
for stmt in stmts {
match stmt {
Stmt::Assign { name, .. } => {
out.insert(name.clone());
}
Stmt::Branch { arms, .. } => {
for arm in arms {
collect_assigned(&arm.body, out);
}
}
Stmt::Loop { body, .. } => collect_assigned(body, out),
_ => {}
}
}
}
struct CallChecker<'a> {
current_namespace: Option<String>,
locals: &'a BTreeSet<String>,
table: &'a BTreeMap<String, CallableSignature>,
imports: BTreeSet<String>,
diagnostics: Vec<Diagnostic>,
}
impl<'a> CallChecker<'a> {
fn stmts(&mut self, stmts: &[Stmt]) {
for stmt in stmts {
match stmt {
Stmt::Assign { value, .. }
| Stmt::Eval { expr: value, .. }
| Stmt::Return { value, .. } => {
self.expr(value);
}
Stmt::Call { call, .. } => {
for Arg { value, .. } in &call.args {
self.expr(value);
}
}
Stmt::Branch { arms, .. } => {
for arm in arms {
self.expr(&arm.condition);
self.stmts(&arm.body);
}
}
Stmt::Loop {
condition, body, ..
} => {
self.expr(condition);
self.stmts(body);
}
}
}
}
fn expr(&mut self, expr: &Expr) {
match expr {
Expr::Int(_) | Expr::Float(_) | Expr::Text(_) | Expr::Bool(_) | Expr::None => {}
Expr::Ident(_) => {}
Expr::List(items) => items.iter().for_each(|item| self.expr(item)),
Expr::Record(entries) => entries.iter().for_each(|entry| self.expr(&entry.value)),
Expr::Unary { operand, .. } => self.expr(operand),
Expr::Binary { left, right, .. } => {
self.expr(left);
self.expr(right);
}
Expr::Member { base, .. } => self.expr(base),
Expr::Index { base, index, .. } => {
self.expr(base);
self.expr(index);
}
Expr::Call { callee, args, span } => {
self.call(callee, args, *span);
for arg in args {
self.expr(&arg.value);
}
}
}
}
fn call(&mut self, callee: &Expr, args: &[Arg], span: Span) {
match callee {
Expr::Ident(Ident { name, .. }) => {
if let Some(builtin) = builtins::find(name) {
if let Err(message) = builtins::validate_args(builtin, args) {
self.diagnostics.push(
Diagnostic::error(codes::CALL_ARITY, Some(span), message)
.with_hint("check the builtin parameter list"),
);
}
return;
}
let name_span = match callee {
Expr::Ident(Ident { span, .. }) => *span,
_ => span,
};
if let Some(signature) = self.resolve(name) {
self.validate_against(name, signature, args, span, name_span);
return;
}
if self.locals.contains(name) || self.imports.contains(name) {
// A local may hold a FunctionRef value; resolved at runtime.
return;
}
self.diagnostics.push(
Diagnostic::error(
codes::SYMBOL_UNKNOWN,
Some(name_span),
format!("unknown function `{name}`"),
)
.with_hint("define it as a level-2 heading or call a builtin"),
);
}
// Qualified calls are validated once the imported module has been
// analysed by the loader; argument expressions are still checked.
Expr::Member { base, .. } => self.expr(base),
other => self.expr(other),
}
}
fn resolve(&self, name: &str) -> Option<&'a CallableSignature> {
if let Some(namespace) = &self.current_namespace {
if let Some(found) = self.table.get(&format!("{namespace}.{name}")) {
return Some(found);
}
}
if let Some(found) = self.table.get(name) {
return Some(found);
}
// Unique local name across namespaces.
let mut matches = self
.table
.iter()
.filter(|(key, _)| key.ends_with(&format!(".{name}")))
.map(|(_, signature)| signature);
let first = matches.next()?;
if matches.next().is_some() {
None
} else {
Some(first)
}
}
fn validate_against(
&mut self,
name: &str,
signature: &CallableSignature,
args: &[Arg],
call_span: Span,
name_span: Span,
) {
if signature.kind == SignatureKind::Inferred {
if let Some(positional) = args.iter().find(|arg| arg.name.is_none()) {
self.diagnostics.push(
Diagnostic::error(
codes::CALL_ARITY,
Some(positional.span),
format!(
"`{name}` has an inferred signature and only accepts named arguments"
),
)
.with_hint("pass arguments as `name = value`"),
);
}
}
let mut supplied: BTreeSet<&str> = BTreeSet::new();
let mut positional = 0usize;
for arg in args {
match &arg.name {
Some(argument_name) => {
if !signature
.params
.iter()
.any(|param| param.name == *argument_name)
{
self.diagnostics.push(
Diagnostic::error(
codes::CALL_ARITY,
Some(arg.span),
format!("`{name}` has no parameter named `{argument_name}`"),
)
.with_hint("check `inspect --signature`"),
);
}
supplied.insert(argument_name.as_str());
}
None => {
if let Some(param) = signature.params.get(positional) {
supplied.insert(param.name.as_str());
positional += 1;
} else {
self.diagnostics.push(Diagnostic::error(
codes::CALL_ARITY,
Some(call_span),
format!(
"`{name}` accepts at most {} positional argument(s)",
signature.params.len()
),
));
}
}
}
}
for param in &signature.params {
if param.default.is_none() && !supplied.contains(param.name.as_str()) {
self.diagnostics.push(
Diagnostic::error(
codes::CALL_ARITY,
Some(name_span),
format!("`{name}` is missing required argument `{}`", param.name),
)
.with_hint("pass it by name, e.g. `x = value`"),
);
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use marqdo_expression::parse_expression;
use marqdo_ir::{Function, FunctionId, ModuleId, Param, UnitId};
fn function(name: &str, params: &[&str], kind: SignatureKind, body: Vec<Stmt>) -> Function {
Function {
id: FunctionId {
module: ModuleId::from("index.mq.md"),
name: name.to_string(),
},
local_name: name.to_string(),
namespace: None,
unit: UnitId {
module: ModuleId::from("index.mq.md"),
path: vec![name.to_string()],
},
heading_span: Span::new(0, 0),
span: Span::new(0, 0),
params: params
.iter()
.map(|name| Param {
name: name.to_string(),
span: Span::new(0, 0),
type_annotation: None,
default: None,
})
.collect(),
signature: kind,
body,
}
}
fn make_module(functions: Vec<Function>) -> Module {
Module {
id: ModuleId::from("index.mq.md"),
units: vec![],
functions,
imports: vec![],
resources: vec![],
anchors: std::collections::BTreeMap::new(),
}
}
fn return_call(code: &str) -> Stmt {
Stmt::Return {
value: parse_expression(code).unwrap(),
span: Span::new(0, 0),
}
}
#[test]
fn unknown_function_is_an_error() {
let module = make_module(vec![function(
"main",
&[],
SignatureKind::Explicit,
vec![return_call("nope(1)")],
)]);
let diagnostics = validate_module(&module);
assert!(diagnostics.iter().any(|d| d.code == codes::SYMBOL_UNKNOWN));
}
#[test]
fn inferred_signature_requires_named_arguments() {
let callee = function("f", &["n"], SignatureKind::Inferred, vec![]);
let module = make_module(vec![
function(
"main",
&[],
SignatureKind::Explicit,
vec![return_call("f(1)")],
),
callee,
]);
let diagnostics = validate_module(&module);
assert!(diagnostics.iter().any(|d| d.code == codes::CALL_ARITY));
}
#[test]
fn explicit_signature_allows_positional_and_checks_arity() {
let callee = function("f", &["a", "b"], SignatureKind::Explicit, vec![]);
let module = make_module(vec![
function(
"main",
&[],
SignatureKind::Explicit,
vec![return_call("f(1, 2)")],
),
callee,
]);
assert!(validate_module(&module).is_empty());
let module = make_module(vec![
function(
"main",
&[],
SignatureKind::Explicit,
vec![return_call("f(1)")],
),
function("f", &["a", "b"], SignatureKind::Explicit, vec![]),
]);
assert!(validate_module(&module)
.iter()
.any(|d| d.code == codes::CALL_ARITY));
}
#[test]
fn builtin_arity_is_checked() {
let module = make_module(vec![function(
"main",
&[],
SignatureKind::Explicit,
vec![return_call("打印()")],
)]);
assert!(validate_module(&module)
.iter()
.any(|d| d.code == codes::CALL_ARITY));
}
}
+397
View File
@@ -0,0 +1,397 @@
//! Static parameter inference via definite-assignment data-flow analysis.
//!
//! Parameters come only from free reads of executable expressions. Prose,
//! headings, inert code spans and natural language never introduce parameters.
//!
//! The analysis tracks, for every program point:
//! * `must` – variables definitely assigned on every path from entry;
//! * `may` – variables assigned on at least one path;
//! * `ambiguous` – variables that may have been assigned before the read on
//! some path but not on all paths, which makes the variable's identity
//! ambiguous (blueprint S-04) rather than silently inventing a parameter.
//!
//! Loop bodies get special treatment: their first iteration starts from the
//! pre-loop state, so a read of an entry variable inside a loop is a parameter
//! candidate even though the body also assigns it (the classic counter case).
use std::collections::{BTreeMap, BTreeSet};
use marqdo_expression::{Arg, Expr, Ident, RecordEntry};
use marqdo_ir::{BranchArm, Stmt};
use marqdo_span::Span;
use marqdo_value::{codes, Diagnostic};
use crate::signature::Signature;
/// Result of the inference analysis for one function.
#[derive(Debug, Clone, Default)]
pub struct Inference {
/// Candidate parameters sorted by canonical name.
pub params: Vec<ParamCandidate>,
/// Diagnostics (ambiguity errors, explicit-signature unknown reads).
pub diagnostics: Vec<Diagnostic>,
}
/// One inferred parameter candidate.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParamCandidate {
/// Canonical parameter name.
pub name: String,
/// Span of the first free read.
pub span: Span,
}
#[derive(Debug, Clone, Default)]
struct State {
must: BTreeSet<String>,
may: BTreeSet<String>,
ambiguous: BTreeSet<String>,
}
impl State {
fn join(&self, other: &State) -> State {
State {
must: self.must.intersection(&other.must).cloned().collect(),
may: self.may.union(&other.may).cloned().collect(),
ambiguous: self.ambiguous.union(&other.ambiguous).cloned().collect(),
}
}
}
struct Analyzer<'a> {
/// Names that are parameters/locals/builtins/imports and therefore never
/// reported as unknown; used for explicit signatures.
known: Option<&'a BTreeSet<String>>,
reads: BTreeMap<String, Span>,
diagnostics: Vec<Diagnostic>,
ambiguous_reported: BTreeSet<String>,
unknown_reported: BTreeSet<String>,
}
impl<'a> Analyzer<'a> {
fn new(known: Option<&'a BTreeSet<String>>) -> Self {
Self {
known,
reads: BTreeMap::new(),
diagnostics: Vec::new(),
ambiguous_reported: BTreeSet::new(),
unknown_reported: BTreeSet::new(),
}
}
fn read_name(&mut self, name: &str, span: Span, state: &State) {
if state.must.contains(name) {
return;
}
if state.ambiguous.contains(name) {
if !self.ambiguous_reported.contains(name) {
self.ambiguous_reported.insert(name.to_string());
self.diagnostics.push(
Diagnostic::error(
codes::SYMBOL_UNINITIALIZED,
Some(span),
format!("`{name}` may be read before it is assigned"),
)
.with_hint(
"assign it on every path before this read, or pass it in as a parameter",
),
);
}
return;
}
if let Some(known) = self.known {
if known.contains(name) {
return;
}
if !self.unknown_reported.contains(name) {
self.unknown_reported.insert(name.to_string());
self.diagnostics.push(
Diagnostic::error(
codes::SYMBOL_UNKNOWN,
Some(span),
format!("unknown variable `{name}`"),
)
.with_hint("declare it in the explicit signature or assign it first"),
);
}
return;
}
self.reads.entry(name.to_string()).or_insert(span);
}
fn read_expr(&mut self, expr: &Expr, state: &State) {
match expr {
Expr::Int(_) | Expr::Float(_) | Expr::Text(_) | Expr::Bool(_) | Expr::None => {}
Expr::Ident(Ident { name, span }) => self.read_name(name, *span, state),
Expr::List(items) => {
for item in items {
self.read_expr(item, state);
}
}
Expr::Record(entries) => {
for RecordEntry { value, .. } in entries {
self.read_expr(value, state);
}
}
Expr::Unary { operand, .. } => self.read_expr(operand, state),
Expr::Binary { left, right, .. } => {
self.read_expr(left, state);
self.read_expr(right, state);
}
Expr::Call { callee, args, .. } => {
// A bare identifier callee names a function, not a variable.
match callee.as_ref() {
Expr::Ident(_) => {}
other => self.read_expr(other, state),
}
for Arg { value, .. } in args {
self.read_expr(value, state);
}
}
Expr::Member { base, .. } => self.read_expr(base, state),
Expr::Index { base, index, .. } => {
self.read_expr(base, state);
self.read_expr(index, state);
}
}
}
fn assign(&self, name: &str, state: &mut State) {
state.must.insert(name.to_string());
state.may.insert(name.to_string());
state.ambiguous.insert(name.to_string());
}
fn analyze_stmts(&mut self, stmts: &[Stmt], mut state: State) -> State {
for stmt in stmts {
state = match stmt {
Stmt::Assign { name, value, .. } => {
self.read_expr(value, &state);
self.assign(name, &mut state);
state
}
Stmt::Eval { expr, .. } => {
self.read_expr(expr, &state);
state
}
Stmt::Call { call, .. } => {
for Arg { value, .. } in &call.args {
self.read_expr(value, &state);
}
state
}
Stmt::Return { value, .. } => {
self.read_expr(value, &state);
state
}
Stmt::Branch { arms, .. } => self.analyze_branch(arms, state),
Stmt::Loop {
condition, body, ..
} => {
self.read_expr(condition, &state);
// First iteration starts from the pre-loop state: body
// assignments must not flag pre-loop reads as ambiguous.
let body_out = self.analyze_stmts(
body,
State {
must: state.must.clone(),
may: state.may.clone(),
ambiguous: state.ambiguous.clone(),
},
);
State {
must: state.must.clone(),
may: body_out
.may
.union(&state.may)
.cloned()
.collect::<BTreeSet<_>>(),
ambiguous: body_out
.ambiguous
.union(&state.ambiguous)
.cloned()
.collect::<BTreeSet<_>>(),
}
}
};
}
state
}
fn analyze_branch(&mut self, arms: &[BranchArm], state: State) -> State {
// Conditions are evaluated in order against the incoming state.
for arm in arms {
self.read_expr(&arm.condition, &state);
}
// The branch may match no arm, so the incoming state joins every arm's
// state; variables assigned only inside an arm stay "may assigned".
let mut joined: Option<State> = Some(State {
must: state.must.clone(),
may: state.may.clone(),
ambiguous: state.ambiguous.clone(),
});
for arm in arms {
let arm_out = self.analyze_stmts(
&arm.body,
State {
must: state.must.clone(),
may: state.may.clone(),
ambiguous: state.ambiguous.clone(),
},
);
joined = Some(match joined {
None => arm_out,
Some(previous) => previous.join(&arm_out),
});
}
match joined {
Some(joined) => joined,
None => state,
}
}
}
/// Infer parameters for a function with no explicit signature.
pub fn infer(
stmts: &[Stmt],
signature: Option<&Signature>,
imports: &BTreeSet<String>,
) -> Inference {
let known = signature.map(|signature| {
let mut names: BTreeSet<String> = signature
.params
.iter()
.map(|param| param.name.clone())
.collect();
names.extend(imports.iter().cloned());
names.extend(
marqdo_ir::builtins::BUILTINS
.iter()
.map(|builtin| builtin.name.to_string()),
);
names
});
let mut analyzer = Analyzer::new(known.as_ref());
analyzer.analyze_stmts(stmts, State::default());
let mut params: Vec<ParamCandidate> = analyzer
.reads
.iter()
.filter(|(name, _)| {
// Builtins and imported aliases are never parameters.
marqdo_ir::builtins::find(name).is_none() && !imports.contains(*name)
})
.map(|(name, span)| ParamCandidate {
name: name.clone(),
span: *span,
})
.collect();
params.sort_by(|a, b| a.name.cmp(&b.name));
Inference {
params,
diagnostics: analyzer.diagnostics,
}
}
#[cfg(test)]
mod tests {
use super::*;
use marqdo_expression::{parse_expression, parse_statement};
fn assign(name: &str, value: &str) -> Stmt {
Stmt::Assign {
name: name.to_string(),
name_span: Span::new(0, 0),
value: parse_expression(value).unwrap(),
span: Span::new(0, 0),
}
}
fn ret(expr: &str) -> Stmt {
Stmt::Return {
value: parse_expression(expr).unwrap(),
span: Span::new(0, 0),
}
}
fn params(stmts: &[Stmt]) -> Vec<String> {
infer(stmts, None, &BTreeSet::new())
.params
.into_iter()
.map(|candidate| candidate.name)
.collect()
}
#[test]
fn infers_free_reads() {
// n * 阶乘(n=n-1)
let call: Expr = parse_expression("n * 阶乘(n=n-1)").unwrap();
let stmts = vec![Stmt::Return {
value: call,
span: Span::new(0, 0),
}];
assert_eq!(params(&stmts), vec!["n".to_string()]);
}
#[test]
fn unconditional_entry_assignment_is_local() {
let stmts = vec![assign("n", "3"), ret("n")];
assert!(params(&stmts).is_empty());
}
#[test]
fn loop_counter_is_parameter() {
let stmts = vec![
Stmt::Loop {
condition: parse_expression("n > 0").unwrap(),
condition_span: Span::new(0, 0),
body: vec![assign("n", "n - 1")],
span: Span::new(0, 0),
},
ret("n"),
];
assert_eq!(params(&stmts), vec!["n".to_string()]);
}
#[test]
fn partial_branch_assignment_is_ambiguous() {
let stmts = vec![
Stmt::Branch {
arms: vec![BranchArm {
condition: parse_expression("true").unwrap(),
condition_span: Span::new(0, 0),
body: vec![assign("x", "1")],
span: Span::new(0, 0),
}],
span: Span::new(0, 0),
},
ret("x"),
];
let inference = infer(&stmts, None, &BTreeSet::new());
assert!(inference.params.is_empty());
assert!(inference
.diagnostics
.iter()
.any(|d| d.code == codes::SYMBOL_UNINITIALIZED));
}
#[test]
fn explicit_signature_reports_unknown_reads() {
let signature = Signature {
params: vec![marqdo_ir::Param {
name: "r".into(),
span: Span::new(0, 0),
type_annotation: None,
default: None,
}],
span: Span::new(0, 0),
diagnostics: Vec::new(),
};
let stmts = vec![ret("r * pi * typo")];
let inference = infer(&stmts, Some(&signature), &BTreeSet::new());
assert!(inference.params.is_empty());
assert!(inference
.diagnostics
.iter()
.any(|d| d.code == codes::SYMBOL_UNKNOWN && d.message.contains("typo")));
}
}
+18
View File
@@ -0,0 +1,18 @@
//! Marqdo frontend: Markdown AST → unit index → executable IR.
//!
//! The frontend is the semantic mapper described by
//! `spec/mapping.md`. It owns heading scopes, executable-role assignment,
//! payload parsing, signature/parameter analysis and static call validation.
//! It never executes user code and never touches the host boundary.
pub mod analyze;
pub mod calls;
pub mod infer;
pub mod map;
pub mod payload;
pub mod resources;
pub mod signature;
pub mod units;
pub use analyze::{analyze_source, AnalysisResult};
pub use units::{build_units, github_slug, FunctionScope, HeadingInfo, UnitIndex};
+503
View File
@@ -0,0 +1,503 @@
//! Semantic mapping: canonical Markdown AST → executable IR.
//!
//! This is the only place where executable roles are assigned. Roles come from
//! node kind plus structural position (see `spec/mapping.md`); payload text is
//! parsed only after the role is known. Invalid executable shapes produce hard
//! diagnostics and never fall back to prose.
use marqdo_expression::{
parse_arguments, parse_expression, parse_statement, Arg, Expr, StatementKind,
};
use marqdo_ir::{CallSite, CallTarget, ImportDecl, Stmt};
use marqdo_markdown::{normalize_name, MarkdownDocument, MdKind, MdNode};
use marqdo_span::Span;
use marqdo_value::{codes, Diagnostic};
use crate::payload::PayloadSegments;
use crate::units::{FunctionScope, UnitIndex};
/// A mapped function body plus diagnostics.
#[derive(Debug, Clone, Default)]
pub struct MappedBody {
/// Executable statements in document order.
pub stmts: Vec<Stmt>,
/// Diagnostics produced while mapping.
pub diagnostics: Vec<Diagnostic>,
}
/// Map one function scope to executable statements.
pub fn map_function(
doc: &MarkdownDocument,
index: &UnitIndex,
imports: &[ImportDecl],
scope: &FunctionScope,
) -> MappedBody {
let mut mapper = Mapper {
index,
imports,
diagnostics: Vec::new(),
};
let blocks = &doc.root.children[scope.body_start..scope.body_end];
let stmts = mapper.blocks(blocks);
MappedBody {
stmts,
diagnostics: mapper.diagnostics,
}
}
struct Mapper<'a> {
index: &'a UnitIndex,
#[allow(dead_code)]
imports: &'a [ImportDecl],
diagnostics: Vec<Diagnostic>,
}
impl<'a> Mapper<'a> {
fn error(&mut self, code: &str, span: Option<Span>, message: impl Into<String>) {
self.diagnostics
.push(Diagnostic::error(code, span, message));
}
fn error_with_hint(
&mut self,
code: &str,
span: Option<Span>,
message: impl Into<String>,
hint: impl Into<String>,
) {
self.diagnostics
.push(Diagnostic::error(code, span, message).with_hint(hint));
}
fn blocks(&mut self, blocks: &[MdNode]) -> Vec<Stmt> {
let mut stmts = Vec::new();
for block in blocks {
stmts.extend(self.block(block));
}
stmts
}
fn block(&mut self, block: &MdNode) -> Vec<Stmt> {
match &block.kind {
MdKind::Paragraph => self.paragraph(block),
MdKind::List { ordered, .. } => self.list(block, *ordered),
MdKind::BlockQuote => self.quote(block),
// Level>=3 headings and inert document values stay out of the IR.
_ => Vec::new(),
}
}
fn paragraph(&mut self, paragraph: &MdNode) -> Vec<Stmt> {
let mut stmts = Vec::new();
for child in &paragraph.children {
match &child.kind {
MdKind::Strong => {
if let Some(stmt) = self.exec_statement(child) {
stmts.push(stmt);
}
}
MdKind::Emph => {
if let Some(stmt) = self.return_statement(child) {
stmts.push(stmt);
}
}
// Lazy/inert inline structures: never recurse into them.
MdKind::Link { .. }
| MdKind::Image { .. }
| MdKind::Strikethrough
| MdKind::Code { .. }
| MdKind::Math { .. }
| MdKind::Text
| MdKind::SoftBreak
| MdKind::LineBreak
| MdKind::HtmlInline
| MdKind::FootnoteReference { .. } => {}
_ => {}
}
}
stmts
}
fn exec_statement(&mut self, node: &MdNode) -> Option<Stmt> {
let (payload, segments) = match PayloadSegments::of(node) {
Ok(result) => result,
Err(error) => {
self.error_with_hint(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(error.span),
error.reason,
"keep the executable payload as plain text or a single code span",
);
return None;
}
};
if payload.trim().is_empty() {
self.error(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(node.span),
"execution statement has an empty payload",
);
return None;
}
match parse_statement(&payload) {
Ok(mut statement) => {
segments.rewrite_statement(&mut statement);
Some(match statement.kind {
StatementKind::Assign {
name,
name_span,
value,
} => Stmt::Assign {
name,
name_span,
value,
span: node.span,
},
StatementKind::Expr(expr) => Stmt::Eval {
expr,
span: node.span,
},
})
}
Err(error) => {
self.error_with_hint(
codes::EXPR_PARSE,
Some(segments.map_span(error.span)),
format!("invalid execution statement: {}", error.message),
"statements are `name = expression` or an expression; put the payload in a code span when Markdown emphasis conflicts",
);
None
}
}
}
fn return_statement(&mut self, node: &MdNode) -> Option<Stmt> {
let (payload, segments) = match PayloadSegments::of(node) {
Ok(result) => result,
Err(error) => {
self.error_with_hint(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(error.span),
error.reason,
"a return payload must be plain text or a single code span",
);
return None;
}
};
if payload.trim().is_empty() {
self.error(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(node.span),
"return statement has an empty payload",
);
return None;
}
match parse_expression(&payload) {
Ok(mut expr) => {
segments.rewrite_expr(&mut expr);
Some(Stmt::Return {
value: expr,
span: node.span,
})
}
Err(error) => {
self.error_with_hint(
codes::EXPR_PARSE,
Some(segments.map_span(error.span)),
format!("invalid return expression: {}", error.message),
"`*表达式*` returns the value of the expression",
);
None
}
}
}
fn list(&mut self, list: &MdNode, ordered: bool) -> Vec<Stmt> {
if list.children.is_empty() {
self.error(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(list.span),
"list in an executable position has no items",
);
return Vec::new();
}
let mut arms = Vec::new();
let mut loops = Vec::new();
for item in &list.children {
let Some((condition, condition_span, body_blocks)) = self.condition_of(item) else {
continue;
};
let body = self.blocks(body_blocks);
if ordered {
arms.push(marqdo_ir::BranchArm {
condition,
condition_span,
body,
span: item.span,
});
} else {
loops.push(Stmt::Loop {
condition,
condition_span,
body,
span: item.span,
});
}
}
if ordered {
if arms.is_empty() {
return Vec::new();
}
vec![Stmt::Branch {
arms,
span: list.span,
}]
} else {
loops
}
}
/// Extract the condition header of a list item and its remaining blocks.
fn condition_of<'b>(&mut self, item: &'b MdNode) -> Option<(Expr, Span, &'b [MdNode])> {
let Some(first) = item.children.first() else {
self.error_with_hint(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(item.span),
"list item in an executable position must start with a condition code span",
"write the condition first: `` `n > 0` ``",
);
return None;
};
if !matches!(first.kind, MdKind::Paragraph) {
self.error_with_hint(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(first.span),
"list item must start with a paragraph containing the condition code span",
"put the condition on the first line of the item",
);
return None;
}
let Some(condition_node) = first.children.first() else {
self.error(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(first.span),
"list item paragraph is empty; a condition code span is required",
);
return None;
};
if !matches!(condition_node.kind, MdKind::Code { .. }) {
self.error_with_hint(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(condition_node.span),
"list item must start with a condition inside an inline code span",
"the condition is a `Code` span: `` `n > 0` ``; other text is description",
);
return None;
}
let literal = condition_node.literal.clone().unwrap_or_default();
let segments = PayloadSegments::single(&literal, condition_node.span);
match parse_expression(&literal) {
Ok(mut expr) => {
segments.rewrite_expr(&mut expr);
Some((expr, condition_node.span, &item.children[1..]))
}
Err(error) => {
self.error_with_hint(
codes::EXPR_PARSE,
Some(segments.map_span(error.span)),
format!("invalid condition expression: {}", error.message),
"conditions are Boolean expressions, e.g. `n > 0`",
);
None
}
}
}
fn quote(&mut self, quote: &MdNode) -> Vec<Stmt> {
if quote.children.len() != 1 || quote.children[0].kind != MdKind::Paragraph {
self.error_with_hint(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(quote.span),
"a block quote invocation must contain exactly one paragraph",
"use one block quote per call; prose belongs in normal paragraphs",
);
return Vec::new();
}
let paragraph = &quote.children[0];
self.call_paragraph(quote, paragraph)
}
fn call_paragraph(&mut self, quote: &MdNode, paragraph: &MdNode) -> Vec<Stmt> {
let first = paragraph.children.first();
let is_link_form = first
.map(|node| matches!(node.kind, MdKind::Link { .. }))
.unwrap_or(false);
if is_link_form {
return self.link_call(quote, paragraph);
}
let (payload, segments) = match PayloadSegments::of(paragraph) {
Ok(result) => result,
Err(error) => {
self.error_with_hint(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(error.span),
error.reason,
"a block quote call payload must be plain text or one code span",
);
return Vec::new();
}
};
if payload.trim().is_empty() {
self.error(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(quote.span),
"block quote invocation has an empty payload",
);
return Vec::new();
}
match parse_expression(&payload) {
Ok(mut expr) => {
segments.rewrite_expr(&mut expr);
if !matches!(expr, Expr::Call { .. }) {
self.error_with_hint(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(segments.map_span(expr_span(&expr))),
"a block quote must be a complete function call",
"write `> 函数(参数)`; use a `**strong**` statement to bind a result",
);
return Vec::new();
}
vec![Stmt::Eval {
expr,
span: quote.span,
}]
}
Err(error) => {
self.error_with_hint(
codes::EXPR_PARSE,
Some(segments.map_span(error.span)),
format!("invalid call expression: {}", error.message),
"block quotes call functions explicitly: `> 函数(参数)`",
);
Vec::new()
}
}
}
fn link_call(&mut self, quote: &MdNode, paragraph: &MdNode) -> Vec<Stmt> {
let link = &paragraph.children[0];
let (url, link_span) = match &link.kind {
MdKind::Link { url, .. } => (url.clone(), link.span),
_ => unreachable!("link form checked by caller"),
};
let target = self.resolve_link_target(&url, link_span);
let rest = &paragraph.children[1..];
let (suffix, segments) = match PayloadSegments::from_children(rest) {
Ok(result) => result,
Err(error) => {
self.error_with_hint(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(error.span),
error.reason,
"link call arguments must follow the link as plain text or code spans",
);
return Vec::new();
}
};
if suffix.trim().is_empty() {
self.error_with_hint(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(quote.span),
"link-form call requires an explicit argument list",
"write `> [函数](#函数)()` even for zero arguments",
);
return Vec::new();
}
let mut args: Vec<Arg> = match parse_arguments(&suffix) {
Ok(args) => args,
Err(error) => {
self.error_with_hint(
codes::EXPR_PARSE,
Some(segments.map_span(error.span)),
format!("invalid call arguments: {}", error.message),
"arguments are `name = value` or positional values",
);
return Vec::new();
}
};
segments.rewrite_args(&mut args);
let Some(target) = target else {
return Vec::new();
};
vec![Stmt::Call {
call: CallSite {
target,
args,
span: quote.span,
},
span: quote.span,
}]
}
fn resolve_link_target(&mut self, url: &str, span: Span) -> Option<CallTarget> {
if let Some(fragment) = url.strip_prefix('#') {
let unit_id = self.index.anchors.get(fragment).cloned().or_else(|| {
self.index
.units
.iter()
.find(|unit| unit.name == fragment)
.map(|unit| unit.id.clone())
});
let Some(unit_id) = unit_id else {
self.error(
codes::REF_UNRESOLVED,
Some(span),
format!("no heading matches call target `{url}`"),
);
return None;
};
let Some(scope) = self
.index
.functions
.iter()
.find(|scope| scope.unit == unit_id)
else {
self.error(
codes::REF_UNRESOLVED,
Some(span),
format!("call target `{url}` is not a function"),
);
return None;
};
Some(CallTarget::Resolved {
module: unit_id.module.clone(),
function: scope.id.name.clone(),
})
} else if url.starts_with("http://") || url.starts_with("https://") {
self.error_with_hint(
codes::MATH_UNSUPPORTED,
Some(span),
"external links cannot be called",
"link targets used as calls must resolve to a Marqdo function",
);
None
} else {
self.error_with_hint(
codes::MODULE_UNRESOLVED,
Some(span),
format!("cannot resolve cross-module call target `{url}`"),
"import the module explicitly in front matter and call it through the alias",
);
None
}
}
}
fn expr_span(expr: &Expr) -> Span {
marqdo_expression::Expr::span(expr)
}
/// Normalise a heading name (re-exported for callers that resolve link targets).
pub fn normalized_heading_name(node: &MdNode) -> Option<String> {
normalize_name(&marqdo_markdown::plain_text(node))
}
+261
View File
@@ -0,0 +1,261 @@
//! Executable 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
//! string, so its spans are payload-relative; this module maps them back to the
//! original file so diagnostics point at real source.
use marqdo_expression::{Arg, Expr, RecordEntry, Statement, StatementKind};
use marqdo_markdown::{MdKind, MdNode, PayloadError};
use marqdo_span::Span;
/// One contiguous payload segment and where it came from in the file.
#[derive(Debug, Clone, PartialEq, Eq)]
struct Segment {
payload_start: usize,
payload_end: usize,
file: Span,
}
/// Map from concatenated payload offsets back to original file spans.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct PayloadSegments {
segments: Vec<Segment>,
payload_len: usize,
}
impl PayloadSegments {
/// Build the payload string and its span map for an executable node.
///
/// The strict shape rules are identical to
/// [`marqdo_markdown::executable_payload`]: only `text` and `code` children
/// are allowed, everything else is a hard error.
pub fn of(node: &MdNode) -> Result<(String, PayloadSegments), PayloadError> {
Self::from_children(&node.children)
}
/// Build a payload from an arbitrary child slice (used for call suffixes).
pub fn from_children(children: &[MdNode]) -> Result<(String, PayloadSegments), PayloadError> {
let mut payload = String::new();
let mut segments = Vec::new();
for child in children {
let literal = match &child.kind {
MdKind::Text => child.literal.as_deref().unwrap_or_default(),
MdKind::Code { ticks } => {
// A code span's source span includes its backtick
// delimiters; the payload is only the literal inside.
let literal = child.literal.as_deref().unwrap_or_default();
let start = payload.len();
payload.push_str(literal);
let file = Span::new(
child.span.start.saturating_add(*ticks),
child.span.end.saturating_sub(*ticks),
);
segments.push(Segment {
payload_start: start,
payload_end: payload.len(),
file,
});
continue;
}
other => {
return Err(PayloadError {
span: child.span,
reason: format!(
"`{}` is not a valid payload inside an executable node",
other.tag()
),
});
}
};
let start = payload.len();
payload.push_str(literal);
segments.push(Segment {
payload_start: start,
payload_end: payload.len(),
file: child.span,
});
}
let payload_len = payload.len();
Ok((
payload,
PayloadSegments {
segments,
payload_len,
},
))
}
/// Build a single-segment payload map for one literal code span.
pub fn single(literal: &str, file: Span) -> PayloadSegments {
PayloadSegments {
segments: vec![Segment {
payload_start: 0,
payload_end: literal.len(),
file,
}],
payload_len: literal.len(),
}
}
/// Payload length in bytes.
pub fn len(&self) -> usize {
self.payload_len
}
/// Whether the payload is empty.
pub fn is_empty(&self) -> bool {
self.payload_len == 0
}
/// Map a payload byte offset to a file byte offset.
///
/// A boundary offset belongs to the *next* segment so that a span starting
/// exactly at a code-span boundary maps to the first byte inside the code
/// span, not to its backtick delimiter.
pub fn map_offset(&self, offset: usize) -> usize {
let offset = offset.min(self.payload_len);
for segment in &self.segments {
if segment.payload_start <= offset && offset < segment.payload_end {
let local = offset - segment.payload_start;
return (segment.file.start + local).min(segment.file.end);
}
}
self.segments
.last()
.map(|segment| segment.file.end)
.unwrap_or(0)
}
/// Map a payload span to a file span.
pub fn map_span(&self, span: Span) -> Span {
Span::new(self.map_offset(span.start), self.map_offset(span.end))
}
/// Map and rewrite every span in an expression tree.
pub fn rewrite_expr(&self, expr: &mut Expr) {
rewrite_expr_spans(expr, self);
}
/// Map and rewrite every span in a parsed statement.
pub fn rewrite_statement(&self, statement: &mut Statement) {
statement.span = self.map_span(statement.span);
if let StatementKind::Assign {
name_span, value, ..
} = &mut statement.kind
{
*name_span = self.map_span(*name_span);
self.rewrite_expr(value);
}
if let StatementKind::Expr(expr) = &mut statement.kind {
self.rewrite_expr(expr);
}
}
/// Map and rewrite every span in a call argument list.
pub fn rewrite_args(&self, args: &mut [Arg]) {
for arg in args {
arg.span = self.map_span(arg.span);
self.rewrite_expr(&mut arg.value);
}
}
}
fn rewrite_expr_spans(expr: &mut Expr, segments: &PayloadSegments) {
match expr {
Expr::Int(_) | Expr::Float(_) | Expr::Text(_) | Expr::Bool(_) | Expr::None => {}
Expr::Ident(ident) => ident.span = segments.map_span(ident.span),
Expr::List(items) => {
for item in items {
rewrite_expr_spans(item, segments);
}
}
Expr::Record(entries) => {
for entry in entries {
entry.key_span = segments.map_span(entry.key_span);
rewrite_expr_spans(&mut entry.value, segments);
}
}
Expr::Unary { operand, span, .. } => {
*span = segments.map_span(*span);
rewrite_expr_spans(operand, segments);
}
Expr::Binary {
left, right, span, ..
} => {
*span = segments.map_span(*span);
rewrite_expr_spans(left, segments);
rewrite_expr_spans(right, segments);
}
Expr::Call { callee, args, span } => {
*span = segments.map_span(*span);
rewrite_expr_spans(callee, segments);
for arg in args {
arg.span = segments.map_span(arg.span);
rewrite_expr_spans(&mut arg.value, segments);
}
}
Expr::Member { base, span, .. } => {
*span = segments.map_span(*span);
rewrite_expr_spans(base, segments);
}
Expr::Index {
base, index, span, ..
} => {
*span = segments.map_span(*span);
rewrite_expr_spans(base, segments);
rewrite_expr_spans(index, segments);
}
}
}
/// Record entry is re-exported for completeness of the walker contract.
pub type _RecordEntry = RecordEntry;
#[cfg(test)]
mod tests {
use super::*;
use marqdo_markdown::parse;
fn first_strong(source: &str) -> MdNode {
let doc = parse(source);
let mut found = None;
doc.root.walk(&mut |node| {
if found.is_none() && node.kind == MdKind::Strong {
found = Some(node.clone());
}
});
found.expect("strong node")
}
#[test]
fn payload_and_spans_are_preserved() {
let source = "正文 **结果 = 1 + 2** 结尾";
let node = first_strong(source);
let (payload, segments) = PayloadSegments::of(&node).unwrap();
assert_eq!(payload, "结果 = 1 + 2");
let span = segments.map_span(Span::new(0, 6));
assert_eq!(&source[span.start..span.end], "结果");
// "1" starts after "结果 = " (9 bytes).
let one = segments.map_span(Span::new(9, 10));
assert_eq!(&source[one.start..one.end], "1");
}
#[test]
fn span_maps_across_text_and_code_segments() {
let source = "**面积 = `计算(r=1)`**";
let node = first_strong(source);
let (payload, segments) = PayloadSegments::of(&node).unwrap();
assert_eq!(payload, "面积 = 计算(r=1)");
let start = payload.find("计算").unwrap();
let call = segments.map_span(Span::new(start, start + "计算".len()));
assert_eq!(&source[call.start..call.end], "计算");
}
#[test]
fn nested_markup_is_a_hard_error() {
let node = first_strong("**a *b* c**");
let error = PayloadSegments::of(&node).unwrap_err();
assert!(error.reason.contains("emph"));
}
}
+147
View File
@@ -0,0 +1,147 @@
//! Collection of inert document resources (formulas, code fences) and their
//! owning units.
//!
//! A resource is addressable through its enclosing heading range; it is never
//! executed by reading or rendering the document. Multiple resources in one
//! unit are all kept (blueprint S-07: never silently pick the first one).
use sha2::{Digest, Sha256};
use marqdo_ir::{ModuleId, Resource, UnitId};
use marqdo_markdown::{MarkdownDocument, MdKind, MdNode};
use marqdo_span::Span;
use crate::units::UnitIndex;
/// Collect formulas and code fences with their innermost owning unit.
pub fn collect(doc: &MarkdownDocument, index: &UnitIndex, _module: &ModuleId) -> Vec<Resource> {
let mut resources = Vec::new();
let ranges = unit_ranges(doc, index);
visit(&doc.root, &ranges, &mut resources);
resources
}
/// Range of each unit, used to attribute resources to the innermost unit.
fn unit_ranges(doc: &MarkdownDocument, index: &UnitIndex) -> Vec<(UnitId, Span)> {
let mut ranges = Vec::with_capacity(index.units.len());
let total = doc.source.len();
for (position, unit) in index.units.iter().enumerate() {
let start = unit.span.start;
let end = if unit.level == 0 {
total
} else {
// The unit's range ends at the next heading at the same or a
// shallower level, or at the end of the document.
index
.units
.iter()
.skip(position + 1)
.find(|candidate| candidate.level != 0 && candidate.level <= unit.level)
.map(|candidate| candidate.span.start)
.unwrap_or(total)
};
ranges.push((unit.id.clone(), Span::new(start, end.max(start))));
}
ranges
}
fn visit(node: &MdNode, ranges: &[(UnitId, Span)], out: &mut Vec<Resource>) {
match &node.kind {
MdKind::Math { display } => {
if let Some(unit) = innermost_unit(node.span, ranges) {
out.push(Resource::Formula {
unit,
latex: node.literal.clone().unwrap_or_default(),
display: *display,
span: node.span,
});
}
}
MdKind::MathBlock => {
if let Some(unit) = innermost_unit(node.span, ranges) {
out.push(Resource::Formula {
unit,
latex: node.literal.clone().unwrap_or_default(),
display: true,
span: node.span,
});
}
}
MdKind::CodeBlock { info, .. } => {
if let Some(unit) = innermost_unit(node.span, ranges) {
let source = node.literal.clone().unwrap_or_default();
out.push(Resource::Code {
unit,
language: info.split_whitespace().next().unwrap_or("").to_string(),
content_hash: content_hash(&source),
source,
span: node.span,
});
}
}
_ => {}
}
for child in &node.children {
visit(child, ranges, out);
}
}
fn innermost_unit(span: Span, ranges: &[(UnitId, Span)]) -> Option<UnitId> {
ranges
.iter()
.filter(|(_, range)| range.start <= span.start && span.end <= range.end)
.max_by_key(|(unit, range)| (unit.path.len(), range.start))
.map(|(unit, _)| unit.clone())
}
/// SHA-256 of code source, stored on `Code` values so that artifacts can be
/// checked for content drift.
pub fn content_hash(source: &str) -> String {
let digest = Sha256::digest(source.as_bytes());
let mut hex = String::with_capacity(64);
for byte in digest {
hex.push_str(&format!("{byte:02x}"));
}
hex
}
#[cfg(test)]
mod tests {
use super::*;
use crate::units::build_units;
use marqdo_markdown::parse;
fn resources_of(source: &str) -> Vec<Resource> {
let doc = parse(source);
let module = ModuleId::from("index.mq.md");
let index = build_units(&doc, &module);
collect(&doc, &index, &module)
}
#[test]
fn formulas_and_code_are_attributed_to_functions() {
let resources = resources_of(
"# ns\n\n## f\n\n$$A = pi r^2$$\n\n```python\nprint(1)\n```\n\n## g\n\n$$B = 1$$\n",
);
assert_eq!(resources.len(), 3);
let Resource::Formula { unit, latex, .. } = &resources[0] else {
panic!("expected formula");
};
assert_eq!(latex, "A = pi r^2");
assert!(unit.to_string().ends_with("f"));
let Resource::Code { language, .. } = &resources[1] else {
panic!("expected code");
};
assert_eq!(language, "python");
let Resource::Formula { unit, .. } = &resources[2] else {
panic!("expected formula");
};
assert!(unit.to_string().ends_with("g"));
}
#[test]
fn content_hash_is_stable() {
assert_eq!(content_hash("print(1)\n").len(), 64);
assert_ne!(content_hash("a"), content_hash("b"));
}
}
+332
View File
@@ -0,0 +1,332 @@
//! 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.
use marqdo_expression::{parse_expression, Expr, Statement, StatementKind};
use marqdo_ir::{Param, SignatureKind};
use marqdo_markdown::{MarkdownDocument, MdKind, MdNode};
use marqdo_span::Span;
use marqdo_value::{codes, Diagnostic};
use unicode_ident::{is_xid_continue, is_xid_start};
use crate::payload::PayloadSegments;
/// Parsed signature declaration.
#[derive(Debug, Clone, PartialEq)]
pub struct Signature {
/// Parameters in declaration order.
pub params: Vec<Param>,
/// Span of the declaration code span.
pub span: Span,
/// Diagnostics raised while parsing the declaration.
pub diagnostics: Vec<Diagnostic>,
}
impl Signature {
/// Whether the declaration had errors.
pub fn has_errors(&self) -> bool {
self.diagnostics.iter().any(Diagnostic::is_error)
}
}
/// Detect and parse a signature paragraph.
///
/// A paragraph qualifies only when it is the first block in the function body
/// (ignoring inert level>=3 section headings) and consists of exactly one
/// inline code span whose payload starts with `(`. Any other first paragraph is
/// prose and inference is used instead.
pub fn detect(_doc: &MarkdownDocument, blocks: &[&MdNode]) -> Option<(usize, Signature)> {
for (index, block) in blocks.iter().enumerate() {
match &block.kind {
MdKind::Heading { level, .. } if *level >= 3 => continue,
MdKind::Paragraph => {
let is_candidate = block.children.len() == 1
&& matches!(block.children[0].kind, MdKind::Code { .. })
&& block.children[0]
.literal
.as_deref()
.map(|text| text.trim_start().starts_with('('))
.unwrap_or(false);
if !is_candidate {
return None;
}
let code = &block.children[0];
let source = code.literal.clone().unwrap_or_default();
let mut signature = parse(&source, code.span);
// Rewrite parameter default expression spans onto the file.
let segments = PayloadSegments::of(&MdNode {
kind: MdKind::Strong,
span: code.span,
literal: None,
children: vec![code.clone()],
})
.ok()
.map(|(_, segments)| segments);
if let Some(segments) = segments {
for param in &mut signature.params {
if let Some(default) = &mut param.default {
segments.rewrite_expr(default);
}
}
}
return Some((index, signature));
}
_ => return None,
}
}
None
}
/// Parse signature payload text (without the code span delimiters).
pub fn parse(source: &str, span: Span) -> Signature {
let mut diagnostics = Vec::new();
let trimmed = source.trim();
let inner = if let Some(rest) = trimmed.strip_prefix('(') {
rest.strip_suffix(')').unwrap_or(rest)
} else {
diagnostics.push(Diagnostic::error(
codes::EXPR_PARSE,
Some(span),
"function signature must be parenthesised, e.g. `(r: Number)`",
));
trimmed
};
let mut params: Vec<Param> = Vec::new();
let mut seen: Vec<String> = Vec::new();
let mut cursor = 0usize;
for (entry_start, entry_end) in split_top_level(inner, ',') {
let entry = &inner[entry_start..entry_end];
if entry.trim().is_empty() {
if !inner.trim().is_empty() {
diagnostics.push(Diagnostic::error(
codes::EXPR_PARSE,
Some(span),
"empty parameter in function signature",
));
}
cursor = entry_end;
continue;
}
let entry_offset = source.find(entry).unwrap_or(0);
match parse_entry(entry, span) {
Ok(mut param) => {
param.span = Span::new(
span.start + entry_offset.min(span.len()),
span.start + (entry_offset + entry.len()).min(span.len()),
);
if seen.contains(&param.name) {
diagnostics.push(Diagnostic::error(
codes::EXPR_PARSE,
Some(param.span),
format!("duplicate parameter `{}`", param.name),
));
} else {
seen.push(param.name.clone());
params.push(param);
}
}
Err(message) => diagnostics.push(Diagnostic::error(
codes::EXPR_PARSE,
Some(span),
format!("invalid function signature: {message}"),
)),
}
cursor = entry_end;
}
let _ = cursor;
Signature {
params,
span,
diagnostics,
}
}
fn parse_entry(entry: &str, span: Span) -> Result<Param, String> {
let entry = entry.trim();
// Find `=` at top level (not part of `==`).
let equals = find_top_level(entry, '=');
let (lhs, default) = match equals {
Some(index)
if !entry[index + 1..].starts_with('=')
&& (index == 0 || entry.as_bytes()[index - 1] != b'=') =>
{
let default_text = entry[index + 1..].trim();
if default_text.is_empty() {
return Err("default value expression is empty".to_string());
}
let expr = parse_expression(default_text)
.map_err(|error| format!("invalid default value: {}", error.message))?;
if !is_const_expr(&expr) {
return Err("default values must be compile-time constants".to_string());
}
(&entry[..index], Some(expr))
}
_ => (entry, None),
};
let colon = find_top_level(lhs, ':');
let (name_text, type_annotation) = match colon {
Some(index) => (
lhs[..index].trim(),
Some(lhs[index + 1..].trim().to_string()),
),
None => (lhs.trim(), None),
};
if let Some(annotation) = &type_annotation {
if annotation.is_empty() {
return Err("type annotation is empty".to_string());
}
}
validate_ident(name_text)?;
Ok(Param {
name: name_text.to_string(),
// Refined by the caller with the exact source span.
span,
type_annotation,
default,
})
}
fn validate_ident(name: &str) -> Result<(), String> {
let mut chars = name.chars();
let Some(first) = chars.next() else {
return Err("parameter name is empty".to_string());
};
if !(first == '_' || is_xid_start(first)) {
return Err(format!("`{name}` is not a valid parameter name"));
}
for ch in chars {
if !(ch == '_' || is_xid_continue(ch)) {
return Err(format!("`{name}` is not a valid parameter name"));
}
}
Ok(())
}
/// Compile-time constant check for signature defaults.
fn is_const_expr(expr: &Expr) -> bool {
match expr {
Expr::Int(_) | Expr::Float(_) | Expr::Text(_) | Expr::Bool(_) | Expr::None => true,
Expr::Unary { operand, .. } => is_const_expr(operand),
Expr::List(items) => items.iter().all(is_const_expr),
Expr::Record(entries) => entries.iter().all(|entry| is_const_expr(&entry.value)),
_ => false,
}
}
/// Split `text` on a separator at bracket/string depth zero, returning byte
/// ranges (without the separator).
fn split_top_level(text: &str, separator: char) -> Vec<(usize, usize)> {
let mut ranges = Vec::new();
let mut depth = 0i32;
let mut in_string = false;
let mut escaped = false;
let mut start = 0usize;
for (index, ch) in text.char_indices() {
if in_string {
if escaped {
escaped = false;
} else if ch == '\\' {
escaped = true;
} else if ch == '"' {
in_string = false;
}
continue;
}
match ch {
'"' => in_string = true,
'(' | '[' | '{' => depth += 1,
')' | ']' | '}' => depth -= 1,
c if c == separator && depth == 0 => {
ranges.push((start, index));
start = index + ch.len_utf8();
}
_ => {}
}
}
ranges.push((start, text.len()));
ranges
}
fn find_top_level(text: &str, needle: char) -> Option<usize> {
let mut depth = 0i32;
let mut in_string = false;
let mut escaped = false;
for (index, ch) in text.char_indices() {
if in_string {
if escaped {
escaped = false;
} else if ch == '\\' {
escaped = true;
} else if ch == '"' {
in_string = false;
}
continue;
}
match ch {
'"' => in_string = true,
'(' | '[' | '{' => depth += 1,
')' | ']' | '}' => depth -= 1,
c if c == needle && depth == 0 => return Some(index),
_ => {}
}
}
None
}
/// Build a statement-less const check helper used by the mapper for defaults.
pub fn const_default_ok(statement: &Statement) -> bool {
match &statement.kind {
StatementKind::Assign { value, .. } => is_const_expr(value),
StatementKind::Expr(expr) => is_const_expr(expr),
}
}
/// Convenience: parameter kind for functions with a signature.
pub const KIND: SignatureKind = SignatureKind::Explicit;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_typed_signature_with_default() {
let signature = parse("(r: Number, precision: Int = 2)", Span::new(0, 38));
assert!(!signature.has_errors(), "{:?}", signature.diagnostics);
assert_eq!(signature.params.len(), 2);
assert_eq!(signature.params[0].name, "r");
assert_eq!(
signature.params[0].type_annotation.as_deref(),
Some("Number")
);
assert_eq!(signature.params[1].name, "precision");
assert!(signature.params[1].default.is_some());
}
#[test]
fn parses_untyped_and_empty() {
let signature = parse("()", Span::new(0, 2));
assert!(signature.params.is_empty());
assert!(!signature.has_errors());
let signature = parse("(n)", Span::new(0, 3));
assert_eq!(signature.params[0].name, "n");
}
#[test]
fn rejects_duplicates_and_bad_defaults() {
let duplicate = parse("(a, a)", Span::new(0, 6));
assert!(duplicate.has_errors());
let bad_default = parse("(a = f())", Span::new(0, 10));
assert!(bad_default.has_errors());
let bad_name = parse("(1x)", Span::new(0, 4));
assert!(bad_name.has_errors());
}
#[test]
fn split_respects_nesting_and_strings() {
let parts = split_top_level("a, f(b, c), d", ',');
assert_eq!(parts.len(), 3);
}
}
+433
View File
@@ -0,0 +1,433 @@
//! Heading scope index.
//!
//! Markdown headings are sibling blocks, so function 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
//!
//! 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.
use std::collections::BTreeMap;
use marqdo_ir::{FunctionId, ModuleId, UnitId, UnitInfo, UnitKind};
use marqdo_markdown::{normalize_name, plain_text, MarkdownDocument, MdKind};
use marqdo_span::Span;
use marqdo_value::{codes, Diagnostic};
/// A heading that participates in the unit index.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HeadingInfo {
/// Index of the heading in `Document.children`.
pub node_index: usize,
/// Level 1-6.
pub level: u8,
/// Canonical (NFC, whitespace collapsed) heading name.
pub name: String,
/// Heading span.
pub span: Span,
/// Canonical heading path including this heading.
pub path: Vec<String>,
/// Role derived from level and position.
pub kind: UnitKind,
}
/// A function range mapped from a level-2 heading.
#[derive(Debug, Clone, PartialEq)]
pub struct FunctionScope {
/// Canonical function identity (namespace-qualified when namespaced).
pub id: FunctionId,
/// Function name as written inside its namespace.
pub local_name: String,
/// Enclosing level-1 namespace, if any.
pub namespace: Option<String>,
/// Addressable unit defined by this heading.
pub unit: UnitId,
/// Heading span.
pub heading_span: Span,
/// Range of `Document.children` indices forming the function body
/// (`body_start..body_end`), excluding the heading itself.
pub body_start: usize,
/// Exclusive end of the body range.
pub body_end: usize,
/// Span from the heading through the last body block.
pub span: Span,
}
/// Result of indexing a document's headings.
#[derive(Debug, Clone, Default)]
pub struct UnitIndex {
/// Addressable units in document order (root first).
pub units: Vec<UnitInfo>,
/// Headings in document order.
pub headings: Vec<HeadingInfo>,
/// Function ranges in document order.
pub functions: Vec<FunctionScope>,
/// GitHub-style heading anchors mapped to units. Anchors are derived from
/// the rendered heading text and are kept separate from canonical names and
/// internal unit ids.
pub anchors: BTreeMap<String, UnitId>,
/// Diagnostics produced while building the index.
pub diagnostics: Vec<Diagnostic>,
}
impl UnitIndex {
/// Units declared directly under the given parent path.
pub fn children_of<'a>(&'a self, parent: &[String]) -> impl Iterator<Item = &'a UnitInfo> + 'a {
let parent = parent.to_vec();
self.units.iter().filter(move |unit| {
unit.id.path.len() == parent.len() + 1 && unit.id.path.starts_with(&parent)
})
}
/// Function scope whose body range contains the given document child index.
pub fn function_containing_block(&self, block_index: usize) -> Option<&FunctionScope> {
self.functions
.iter()
.find(|f| block_index >= f.body_start && block_index < f.body_end)
}
}
/// Build the heading/function index for a parsed document.
pub fn build_units(doc: &MarkdownDocument, module: &ModuleId) -> UnitIndex {
let mut index = UnitIndex::default();
index.units.push(UnitInfo {
id: UnitId {
module: module.clone(),
path: Vec::new(),
},
level: 0,
name: String::new(),
span: doc.root.span,
kind: UnitKind::Root,
function: None,
});
// Stack of (level, path) for ancestor headings with smaller level.
let mut stack: Vec<(u8, Vec<String>)> = Vec::new();
let mut seen: BTreeMap<(Vec<String>, String), Span> = BTreeMap::new();
let mut current_namespace: Option<String> = None;
let mut current_function: Option<FunctionId> = None;
let mut heading_infos: Vec<HeadingInfo> = Vec::new();
for (node_index, child) in doc.root.children.iter().enumerate() {
let MdKind::Heading { level, .. } = &child.kind else {
continue;
};
let level = *level;
let raw_name = normalize_name(&plain_text(child));
let Some(name) = raw_name else {
index.diagnostics.push(
Diagnostic::error(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(child.span),
"heading name must not be empty",
)
.with_hint("give the heading a non-empty canonical name"),
);
continue;
};
while let Some((parent_level, _)) = stack.last() {
if *parent_level >= level {
stack.pop();
} else {
break;
}
}
let parent_path = stack
.last()
.map(|(_, path)| path.clone())
.unwrap_or_default();
let path = {
let mut path = parent_path.clone();
path.push(name.clone());
path
};
// Duplicate canonical names in the same scope are a hard error; never
// silently rename with -1/-2 suffixes.
let key = (parent_path.clone(), name.clone());
if let Some(previous) = seen.get(&key) {
let previous = *previous;
index.diagnostics.push(
Diagnostic::error(
codes::MARKDOWN_INVALID_CONSTRUCT,
Some(child.span),
format!("duplicate heading name `{name}` in the same scope"),
)
.with_related(Some(previous), "first declared here")
.with_hint("rename one of the headings; duplicate names are not auto-suffixed"),
);
} else {
seen.insert(key, child.span);
}
let kind = match level {
1 => UnitKind::Namespace,
2 => UnitKind::Function,
_ => UnitKind::Section,
};
if level == 1 {
current_namespace = Some(name.clone());
current_function = None;
}
let function = if level == 2 {
let local = name.clone();
let qualified = match &current_namespace {
Some(namespace) => format!("{namespace}.{local}"),
None => local.clone(),
};
let id = FunctionId {
module: module.clone(),
name: qualified,
};
current_function = Some(id.clone());
Some(id)
} else if level >= 3 {
current_function.clone()
} else {
None
};
let info = HeadingInfo {
node_index,
level,
name: name.clone(),
span: child.span,
path: path.clone(),
kind,
};
let unit_id = UnitId {
module: module.clone(),
path,
};
index.units.push(UnitInfo {
id: unit_id,
level,
name: name.clone(),
span: child.span,
kind,
function,
});
heading_infos.push(info.clone());
stack.push((level, info.path.clone()));
}
// Function body ranges and spans.
for heading in heading_infos.iter().filter(|h| h.level == 2) {
let body_start = heading.node_index + 1;
let body_end = doc.root.children[body_start..]
.iter()
.position(|child| match child.kind {
MdKind::Heading { level, .. } => level <= 2,
_ => false,
})
.map(|offset| body_start + offset)
.unwrap_or(doc.root.children.len());
let span = if body_end > body_start {
let mut span = heading.span;
for block in &doc.root.children[body_start..body_end] {
span = span.merge(block.span);
}
span
} else {
heading.span
};
let local_name = heading.name.clone();
let namespace = match heading.path.len() {
0 => None,
_ if heading.path.len() == 1 => None,
_ => Some(heading.path[0].clone()),
};
let namespace = namespace.filter(|_| {
index
.units
.iter()
.any(|unit| unit.kind == UnitKind::Namespace && unit.name == heading.path[0])
});
let qualified = match &namespace {
Some(namespace) => format!("{namespace}.{local_name}"),
None => local_name.clone(),
};
index.functions.push(FunctionScope {
id: FunctionId {
module: module.clone(),
name: qualified,
},
local_name,
namespace,
unit: UnitId {
module: module.clone(),
path: heading.path.clone(),
},
heading_span: heading.span,
body_start,
body_end,
span,
});
}
// Warnings for would-be execution nodes outside every function body.
for (node_index, child) in doc.root.children.iter().enumerate() {
if index.function_containing_block(node_index).is_some() {
continue;
}
let mut warn = |span: Span, what: &str| {
index.diagnostics.push(
Diagnostic::warning(
codes::MARKDOWN_INERT_EXECUTABLE,
Some(span),
format!("{what} outside a function body is inert document content"),
)
.with_hint("move it under a level-2 heading (`## 函数名`) to execute it"),
);
};
match &child.kind {
MdKind::BlockQuote => warn(child.span, "a block quote invocation"),
MdKind::List { .. } => warn(child.span, "a list control structure"),
MdKind::Paragraph => {
let mut found: Option<(Span, &'static str)> = None;
child.walk(&mut |node| {
if found.is_none() {
match node.kind {
MdKind::Strong => found = Some((node.span, "an execution statement")),
MdKind::Emph => found = Some((node.span, "a return statement")),
_ => {}
}
}
});
if let Some((span, what)) = found {
warn(span, what);
}
}
_ => {}
}
}
// Derive GitHub-style anchors for navigation and `ref("#...")`. Anchors are
// not identity: they may collide and receive -1/-2 suffixes exactly like
// GitHub's slugger, while internal ids stay canonical.
let mut slug_counts: BTreeMap<String, usize> = BTreeMap::new();
for unit in &index.units {
if unit.level == 0 {
continue;
}
let base = github_slug(&unit.name);
if base.is_empty() {
continue;
}
let count = slug_counts.entry(base.clone()).or_insert(0);
let slug = if *count == 0 {
base
} else {
format!("{base}-{count}")
};
*count += 1;
index.anchors.insert(slug, unit.id.clone());
}
index.headings = heading_infos;
index
}
/// GitHub-style heading slug, kept in a separate namespace from canonical
/// unit names. Unicode letters/digits survive, spaces become `-`, other
/// punctuation is dropped and text is lowercased.
pub fn github_slug(text: &str) -> String {
let mut slug = String::new();
for ch in text.chars() {
if ch.is_alphanumeric() || ch == '_' {
for lower in ch.to_lowercase() {
slug.push(lower);
}
} else if ch == ' ' || ch == '-' || ch == '\t' {
slug.push('-');
}
}
slug
}
#[cfg(test)]
mod tests {
use super::*;
use marqdo_markdown::parse;
fn index_of(source: &str) -> UnitIndex {
let doc = parse(source);
build_units(&doc, &ModuleId::from("index.mq.md"))
}
#[test]
fn builds_function_ranges() {
let index = index_of(
"# 命名空间\n\n## 阶乘\n\n**x = 1**\n\n### 小节\n\n正文\n\n## 下一个\n\n*y*\n",
);
assert_eq!(index.functions.len(), 2);
assert_eq!(index.functions[0].local_name, "阶乘");
assert_eq!(index.functions[0].namespace.as_deref(), Some("命名空间"));
assert_eq!(index.functions[0].id.name, "命名空间.阶乘");
assert_eq!(index.functions[0].body_start, 2);
// ### section stays inside the factorial function body.
assert!(index.functions[0].body_end > index.functions[0].body_start + 2);
assert_eq!(index.functions[1].local_name, "下一个");
}
#[test]
fn root_level_function_without_namespace() {
let index = index_of("## main\n\n> 打印(1)\n");
assert_eq!(index.functions.len(), 1);
assert_eq!(index.functions[0].id.name, "main");
assert!(index.functions[0].namespace.is_none());
assert!(index.diagnostics.is_empty());
}
#[test]
fn empty_heading_is_an_error() {
let index = index_of("## \n\n正文\n");
assert!(index
.diagnostics
.iter()
.any(|d| d.code == codes::MARKDOWN_INVALID_CONSTRUCT && d.message.contains("empty")));
}
#[test]
fn duplicate_function_names_are_errors() {
let index = index_of("## f\n\n## f\n");
let errors = index
.diagnostics
.iter()
.filter(|d| d.message.contains("duplicate"))
.count();
assert_eq!(errors, 1);
}
#[test]
fn same_name_in_different_namespaces_is_allowed() {
let index = index_of("# a\n\n## f\n\n# b\n\n## f\n");
let duplicates = index
.diagnostics
.iter()
.filter(|d| d.message.contains("duplicate"))
.count();
assert_eq!(duplicates, 0);
assert_eq!(index.functions.len(), 2);
assert_eq!(index.functions[0].id.name, "a.f");
assert_eq!(index.functions[1].id.name, "b.f");
}
#[test]
fn executable_outside_function_warns_but_does_not_execute() {
let index = index_of("**x = 1**\n\n## f\n\n*y*\n");
assert!(index
.diagnostics
.iter()
.any(|d| d.code == codes::MARKDOWN_INERT_EXECUTABLE));
assert_eq!(index.functions.len(), 1);
}
}