From 0bbe735c3c969b56a17b34c6ad5e60b1d7e6e99e Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 23 Oct 2026 08:24:10 +0000 Subject: [PATCH] feat: add stable executable knowledge symbols --- src/ast.rs | 66 +++++ src/bytecode/compile.rs | 15 +- src/interp.rs | 2 +- src/lib.rs | 2 + src/main.rs | 152 ++++++++--- src/parse/expr.rs | 29 ++ src/project/mod.rs | 190 +++++++++++++ src/sema/mod.rs | 9 + src/sema/symbols.rs | 378 ++++++++++++++++++++++++++ tests/errors/ns-instance-method.mq.md | 2 +- tests/gold.rs | 14 + tests/structure/ns/associated.mq.md | 14 + tests/structure/ns/helpers.mq.md | 8 + 13 files changed, 841 insertions(+), 40 deletions(-) create mode 100644 src/project/mod.rs create mode 100644 src/sema/mod.rs create mode 100644 src/sema/symbols.rs create mode 100644 tests/structure/ns/associated.mq.md diff --git a/src/ast.rs b/src/ast.rs index 47dbbc2..13d47f9 100644 --- a/src/ast.rs +++ b/src/ast.rs @@ -80,6 +80,72 @@ impl Function { } } +/// Whether this function needs an instance receiver. +/// +/// A direct child of a level-1 object may be an associated function: when its +/// executable body does not read `self` / `自`, it can be invoked through its +/// definition path (`lib.Type.fact`). Child declarations are not traversed; +/// each declaration owns its own receiver requirement. +pub fn function_uses_receiver(fun: &Function) -> bool { + fn is_receiver(name: &str) -> bool { + matches!(name, "self" | "自") + } + + fn expr_uses_receiver(expr: &Expr) -> bool { + match expr { + Expr::Var(name) => is_receiver(name), + Expr::Interp(parts) => parts.iter().any(|part| match part { + InterpPart::Var(name) | InterpPart::Index { base: name, .. } => is_receiver(name), + InterpPart::Lit(_) => false, + }), + Expr::Unary { expr, .. } => expr_uses_receiver(expr), + Expr::Binary { left, right, .. } => { + expr_uses_receiver(left) || expr_uses_receiver(right) + } + Expr::Call(call) => { + call.receiver.as_deref().is_some_and(is_receiver) + || call.args.iter().any(|arg| match arg { + Arg::Positional(value) | Arg::Named { value, .. } => expr_uses_receiver(value), + }) + } + Expr::List(items) => items.iter().any(expr_uses_receiver), + Expr::Map(entries) => entries.iter().any(|(_, value)| expr_uses_receiver(value)), + Expr::Index { base, label } => { + expr_uses_receiver(base) + || matches!(label, IndexKey::Var(name) if is_receiver(name)) + } + Expr::Occluded { payload, .. } => payload.as_deref().is_some_and(expr_uses_receiver), + Expr::Literal(_) | Expr::Formula(_) | Expr::Code(_) => false, + } + } + + fn stmt_uses_receiver(stmt: &Stmt) -> bool { + match stmt { + Stmt::Assign { value, .. } | Stmt::Return { value, .. } | Stmt::Expr { value, .. } => { + expr_uses_receiver(value) + } + Stmt::Call { call, .. } => { + call.receiver.as_deref().is_some_and(is_receiver) + || call.args.iter().any(|arg| match arg { + Arg::Positional(value) | Arg::Named { value, .. } => expr_uses_receiver(value), + }) + } + Stmt::Branch { arms, .. } => arms.iter().any(|arm| { + arm.condition.as_ref().is_some_and(expr_uses_receiver) + || arm.body.iter().any(stmt_uses_receiver) + }), + Stmt::While { condition, body, .. } => { + expr_uses_receiver(condition) || body.iter().any(stmt_uses_receiver) + } + Stmt::ForEach { collection, body, .. } => { + is_receiver(collection) || body.iter().any(stmt_uses_receiver) + } + } + } + + fun.body.iter().any(stmt_uses_receiver) +} + /// Source line of a statement (every variant carries a span). pub fn stmt_line(st: &Stmt) -> u32 { match st { diff --git a/src/bytecode/compile.rs b/src/bytecode/compile.rs index 6463f9b..1885e5e 100644 --- a/src/bytecode/compile.rs +++ b/src/bytecode/compile.rs @@ -14,6 +14,9 @@ use crate::value::Value; struct FlatFun { name: String, level: u8, + /// Receiver-free children of an object are associated functions, not + /// instance methods. This flag is computed from executable AST only. + uses_receiver: bool, parent: Option, /// Inheritance base type name (`# Child = > Parent`), objects only. base: Option, @@ -154,6 +157,7 @@ fn collect_fun( flat.push(FlatFun { name: fun.name.clone(), level: fun.level, + uses_receiver: crate::ast::function_uses_receiver(fun), parent, base: fun.base.clone(), params: fun.params.clone(), @@ -191,10 +195,7 @@ fn compile_function( for (i, p) in fun.params.iter().enumerate() { locals.insert(p.name.clone(), i as u8); } - let is_method = fun - .parent - .map(|pid| flat[pid].level == 1 && flat[pid].parent.is_none()) - .unwrap_or(false); + let is_method = fun.uses_receiver; if is_method { for name in ["自", "self"] { if !locals.contains_key(name) { @@ -666,7 +667,11 @@ impl<'a> FnCompiler<'a> { .ok_or_else(|| self.err(format!("unknown `{display}`")))?; if let Some(pid) = self.flat[fid].parent { let parent = &self.flat[pid]; - if parent.level == 1 && parent.parent.is_none() && !(self.flat[fid].level == 1) { + if parent.level == 1 + && parent.parent.is_none() + && self.flat[fid].level != 1 + && self.flat[fid].uses_receiver + { return Err(self.err(format!( "`{display}` is an instance method; call it as `var`.{}", self.flat[fid].name diff --git a/src/interp.rs b/src/interp.rs index 234ff75..0675725 100644 --- a/src/interp.rs +++ b/src/interp.rs @@ -1404,7 +1404,7 @@ impl Interpreter { .ok_or_else(|| self.err(format!("unknown `{display}`")))?; } - if parent_is_object && !node.is_object() { + if parent_is_object && !node.is_object() && crate::ast::function_uses_receiver(node) { return Err(self.err(format!( "`{display}` is an instance method; call it as `var`.{}", node.name diff --git a/src/lib.rs b/src/lib.rs index 7b3c1d5..07f8414 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -37,7 +37,9 @@ pub mod linalg_ops; pub mod load; pub mod mlsp; pub mod parse; +pub mod project; pub mod repair; +pub mod sema; pub mod value; #[cfg(feature = "net-host")] pub mod version_check; diff --git a/src/main.rs b/src/main.rs index 432156b..3bf9d82 100644 --- a/src/main.rs +++ b/src/main.rs @@ -9,18 +9,25 @@ use marqdo::diagnostics::{Diagnostic, Span}; use marqdo::ext_cli::{add_ext, list_ext, remove_ext}; use marqdo::input_feed::load_stdin_file; use marqdo::knowledge::{ - compile_policy, conflicts_json, ensure_compiled, find, find_duplicates, find_json, - find_conflicts, find_stale, format_conflicts_text, format_duplicates_text, format_find_text, + compile_policy, conflicts_json, ensure_compiled, find, find_conflicts, find_duplicates, + find_json, find_stale, format_conflicts_text, format_duplicates_text, format_find_text, format_impact_text, format_preflight_yaml, format_reuse_text, format_stale_text, format_verify_text, impact, impact_json, learn, preflight, preflight_json, record_decision, resolve, reuse_json, stale_json, verify, verify_json, write_knowledge, KnowledgeOptions, LearnInput, ReuseBudget, }; -use marqdo::view::{serve, serve_debug, write_capture, write_static, CaptureOptions, DebugOptions, OutputOptions, ViewOptions}; +use marqdo::view::{ + serve, serve_debug, write_capture, write_static, CaptureOptions, DebugOptions, OutputOptions, + ViewOptions, +}; use marqdo::{Backend, RunOptions}; #[derive(Parser, Debug)] -#[command(name = "marqdo", version, about = "Marqdo interpreter — run, view, debug, catalog, knowledge, and ext")] +#[command( + name = "marqdo", + version, + about = "Marqdo interpreter — run, view, debug, catalog, knowledge, and ext" +)] struct Cli { #[command(subcommand)] command: Commands, @@ -56,7 +63,6 @@ enum MigrateAction { }, } - #[derive(Subcommand, Debug)] enum Commands { /// Execute a Marqdo source file (defaults to ./index.mq.md) @@ -355,6 +361,12 @@ enum Commands { enum KnowledgeAction { /// Compile L0–L4 projections (default) Compile, + /// Inspect stable project symbols by exact URI or display name + Inspect { + /// Symbol URI (`mq://…`) or declaration name + #[arg(value_name = "SYMBOL")] + symbol: String, + }, /// Run engineering preflight for a task Preflight { #[arg(value_name = "TASK")] @@ -488,12 +500,17 @@ fn main() -> ExitCode { /// Recursively collect `*.mq.md` under `path` (file → itself). fn collect_mq_files(path: &std::path::Path) -> Result> { fn walk(dir: &std::path::Path, out: &mut Vec) { - let Ok(rd) = std::fs::read_dir(dir) else { return }; + let Ok(rd) = std::fs::read_dir(dir) else { + return; + }; for e in rd.flatten() { let p = e.path(); let name = p.file_name().and_then(|n| n.to_str()).unwrap_or(""); if p.is_dir() { - if matches!(name, "target" | "dist" | "node_modules" | ".git" | ".marqdo") { + if matches!( + name, + "target" | "dist" | "node_modules" | ".git" | ".marqdo" + ) { continue; } walk(&p, out); @@ -610,7 +627,11 @@ fn try_main(cli: Cli) -> Result { Some(spec) => marqdo::label::parse_words(spec), None => { let groups: Vec<&str> = match &group { - Some(g) => g.split(',').map(|s| s.trim()).filter(|s| !s.is_empty()).collect(), + Some(g) => g + .split(',') + .map(|s| s.trim()) + .filter(|s| !s.is_empty()) + .collect(), None => marqdo::label::PENDING_GROUPS.to_vec(), }; marqdo::label::group_words(&groups) @@ -618,7 +639,11 @@ fn try_main(cli: Cli) -> Result { }; if also_builtin { let groups: Vec<&str> = match &group { - Some(g) => g.split(',').map(|s| s.trim()).filter(|s| !s.is_empty()).collect(), + Some(g) => g + .split(',') + .map(|s| s.trim()) + .filter(|s| !s.is_empty()) + .collect(), None => marqdo::label::PENDING_GROUPS.to_vec(), }; for w in marqdo::label::group_words(&groups) { @@ -790,7 +815,11 @@ fn try_main(cli: Cli) -> Result { } println!( "migrate labels: {idx} index, {loops} loop, {applied} file written{}", - if write { "" } else { " (dry run; pass --write)" } + if write { + "" + } else { + " (dry run; pass --write)" + } ); } Ok(0) @@ -825,20 +854,19 @@ fn try_main(cli: Cli) -> Result { snapshot, }) => { write_static(OutputOptions { - path: out_path - .or(path) - .unwrap_or_else(|| PathBuf::from(".")), + path: out_path.or(path).unwrap_or_else(|| PathBuf::from(".")), out_dir: out, no_exec, snapshot, })?; Ok(0) } - Some(ViewAction::Capture { path: out_path, out }) => { + Some(ViewAction::Capture { + path: out_path, + out, + }) => { write_capture(CaptureOptions { - path: out_path - .or(path) - .unwrap_or_else(|| PathBuf::from(".")), + path: out_path.or(path).unwrap_or_else(|| PathBuf::from(".")), out, })?; Ok(0) @@ -883,10 +911,7 @@ fn try_main(cli: Cli) -> Result { out_dir: out.clone(), })?; if !no_knowledge { - write_knowledge(KnowledgeOptions { - path, - out_dir: out, - })?; + write_knowledge(KnowledgeOptions { path, out_dir: out })?; } Ok(0) } @@ -899,10 +924,72 @@ fn try_main(cli: Cli) -> Result { let path = path.unwrap_or_else(|| PathBuf::from(".")); match action.unwrap_or(KnowledgeAction::Compile) { KnowledgeAction::Compile => { - write_knowledge(KnowledgeOptions { - path, - out_dir: out, - })?; + write_knowledge(KnowledgeOptions { path, out_dir: out })?; + Ok(0) + } + KnowledgeAction::Inspect { symbol } => { + // A supplied directory is an explicit compilation scope; + // a supplied file inherits the nearest project boundary. + let project = if path.is_dir() { + marqdo::project::ProjectRoot::new(&path)? + } else { + marqdo::project::ProjectRoot::discover(&path)? + }; + let index = marqdo::sema::ProjectIndex::build(project)?; + let candidates: Vec<_> = if symbol.starts_with("mq://") { + index + .symbols() + .iter() + .filter(|item| item.id.as_str() == symbol) + .collect() + } else { + index.symbols_named(&symbol) + }; + if candidates.is_empty() { + anyhow::bail!( + "no semantic symbol matching `{symbol}` in project {}", + index.root().path().display() + ); + } + if json { + println!( + "{}", + serde_json::json!({ + "project": index.project_id(), + "query": symbol, + "ambiguous": candidates.len() > 1, + "symbols": candidates.iter().map(|item| serde_json::json!({ + "id": item.id.as_str(), + "module": item.module.as_str(), + "kind": item.kind.as_str(), + "name": item.name, + "declaration_path": item.declaration_path, + "source": { + "file": item.source, + "line": item.line, + }, + })).collect::>(), + }) + ); + } else { + for item in &candidates { + println!( + "{}\n {} {} · module {}\n {}:{}", + item.id, + item.kind.as_str(), + item.declaration_path.join("."), + item.module, + item.source.display(), + item.line, + ); + } + if candidates.len() > 1 { + println!( + "ambiguous: {} symbols named `{symbol}`; use one full mq:// URI", + candidates.len() + ); + } + } Ok(0) } KnowledgeAction::Preflight { @@ -923,14 +1010,13 @@ fn try_main(cli: Cli) -> Result { } else { print!("{}", format_preflight_yaml(&pf)); } - Ok(if pf.create_allowed - || pf.decision == "REUSE" - || pf.decision == "ADAPT" - { - 0 - } else { - 2 - }) + Ok( + if pf.create_allowed || pf.decision == "REUSE" || pf.decision == "ADAPT" { + 0 + } else { + 2 + }, + ) } KnowledgeAction::Record { decision, diff --git a/src/parse/expr.rs b/src/parse/expr.rs index c5ef1d1..f114601 100644 --- a/src/parse/expr.rs +++ b/src/parse/expr.rs @@ -683,6 +683,20 @@ impl<'a> Parser<'a> { return Ok(Expr::Call(call)); } } + // A dotted definition path in a value position is a zero-argument + // call. This makes a documented fact such as `facts.Person.birth_year` + // executable without ceremonial `()`. + if let Some(path) = split_lib_path_callee(&word) { + let callee = path.last().cloned().unwrap_or_default(); + return Ok(Expr::Call(CallExpr { + callee, + path: Some(path), + receiver: None, + args: Vec::new(), + pre_modifiers: Vec::new(), + bracket_marked: false, + })); + } self.skip_ws(); if self.starts_with("[^") { return self.parse_index_chain(Expr::Var(word)); @@ -2075,6 +2089,21 @@ mod bracket_call_tests { assert!(c.receiver.is_none()); } + #[test] + fn dotted_path_is_implicit_zero_arg_call() { + let c = call_of(parse_expr_prefer_var("facts.Person.birth_year").unwrap()); + assert_eq!(c.callee, "birth_year"); + assert_eq!( + c.path.as_deref(), + Some(&[ + "facts".to_string(), + "Person".to_string(), + "birth_year".to_string(), + ][..]) + ); + assert!(c.args.is_empty()); + } + #[test] fn paren_call_nested_in_expression() { let c = call_of(parse_expr("加(加(1 2), 3)").unwrap()); diff --git a/src/project/mod.rs b/src/project/mod.rs new file mode 100644 index 0000000..9caa656 --- /dev/null +++ b/src/project/mod.rs @@ -0,0 +1,190 @@ +//! Project boundaries and deterministic source discovery. +//! +//! The executable-knowledge compiler must never let each consumer decide what +//! a project contains. This module establishes one filesystem boundary and a +//! stable, sorted list of Marqdo source files for `sema`, EKC, view, and MLSP. + +use std::fs; +use std::path::{Path, PathBuf}; + +use anyhow::{bail, Context, Result}; + +/// Canonical project boundary used by project-wide compilation. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ProjectRoot { + root: PathBuf, +} + +impl ProjectRoot { + /// Find the nearest explicit project marker or Git root. A standalone + /// source file without either marker forms a one-directory project. + pub fn discover(start: &Path) -> Result { + let start = if start.is_file() { + start.parent().unwrap_or_else(|| Path::new(".")) + } else { + start + }; + let start = start + .canonicalize() + .with_context(|| format!("resolve project start {}", start.display()))?; + let fallback = start.clone(); + let mut current = start.as_path(); + loop { + if current.join(".marqdo").join("project.toml").is_file() + || current.join(".git").exists() + { + return Ok(Self { + root: current.to_path_buf(), + }); + } + match current.parent() { + Some(parent) => current = parent, + None => { + return Ok(Self { root: fallback }); + } + } + } + } + + /// Construct an explicitly scoped project root. + pub fn new(root: &Path) -> Result { + let root = root + .canonicalize() + .with_context(|| format!("resolve project root {}", root.display()))?; + if !root.is_dir() { + bail!("project root {} is not a directory", root.display()); + } + Ok(Self { root }) + } + + pub fn path(&self) -> &Path { + &self.root + } + + /// Discover every project-local `.mq.md` file in lexicographic relative + /// path order. Generated and dependency directories are intentionally + /// excluded so a cache cannot silently become source knowledge. + pub fn source_files(&self) -> Result> { + let mut out = Vec::new(); + collect_sources(&self.root, &self.root, &mut out)?; + out.sort_by(|a, b| relative_key(&self.root, a).cmp(&relative_key(&self.root, b))); + Ok(out) + } +} + +const EXCLUDED_DIRS: &[&str] = &[ + ".git", + ".marqdo", + "target", + "node_modules", + ".cursor", + ".agents", +]; + +fn collect_sources(root: &Path, dir: &Path, out: &mut Vec) -> Result<()> { + let mut entries: Vec<_> = fs::read_dir(dir) + .with_context(|| format!("read project directory {}", dir.display()))? + .collect::, _>>()?; + entries.sort_by_key(|entry| entry.file_name()); + + for entry in entries { + let path = entry.path(); + let file_type = entry.file_type()?; + if file_type.is_symlink() { + // A source symlink is only admitted if its resolved target remains + // within the project boundary. This prevents index escape. + let Ok(canonical) = path.canonicalize() else { + continue; + }; + if !canonical.starts_with(root) { + continue; + } + if canonical.is_dir() { + collect_sources(root, &canonical, out)?; + } else if is_mq_md(&canonical) { + out.push(canonical); + } + continue; + } + if file_type.is_dir() { + let name = entry.file_name(); + if EXCLUDED_DIRS.iter().any(|excluded| name == *excluded) { + continue; + } + collect_sources(root, &path, out)?; + } else if file_type.is_file() && is_mq_md(&path) { + out.push(path); + } + } + Ok(()) +} + +fn is_mq_md(path: &Path) -> bool { + path.file_name() + .and_then(|name| name.to_str()) + .is_some_and(|name| name.ends_with(".mq.md")) +} + +fn relative_key(root: &Path, path: &Path) -> String { + path.strip_prefix(root) + .unwrap_or(path) + .to_string_lossy() + .replace('\\', "/") +} + +#[cfg(test)] +mod tests { + use super::*; + use std::time::{SystemTime, UNIX_EPOCH}; + + fn fixture_root(name: &str) -> PathBuf { + let nanos = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_nanos(); + let root = std::env::temp_dir().join(format!("marqdo-project-{name}-{nanos}")); + fs::create_dir_all(&root).unwrap(); + root + } + + #[test] + fn source_discovery_is_sorted_and_skips_generated_dirs() { + let root = fixture_root("sources"); + fs::create_dir_all(root.join("z")).unwrap(); + fs::create_dir_all(root.join("a")).unwrap(); + fs::create_dir_all(root.join("target")).unwrap(); + fs::write(root.join("z/b.mq.md"), "# z").unwrap(); + fs::write(root.join("a/a.mq.md"), "# a").unwrap(); + fs::write(root.join("target/ignored.mq.md"), "# ignored").unwrap(); + fs::write(root.join("README.md"), "not source").unwrap(); + + let project = ProjectRoot::new(&root).unwrap(); + let files = project.source_files().unwrap(); + let names: Vec<_> = files + .iter() + .map(|p| { + p.strip_prefix(&root) + .unwrap() + .to_string_lossy() + .replace('\\', "/") + }) + .collect(); + assert_eq!(names, ["a/a.mq.md", "z/b.mq.md"]); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn nearest_marker_wins() { + let root = fixture_root("discover"); + let nested = root.join("nested/work"); + fs::create_dir_all(nested.join(".marqdo")).unwrap(); + fs::write(nested.join(".marqdo/project.toml"), "id = \"nested\"").unwrap(); + fs::create_dir_all(nested.join("src")).unwrap(); + let file = nested.join("src/main.mq.md"); + fs::write(&file, "# main").unwrap(); + + let project = ProjectRoot::discover(&file).unwrap(); + assert_eq!(project.path(), nested.canonicalize().unwrap()); + fs::remove_dir_all(root).unwrap(); + } +} diff --git a/src/sema/mod.rs b/src/sema/mod.rs new file mode 100644 index 0000000..98f1002 --- /dev/null +++ b/src/sema/mod.rs @@ -0,0 +1,9 @@ +//! Compiler semantic analysis for executable knowledge. +//! +//! Syntax remains in `ast`/`parse`; this module owns project-wide identity and +//! binding facts so runtime, EKC, view, and agents do not independently infer +//! the meaning of the same source text. + +pub mod symbols; + +pub use symbols::{ModuleId, ProjectIndex, SymbolDecl, SymbolId, SymbolKind}; diff --git a/src/sema/symbols.rs b/src/sema/symbols.rs new file mode 100644 index 0000000..d9b1801 --- /dev/null +++ b/src/sema/symbols.rs @@ -0,0 +1,378 @@ +//! Stable module/symbol identity and deterministic project declaration index. + +use std::collections::BTreeMap; +use std::fmt; +use std::fs; +use std::path::{Path, PathBuf}; + +use anyhow::{bail, Context, Result}; + +use crate::ast::Function; +use crate::project::ProjectRoot; + +/// Project-local module identity. An explicit frontmatter `id` wins over the +/// normalized relative path, so authors can preserve identity across moves. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct ModuleId(String); + +impl ModuleId { + pub fn as_str(&self) -> &str { + &self.0 + } +} + +impl fmt::Display for ModuleId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.0) + } +} + +/// Globally stable address inside a project compilation. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct SymbolId(String); + +impl SymbolId { + pub fn as_str(&self) -> &str { + &self.0 + } +} + +impl fmt::Display for SymbolId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.0) + } +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] +pub enum SymbolKind { + Type, + Function, +} + +impl SymbolKind { + pub fn as_str(self) -> &'static str { + match self { + Self::Type => "type", + Self::Function => "function", + } + } +} + +/// One source declaration, including a display path for human-facing tools. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct SymbolDecl { + pub id: SymbolId, + pub module: ModuleId, + pub kind: SymbolKind, + pub name: String, + pub declaration_path: Vec, + pub source: PathBuf, + pub line: u32, +} + +/// Deterministic read-only view of all declarations in one project. +#[derive(Debug, Clone)] +pub struct ProjectIndex { + project_id: String, + root: ProjectRoot, + modules: BTreeMap, + symbols: Vec, + by_id: BTreeMap, + by_name: BTreeMap>, +} + +impl ProjectIndex { + pub fn build(root: ProjectRoot) -> Result { + let project_id = project_id(root.path()); + let files = root.source_files()?; + let mut modules = BTreeMap::new(); + let mut symbols = Vec::new(); + + for file in files { + let source = fs::read_to_string(&file) + .with_context(|| format!("read source {}", file.display()))?; + let module_id = module_id(&source, root.path(), &file)?; + if let Some(previous) = modules.insert(module_id.clone(), file.clone()) { + bail!( + "duplicate module id `{module_id}` in {} and {}", + previous.display(), + file.display() + ); + } + let module = crate::load::parse_source_auto(&source) + .with_context(|| format!("parse source {}", file.display()))?; + for function in &module.functions { + collect_symbols( + &project_id, + &module_id, + &file, + function, + &mut Vec::new(), + &mut symbols, + )?; + } + } + + symbols.sort_by(|a, b| a.id.cmp(&b.id)); + let mut by_id = BTreeMap::new(); + let mut by_name: BTreeMap> = BTreeMap::new(); + for (index, symbol) in symbols.iter().enumerate() { + if by_id.insert(symbol.id.clone(), index).is_some() { + bail!("duplicate symbol id `{}`", symbol.id); + } + by_name.entry(symbol.name.clone()).or_default().push(index); + } + for indexes in by_name.values_mut() { + indexes.sort_by(|a, b| symbols[*a].id.cmp(&symbols[*b].id)); + } + + Ok(Self { + project_id, + root, + modules, + symbols, + by_id, + by_name, + }) + } + + pub fn project_id(&self) -> &str { + &self.project_id + } + + pub fn root(&self) -> &ProjectRoot { + &self.root + } + + pub fn modules(&self) -> &BTreeMap { + &self.modules + } + + pub fn symbols(&self) -> &[SymbolDecl] { + &self.symbols + } + + pub fn symbol(&self, id: &SymbolId) -> Option<&SymbolDecl> { + self.by_id.get(id).map(|index| &self.symbols[*index]) + } + + /// Candidates are deliberately returned as a list: discovery may be fuzzy, + /// but callers must report ambiguity instead of silently choosing one. + pub fn symbols_named(&self, name: &str) -> Vec<&SymbolDecl> { + self.by_name + .get(name) + .into_iter() + .flatten() + .map(|index| &self.symbols[*index]) + .collect() + } +} + +fn collect_symbols( + project_id: &str, + module_id: &ModuleId, + source: &Path, + function: &Function, + parent_path: &mut Vec, + out: &mut Vec, +) -> Result<()> { + let kind = if function.is_object() { + SymbolKind::Type + } else { + SymbolKind::Function + }; + parent_path.push(function.name.clone()); + let id = symbol_id(project_id, module_id, kind, parent_path); + if out.iter().any(|existing| existing.id == id) { + bail!( + "duplicate declaration path `{}` in module `{module_id}`", + parent_path.join("/") + ); + } + out.push(SymbolDecl { + id, + module: module_id.clone(), + kind, + name: function.name.clone(), + declaration_path: parent_path.clone(), + source: source.to_path_buf(), + line: function.span.line, + }); + for child in &function.children { + collect_symbols(project_id, module_id, source, child, parent_path, out)?; + } + parent_path.pop(); + Ok(()) +} + +fn module_id(source: &str, root: &Path, file: &Path) -> Result { + if let Some(id) = frontmatter_value(source, "id") { + if id.is_empty() { + bail!("empty frontmatter id in {}", file.display()); + } + return Ok(ModuleId(id)); + } + let rel = file.strip_prefix(root).with_context(|| { + format!( + "source {} outside project root {}", + file.display(), + root.display() + ) + })?; + let mut value = rel.to_string_lossy().replace('\\', "/"); + value.truncate(value.len().saturating_sub(".mq.md".len())); + Ok(ModuleId(value)) +} + +fn project_id(root: &Path) -> String { + frontmatter_project_id(root).unwrap_or_else(|| { + root.file_name() + .and_then(|name| name.to_str()) + .filter(|name| !name.is_empty()) + .unwrap_or("marqdo-project") + .to_string() + }) +} + +fn frontmatter_project_id(root: &Path) -> Option { + let path = root.join(".marqdo").join("project.toml"); + let source = fs::read_to_string(path).ok()?; + source.lines().find_map(|line| { + let line = line.trim(); + let value = line + .strip_prefix("id=") + .or_else(|| line.strip_prefix("id ="))?; + let value = value.trim().trim_matches('"'); + (!value.is_empty()).then(|| value.to_string()) + }) +} + +fn frontmatter_value(source: &str, key: &str) -> Option { + let source = source.strip_prefix('\u{feff}').unwrap_or(source); + let mut lines = source.lines(); + if lines.next().map(str::trim) != Some("---") { + return None; + } + let key = format!("{key}:"); + for line in lines { + let line = line.trim(); + if line == "---" { + break; + } + if let Some(value) = line.strip_prefix(&key) { + return Some(value.trim().trim_matches('"').to_string()); + } + } + None +} + +fn symbol_id( + project_id: &str, + module_id: &ModuleId, + kind: SymbolKind, + declaration_path: &[String], +) -> SymbolId { + let path = declaration_path + .iter() + .map(|segment| percent_encode(segment)) + .collect::>() + .join("/"); + SymbolId(format!( + "mq://{}/{}/{}{}", + percent_encode(project_id), + percent_encode(module_id.as_str()), + kind.as_str(), + if path.is_empty() { + String::new() + } else { + format!("/{path}") + } + )) +} + +fn percent_encode(value: &str) -> String { + let mut out = String::new(); + for byte in value.bytes() { + match byte { + b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' => out.push(byte as char), + _ => out.push_str(&format!("%{byte:02X}")), + } + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + use std::time::{SystemTime, UNIX_EPOCH}; + + fn fixture_root(name: &str) -> PathBuf { + let nanos = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_nanos(); + let root = std::env::temp_dir().join(format!("marqdo-sema-{name}-{nanos}")); + fs::create_dir_all(&root).unwrap(); + root + } + + #[test] + fn index_uses_explicit_module_id_and_stable_declaration_paths() { + let root = fixture_root("ids"); + let source = r#"--- +id: knowledge.policy +--- +# 书店政策 + +## 金卡折扣 + +*0.90* +"#; + fs::write(root.join("policy.mq.md"), source).unwrap(); + + let index = ProjectIndex::build(ProjectRoot::new(&root).unwrap()).unwrap(); + assert_eq!(index.modules().len(), 1); + assert_eq!(index.symbols().len(), 2); + assert!(index.symbols()[0].id.as_str().starts_with(&format!( + "mq://{}/knowledge.policy/function/", + index.project_id() + ))); + assert!(index.symbols()[0].id.as_str().ends_with( + "%E4%B9%A6%E5%BA%97%E6%94%BF%E7%AD%96/%E9%87%91%E5%8D%A1%E6%8A%98%E6%89%A3" + )); + assert_eq!(index.symbols()[1].declaration_path, ["书店政策"]); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn duplicate_module_ids_are_rejected() { + let root = fixture_root("duplicate-module"); + fs::write(root.join("a.mq.md"), "---\nid: duplicate\n---\n# a").unwrap(); + fs::write(root.join("b.mq.md"), "---\nid: duplicate\n---\n# b").unwrap(); + + let err = ProjectIndex::build(ProjectRoot::new(&root).unwrap()) + .unwrap_err() + .to_string(); + assert!(err.contains("duplicate module id `duplicate`")); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn symbols_named_remains_ambiguous_by_design() { + let root = fixture_root("ambiguous"); + fs::write(root.join("a.mq.md"), "# A\n\n## 查询\n\n*1*").unwrap(); + fs::write(root.join("b.mq.md"), "# B\n\n## 查询\n\n*2*").unwrap(); + + let index = ProjectIndex::build(ProjectRoot::new(&root).unwrap()).unwrap(); + assert_eq!(index.symbols_named("查询").len(), 2); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn percent_encoding_preserves_unicode_boundaries() { + assert_eq!( + percent_encode("李白/出生 年份"), + "%E6%9D%8E%E7%99%BD%2F%E5%87%BA%E7%94%9F%20%E5%B9%B4%E4%BB%BD" + ); + } +} diff --git a/tests/errors/ns-instance-method.mq.md b/tests/errors/ns-instance-method.mq.md index 304b578..6e12d54 100644 --- a/tests/errors/ns-instance-method.mq.md +++ b/tests/errors/ns-instance-method.mq.md @@ -5,4 +5,4 @@ import helpers:../structure/ns/helpers.mq.md # main -> helpers.Box.tag s=x +> helpers.Box.type_name diff --git a/tests/gold.rs b/tests/gold.rs index dcb2d66..b0d90ba 100644 --- a/tests/gold.rs +++ b/tests/gold.rs @@ -490,6 +490,20 @@ fn bytecode_ns_use() { assert_out_backend("tests/structure/ns/use.mq.md", "bytecode", "hi"); } +#[test] +fn structure_ns_associated_function() { + assert_out("tests/structure/ns/associated.mq.md", "associated\n701"); +} + +#[test] +fn bytecode_ns_associated_function() { + assert_out_backend( + "tests/structure/ns/associated.mq.md", + "bytecode", + "associated\n701", + ); +} + #[test] fn error_ns_instance_method() { assert_err( diff --git a/tests/structure/ns/associated.mq.md b/tests/structure/ns/associated.mq.md new file mode 100644 index 0000000..10a5f57 --- /dev/null +++ b/tests/structure/ns/associated.mq.md @@ -0,0 +1,14 @@ +--- +title: receiver-free object children are associated executable knowledge +import helpers:helpers.mq.md +--- + +# main + +**year = helpers.Box.tag(s="associated")** + +> print text=`year` + +**also = helpers.Box.birth_year** + +> print text=`also` diff --git a/tests/structure/ns/helpers.mq.md b/tests/structure/ns/helpers.mq.md index 2778670..be6c259 100644 --- a/tests/structure/ns/helpers.mq.md +++ b/tests/structure/ns/helpers.mq.md @@ -17,3 +17,11 @@ Nested free function (not an object method) for `helpers.pack.label`. + `s` *s* + +## birth_year + +*701* + +## type_name + +*`self`*