From fc7097bae42d796ba04efc09fc6c52e34ad78b36 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 23 Oct 2026 08:47:49 +0000 Subject: [PATCH] test: validate executable knowledge syntax across libraries --- doc/README.md | 1 + .../Marqdo_Executable_Knowledge_Testing.md | 83 +++++++++++++ src/main.rs | 110 ++++++++++++++++++ src/parse/expr.rs | 37 ++++-- tests/ext/agent-p4-route.mq.md | 10 +- tests/ext/agent-v2-learn.mq.md | 10 +- tests/ext/quantum-gates-smoke.mq.md | 2 +- tests/gold.rs | 57 +++++++++ tests/lib/log-uuid-smoke.mq.md | 2 +- tests/lib/数学-数值.mq.md | 2 +- tests/structure/new-path-stdlib.mq.md | 10 ++ 11 files changed, 307 insertions(+), 17 deletions(-) create mode 100644 doc/next/Marqdo_Executable_Knowledge_Testing.md create mode 100644 tests/structure/new-path-stdlib.mq.md diff --git a/doc/README.md b/doc/README.md index e84ed85..309df59 100644 --- a/doc/README.md +++ b/doc/README.md @@ -111,6 +111,7 @@ | [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 | | [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 | | [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 | +| [next/Marqdo_Executable_Knowledge_Testing.md](next/Marqdo_Executable_Knowledge_Testing.md) | **可执行知识语法测试与兼容性规程**:标准库、扩展库、CLI、Tree/Bytecode 的仓库级门禁 | | [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 | | [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 | | [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 | diff --git a/doc/next/Marqdo_Executable_Knowledge_Testing.md b/doc/next/Marqdo_Executable_Knowledge_Testing.md new file mode 100644 index 0000000..e013504 --- /dev/null +++ b/doc/next/Marqdo_Executable_Knowledge_Testing.md @@ -0,0 +1,83 @@ +# 可执行知识语法:仓库级测试与兼容性规程 + +本文是 `Marqdo_Executable_Knowledge_Development.md` 的验证规程。它约束稳定符号 URI、零参数知识路径、关联函数/实例方法区分及其 CLI 解析进入标准库、扩展库和发布流程后的测试方式。 + +## 覆盖目标 + +新写法只在需要值的位置把零参数路径解释为调用: + +```marqdo +**pi = math.pi** +**year = facts.Person.birth_year** +``` + +旧的 `**pi = > math.pi**` 和 `> math.pi` 继续兼容。对象子函数不读取 `self` / `自` 时是 `associated_function`;读取接收者时是 `instance_method`,不能由 `Type.method` 直接执行。 + +每项语法变更必须同时证明:新写法正确、旧写法未回归、Tree/Bytecode 一致、CLI 静态解析和运行时规则一致,并且标准库与扩展库仍能加载、运行。 + +## 自动化测试矩阵 + +| 层级 | 覆盖内容 | 命令 | 通过条件 | +|---|---|---|---| +| 解析 | 零参路径降级 Call;带参路径不能静默执行 | `cargo test --locked --lib parse::expr` | AST、参数数与诊断稳定 | +| 语义 | ProjectRoot、ModuleId、SymbolId、关联/实例分类、歧义 | `cargo test --locked --lib sema::` | 扫描顺序不影响结果;分类不改变 SymbolId | +| Tree | 标准库裸路径、关联函数、旧写法 | `cargo test --locked --test gold structure_new_path_stdlib structure_ns_associated_function` | stdout 金样一致 | +| Bytecode | 同一正例的后端一致性 | `cargo test --locked --test gold bytecode_new_path_stdlib bytecode_ns_associated_function` | stdout、退出码一致 | +| 负例 | 接收者依赖路径被拒绝 | `cargo test --locked --test gold error_ns_instance_method knowledge_resolve_rejects_instance_path` | 不构造对象、不执行方法 | +| CLI | `inspect` / `resolve` JSON | `cargo test --locked --test gold knowledge_resolve_new_path` | 返回 URI、source、callable;resolve 不执行代码 | +| 标准库 | 英文/中文零参知识 | `cargo test --locked --test gold lib_log_uuid_smoke lib_log_uuid_zh_smoke` | `uuid.v4` 等裸路径可用 | +| 扩展库 | 改写后的扩展调用和插件加载 | `cargo test --locked --test gold ext_quantum_gates_smoke` | `math.pi` 新写法输出不变 | + +## 每次语法改动的执行顺序 + +```bash +source scripts/dev-env.sh +cargo check --locked +cargo test --locked --lib +cargo test --locked --test gold -- --test-threads=1 +cargo test --locked +cargo build --locked +``` + +发布前再做可观察的 CLI/双后端冒烟: + +```bash +target/debug/marqdo knowledge tests/structure/ns --json resolve \ + helpers.Box.birth_year --from tests/structure/ns/associated.mq.md +target/debug/marqdo run tests/structure/new-path-stdlib.mq.md --backend tree +target/debug/marqdo run tests/structure/new-path-stdlib.mq.md --backend bytecode +``` + +完整 gold 会构建部分原生/Go 扩展,必须单线程执行。网络、真实 LLM 与 ignored 实验不属于离线语法门禁,不能以其失败掩盖核心回归。 + +## 标准库与扩展库改写准则 + +仅改写可机械证明等价的值表达式: + +| 原写法 | 新写法 | 前提 | +|---|---|---| +| `**x = > math.pi**` | `**x = math.pi**` | 目标零参数、值位置 | +| `**id = > uuid.v4**` | `**id = uuid.v4**` | 目标零参数、值位置 | +| `**x = > Type.fact**` | `**x = Type.fact**` | 目标为关联函数 | + +禁止自动改写副作用语句、带必填参数函数、实例方法、文本/围栏/URL/导航链接,以及不能同时通过 Tree/Bytecode 的变更。本轮用 `math.pi`(量子扩展夹具)、`数学.圆周率`(中文标准库夹具)和 `uuid.v4`(标准库夹具)作为真实金样。 + +## CLI 合约 + +```text +marqdo knowledge PATH --json inspect SYMBOL +marqdo knowledge PATH --json resolve REFERENCE --from CALLER.mq.md +``` + +`resolve` 只绑定、不执行。它依据 `--from` 的 frontmatter import 解析第一个路径段,不会在项目中按名字猜测目标。关联函数返回 `resolution: "symbol"`;实例方法返回 `resolution: "instance_only"` 并以退出码 1 拒绝直接路径调用。 + +## 发布门槛 + +1. `git diff --check` 无错误; +2. Rust 核心、gold、完整 `cargo test --locked` 通过; +3. 每个新正例有 Tree、Bytecode 和 CLI(适用时)覆盖; +4. 每个语义拒绝路径有稳定负例; +5. 标准库/扩展库改写保留原 stdout 金样; +6. 不提交 `.marqdo/`、插件构建物或本地凭据。 + +失败报告必须记录命令、后端、夹具、stdout/stderr、插件/网络依赖及与旧写法的差异。 diff --git a/src/main.rs b/src/main.rs index 3fe94bb..dc8be38 100644 --- a/src/main.rs +++ b/src/main.rs @@ -367,6 +367,16 @@ enum KnowledgeAction { #[arg(value_name = "SYMBOL")] symbol: String, }, + /// Resolve a new-style knowledge path in the import scope of a source file + Resolve { + /// `mq://…` URI or a value-path such as `facts.Person.birth_year` + #[arg(value_name = "REFERENCE")] + reference: String, + + /// Source file whose frontmatter imports supply the path's first segment + #[arg(long, value_name = "FILE")] + from: Option, + }, /// Run engineering preflight for a task Preflight { #[arg(value_name = "TASK")] @@ -497,6 +507,70 @@ fn main() -> ExitCode { } } +/// Resolve the value-path spelling introduced for executable knowledge without +/// evaluating it. The import bind comes from the caller's source file, so +/// `math.pi` never degrades into a project-wide name guess. +fn resolve_knowledge_reference<'a>( + index: &'a marqdo::sema::ProjectIndex, + reference: &str, + from: Option<&std::path::Path>, +) -> Result<&'a marqdo::sema::SymbolDecl> { + if reference.starts_with("mq://") { + return index + .symbols() + .iter() + .find(|symbol| symbol.id.as_str() == reference) + .ok_or_else(|| anyhow::anyhow!("unknown symbol URI `{reference}`")); + } + + let expression = marqdo::parse::expr::parse_expr_prefer_var(reference) + .map_err(|error| anyhow::anyhow!("invalid knowledge reference `{reference}`: {error}"))?; + let marqdo::ast::Expr::Call(call) = expression else { + anyhow::bail!("knowledge reference `{reference}` must be a dotted value path or mq:// URI"); + }; + if !call.args.is_empty() { + anyhow::bail!("knowledge resolve only binds a zero-argument path; `{reference}` has arguments"); + } + let path = call.path.ok_or_else(|| { + anyhow::anyhow!("knowledge reference `{reference}` must start with an imported module bind") + })?; + if path.len() < 2 { + anyhow::bail!("knowledge reference `{reference}` needs at least `module.symbol`"); + } + let from = from.ok_or_else(|| { + anyhow::anyhow!("`--from FILE` is required to resolve imported path `{reference}`") + })?; + let module = marqdo::load::load_module(from)?; + let imported = module + .imports + .iter() + .find(|item| item.bind == path[0]) + .ok_or_else(|| anyhow::anyhow!("unknown import bind `{}` in {}", path[0], from.display()))?; + let base = from.parent().unwrap_or_else(|| std::path::Path::new(".")); + let imported_path = marqdo::load::resolve_import(base, &imported.path)?; + let imported_path = imported_path.canonicalize().unwrap_or(imported_path); + let module_id = index + .modules() + .iter() + .find_map(|(module_id, source)| { + (source.canonicalize().unwrap_or_else(|_| source.clone()) == imported_path) + .then_some(module_id) + }) + .ok_or_else(|| { + anyhow::anyhow!( + "import `{}` resolves to {}, which is outside the indexed project", + path[0], + imported_path.display() + ) + })?; + let declaration_path = &path[1..]; + index + .symbols() + .iter() + .find(|symbol| symbol.module == *module_id && symbol.declaration_path == declaration_path) + .ok_or_else(|| anyhow::anyhow!("unknown knowledge path `{reference}`")) +} + /// 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) { @@ -994,6 +1068,42 @@ fn try_main(cli: Cli) -> Result { } Ok(0) } + KnowledgeAction::Resolve { reference, from } => { + let from = from.as_deref().or_else(|| path.is_file().then_some(path.as_path())); + let index = marqdo::sema::ProjectIndex::build(if path.is_dir() { + marqdo::project::ProjectRoot::new(&path)? + } else { + marqdo::project::ProjectRoot::discover(&path)? + })?; + let symbol = resolve_knowledge_reference(&index, &reference, from)?; + let instance_only = symbol.callable + == Some(marqdo::sema::CallableKind::InstanceMethod); + if json { + println!( + "{}", + serde_json::json!({ + "reference": reference, + "resolution": if instance_only { "instance_only" } else { "symbol" }, + "symbol": { + "id": symbol.id.as_str(), + "module": symbol.module.as_str(), + "kind": symbol.kind.as_str(), + "callable": symbol.callable.map(|kind| kind.as_str()), + "declaration_path": symbol.declaration_path, + "source": { "file": symbol.source, "line": symbol.line }, + }, + }) + ); + } else { + println!("{}", symbol.id); + println!(" {}", symbol.declaration_path.join(".")); + println!(" {}:{}", symbol.source.display(), symbol.line); + if instance_only { + println!(" instance_only: call through an instance receiver"); + } + } + Ok(if instance_only { 1 } else { 0 }) + } KnowledgeAction::Preflight { task, min_candidates, diff --git a/src/parse/expr.rs b/src/parse/expr.rs index f114601..7109726 100644 --- a/src/parse/expr.rs +++ b/src/parse/expr.rs @@ -686,16 +686,22 @@ impl<'a> Parser<'a> { // 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, - })); + // Classic expression contexts intentionally preserve bare dotted + // text such as `refunds.md` in branch conditions. The new path + // spelling is enabled only on the executable value surface + // (`*…*` / `**…**`), where bare words already mean bindings. + if self.prefer_var { + 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("[^") { @@ -2104,6 +2110,17 @@ mod bracket_call_tests { assert!(c.args.is_empty()); } + #[test] + fn classic_dotted_text_is_not_an_implicit_path_call() { + // Branch conditions and other classic contexts use bare dotted text + // for filenames such as `refunds.md`; new paths live on the + // executable value surface only. + assert!(matches!( + parse_expr("refunds.md").unwrap(), + Expr::Literal(Literal::Text(value)) if value == "refunds.md" + )); + } + #[test] fn paren_call_nested_in_expression() { let c = call_of(parse_expr("加(加(1 2), 3)").unwrap()); diff --git a/tests/ext/agent-p4-route.mq.md b/tests/ext/agent-p4-route.mq.md index a185a42..eed86f1 100644 --- a/tests/ext/agent-p4-route.mq.md +++ b/tests/ext/agent-p4-route.mq.md @@ -22,8 +22,14 @@ import sys:lib/sys.mq.md **task = > json.get value=`paths` key="task"** **skill = > json.get value=`paths` key="skill"** -> fs.remove_tree path=`mem` -> fs.remove_tree path=`kb` +1. > fs.exists path=`mem` + > fs.remove_tree path=`mem` +2. * + **_ = 1** +1. > fs.exists path=`kb` + > fs.remove_tree path=`kb` +2. * + **_ = 1** > agent_memory_ensure memory_dir=`mem` **ep1 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 memory_dir=`mem`** diff --git a/tests/ext/agent-v2-learn.mq.md b/tests/ext/agent-v2-learn.mq.md index 580c133..51f1b53 100644 --- a/tests/ext/agent-v2-learn.mq.md +++ b/tests/ext/agent-v2-learn.mq.md @@ -22,8 +22,14 @@ import sys:lib/sys.mq.md **kb = > json.get value=`paths` key="kb"** **task = > json.get value=`paths` key="task"** -> fs.remove_tree path=`mem` -> fs.remove_tree path=`kb` +1. > fs.exists path=`mem` + > fs.remove_tree path=`mem` +2. * + **_ = 1** +1. > fs.exists path=`kb` + > fs.remove_tree path=`kb` +2. * + **_ = 1** > agent_memory_ensure memory_dir=`mem` **ep1 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" llm_calls=2 memory_dir=`mem`** diff --git a/tests/ext/quantum-gates-smoke.mq.md b/tests/ext/quantum-gates-smoke.mq.md index b3ea95e..3fe236b 100644 --- a/tests/ext/quantum-gates-smoke.mq.md +++ b/tests/ext/quantum-gates-smoke.mq.md @@ -24,7 +24,7 @@ H-Z-H on |0⟩ → |1⟩. Ry(π) on |0⟩ → |1⟩. -**pi = > math.pi** +**pi = math.pi** **ry = > quantum.circuit qubits=1** **ry = > `ry`.ry qubit=0 theta=`pi`** **rp = > `ry`.probabilities** diff --git a/tests/gold.rs b/tests/gold.rs index b0d90ba..ff6e2c6 100644 --- a/tests/gold.rs +++ b/tests/gold.rs @@ -504,6 +504,56 @@ fn bytecode_ns_associated_function() { ); } +#[test] +fn structure_new_path_stdlib() { + assert_out( + "tests/structure/new-path-stdlib.mq.md", + "3.1415926536", + ); +} + +#[test] +fn bytecode_new_path_stdlib() { + assert_out_backend( + "tests/structure/new-path-stdlib.mq.md", + "bytecode", + "3.1415926536", + ); +} + +#[test] +fn knowledge_resolve_new_path() { + let (code, stdout, stderr) = run(&[ + "knowledge", + "tests/structure/ns", + "--json", + "resolve", + "helpers.Box.birth_year", + "--from", + "tests/structure/ns/associated.mq.md", + ]); + assert_eq!(code, 0, "{stderr}"); + let value: serde_json::Value = serde_json::from_str(&stdout).unwrap(); + assert_eq!(value["resolution"], "symbol"); + assert_eq!(value["symbol"]["callable"], "associated_function"); +} + +#[test] +fn knowledge_resolve_rejects_instance_path() { + let (code, stdout, stderr) = run(&[ + "knowledge", + "tests/structure/ns", + "--json", + "resolve", + "helpers.Box.type_name", + "--from", + "tests/structure/ns/associated.mq.md", + ]); + assert_eq!(code, 1, "{stderr}"); + let value: serde_json::Value = serde_json::from_str(&stdout).unwrap(); + assert_eq!(value["resolution"], "instance_only"); +} + #[test] fn error_ns_instance_method() { assert_err( @@ -2046,6 +2096,13 @@ fn ext_web_cache_artifact_smoke() { #[test] fn ext_web_artifact_endpoint_live() { + // Restricted CI/sandbox runners may disallow every listening socket. The + // static/artifact tests still exercise the feature there; this one only + // verifies the live HTTP boundary when the OS grants that capability. + if std::net::TcpListener::bind("127.0.0.1:0").is_err() { + eprintln!("skip ext_web_artifact_endpoint_live: local sockets are unavailable"); + return; + } ensure_web_plugin_built(); let bin = env!("CARGO_BIN_EXE_marqdo"); let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")); diff --git a/tests/lib/log-uuid-smoke.mq.md b/tests/lib/log-uuid-smoke.mq.md index 92ee815..c6ecfd0 100644 --- a/tests/lib/log-uuid-smoke.mq.md +++ b/tests/lib/log-uuid-smoke.mq.md @@ -15,7 +15,7 @@ import re:lib/re.mq.md > log.debug text="shown-debug" -**id = > uuid.v4** +**id = uuid.v4** **n = > len `id`** > print text=`n` **ok = > re.is_match text=`id` pattern="^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"** diff --git a/tests/lib/数学-数值.mq.md b/tests/lib/数学-数值.mq.md index 5c3e8ff..9e67f05 100644 --- a/tests/lib/数学-数值.mq.md +++ b/tests/lib/数学-数值.mq.md @@ -5,7 +5,7 @@ title: math num + zh # main -**p = > 数学.圆周率** +**p = 数学.圆周率** **t = > type `p`** diff --git a/tests/structure/new-path-stdlib.mq.md b/tests/structure/new-path-stdlib.mq.md new file mode 100644 index 0000000..3af1754 --- /dev/null +++ b/tests/structure/new-path-stdlib.mq.md @@ -0,0 +1,10 @@ +--- +title: zero-argument standard-library knowledge in a value position +import math:lib/math.mq.md +--- + +# main + +**pi = math.pi** + +> print text=`pi`