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:
1 parent
62a9af05fd
commit
8003907f4e
10 files changed
+2763
-3
No files matched your search
@@ -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 }
|
||||
@@ -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));
|
||||
}
|
||||
}
|
||||
@@ -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));
|
||||
}
|
||||
}
|
||||
@@ -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")));
|
||||
}
|
||||
}
|
||||
@@ -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};
|
||||
@@ -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 ¶graph.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 = "e.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 = ¶graph.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 = ¶graph.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))
|
||||
}
|
||||
@@ -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"));
|
||||
}
|
||||
}
|
||||
@@ -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"));
|
||||
}
|
||||
}
|
||||
@@ -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(¶m.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);
|
||||
}
|
||||
}
|
||||
@@ -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 ¤t_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);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user