test: validate executable knowledge syntax across libraries

This commit is contained in:
cflmy committed 2026-10-23 08:47:49 +00:00
1 parent b624084745
commit fc7097bae4
11 files changed
+307 -17

No files matched your search

+1
View File
@@ -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 计划 |
@@ -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、插件/网络依赖及与旧写法的差异。
+110
View File
@@ -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<PathBuf>,
},
/// 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<Vec<std::path::PathBuf>> {
fn walk(dir: &std::path::Path, out: &mut Vec<std::path::PathBuf>) {
@@ -994,6 +1068,42 @@ fn try_main(cli: Cli) -> Result<i32> {
}
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,
+27 -10
View File
@@ -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());
+8 -2
View File
@@ -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`**
+8 -2
View File
@@ -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`**
+1 -1
View File
@@ -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**
+57
View File
@@ -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"));
+1 -1
View File
@@ -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}$"**
+1 -1
View File
@@ -5,7 +5,7 @@ title: math num + zh
# main
**p = > 数学.圆周率**
**p = 数学.圆周率**
**t = > type `p`**
+10
View File
@@ -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`