diff --git a/crates/marqdo-frontend/Cargo.toml b/crates/marqdo-frontend/Cargo.toml index 4675392..c6c26ba 100644 --- a/crates/marqdo-frontend/Cargo.toml +++ b/crates/marqdo-frontend/Cargo.toml @@ -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 } diff --git a/crates/marqdo-frontend/src/analyze.rs b/crates/marqdo-frontend/src/analyze.rs new file mode 100644 index 0000000..ffbd390 --- /dev/null +++ b/crates/marqdo-frontend/src/analyze.rs @@ -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, +} + +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 = 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 = + imports.iter().map(|import| import.alias.clone()).collect(); + + let mut functions: Vec = 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 = 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)); + } +} diff --git a/crates/marqdo-frontend/src/calls.rs b/crates/marqdo-frontend/src/calls.rs new file mode 100644 index 0000000..8dbd3bd --- /dev/null +++ b/crates/marqdo-frontend/src/calls.rs @@ -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, + /// 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 { + 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 { + let table = signature_table(module); + let mut diagnostics = Vec::new(); + for function in &module.functions { + let mut locals: BTreeSet = 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) { + 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, + locals: &'a BTreeSet, + table: &'a BTreeMap, + imports: BTreeSet, + diagnostics: Vec, +} + +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) -> 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) -> 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)); + } +} diff --git a/crates/marqdo-frontend/src/infer.rs b/crates/marqdo-frontend/src/infer.rs new file mode 100644 index 0000000..5c1c16d --- /dev/null +++ b/crates/marqdo-frontend/src/infer.rs @@ -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, + /// Diagnostics (ambiguity errors, explicit-signature unknown reads). + pub diagnostics: Vec, +} + +/// 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, + may: BTreeSet, + ambiguous: BTreeSet, +} + +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>, + reads: BTreeMap, + diagnostics: Vec, + ambiguous_reported: BTreeSet, + unknown_reported: BTreeSet, +} + +impl<'a> Analyzer<'a> { + fn new(known: Option<&'a BTreeSet>) -> 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::>(), + ambiguous: body_out + .ambiguous + .union(&state.ambiguous) + .cloned() + .collect::>(), + } + } + }; + } + 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 = 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, +) -> Inference { + let known = signature.map(|signature| { + let mut names: BTreeSet = 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 = 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 { + 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"))); + } +} diff --git a/crates/marqdo-frontend/src/lib.rs b/crates/marqdo-frontend/src/lib.rs new file mode 100644 index 0000000..beeeef8 --- /dev/null +++ b/crates/marqdo-frontend/src/lib.rs @@ -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}; diff --git a/crates/marqdo-frontend/src/map.rs b/crates/marqdo-frontend/src/map.rs new file mode 100644 index 0000000..50d2fca --- /dev/null +++ b/crates/marqdo-frontend/src/map.rs @@ -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, + /// Diagnostics produced while mapping. + pub diagnostics: Vec, +} + +/// 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, +} + +impl<'a> Mapper<'a> { + fn error(&mut self, code: &str, span: Option, message: impl Into) { + self.diagnostics + .push(Diagnostic::error(code, span, message)); + } + + fn error_with_hint( + &mut self, + code: &str, + span: Option, + message: impl Into, + hint: impl Into, + ) { + self.diagnostics + .push(Diagnostic::error(code, span, message).with_hint(hint)); + } + + fn blocks(&mut self, blocks: &[MdNode]) -> Vec { + let mut stmts = Vec::new(); + for block in blocks { + stmts.extend(self.block(block)); + } + stmts + } + + fn block(&mut self, block: &MdNode) -> Vec { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 = 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 { + 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 { + normalize_name(&marqdo_markdown::plain_text(node)) +} diff --git a/crates/marqdo-frontend/src/payload.rs b/crates/marqdo-frontend/src/payload.rs new file mode 100644 index 0000000..ca8bd0f --- /dev/null +++ b/crates/marqdo-frontend/src/payload.rs @@ -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, + 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")); + } +} diff --git a/crates/marqdo-frontend/src/resources.rs b/crates/marqdo-frontend/src/resources.rs new file mode 100644 index 0000000..b20c741 --- /dev/null +++ b/crates/marqdo-frontend/src/resources.rs @@ -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 { + 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) { + 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 { + 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 { + 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")); + } +} diff --git a/crates/marqdo-frontend/src/signature.rs b/crates/marqdo-frontend/src/signature.rs new file mode 100644 index 0000000..45a946c --- /dev/null +++ b/crates/marqdo-frontend/src/signature.rs @@ -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, + /// Span of the declaration code span. + pub span: Span, + /// Diagnostics raised while parsing the declaration. + pub diagnostics: Vec, +} + +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 = Vec::new(); + let mut seen: Vec = 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 { + 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 { + 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); + } +} diff --git a/crates/marqdo-frontend/src/units.rs b/crates/marqdo-frontend/src/units.rs new file mode 100644 index 0000000..a3c90d0 --- /dev/null +++ b/crates/marqdo-frontend/src/units.rs @@ -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, + /// 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, + /// 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, + /// Headings in document order. + pub headings: Vec, + /// Function ranges in document order. + pub functions: Vec, + /// 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, + /// Diagnostics produced while building the index. + pub diagnostics: Vec, +} + +impl UnitIndex { + /// Units declared directly under the given parent path. + pub fn children_of<'a>(&'a self, parent: &[String]) -> impl Iterator + '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)> = Vec::new(); + let mut seen: BTreeMap<(Vec, String), Span> = BTreeMap::new(); + let mut current_namespace: Option = None; + let mut current_function: Option = None; + let mut heading_infos: Vec = 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 = 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); + } +}