Files
marqdo/examples/oa2026-showcase/foreign-node.mq.md
T
cflmy 4488a3cb70 feat(migrate): M7 迁移与版本门 — per-file markup + migrate labels + 全仓迁移
原计划的"翻转默认 + 旧形硬报错"不可行:`[键](集合)` 与 `[描述](实现)` 外形相同,
翻转会让 506 处取元静默变义,硬报错又拿不到证据。改为**按文件声明**。

一、per-file markup
- frontmatter `markup: occlusion`(或 `标记: 遮蔽`)决定该文件模式
- load.rs 先取模式,用 parse::expr::with_markup(线程局部压栈)包住解析
- 同一进程可同时加载两种模式的文件(imports);MARQDO_MARKUP 仍作进程默认
- 好处:迁移逐文件、可增量、可回滚,不存在半迁移的静默错义

二、`marqdo migrate labels [--write|--json]`
改写规则:
  [键](集合)      → [键](access(集合, "键"))
  [`名`](集合)    → [名](access(集合, `名`))
  - [项](集合)    → - [项](遍历 集合 为 项)

安全模型:改写 → 重解析 → 证明等价 → 才写
- 原文件按 classic 解析得 AST-A;改写后按 occlusion 解析得 AST-B
- 反归一化 B(标签与键同名且 payload 为 access 的遮蔽还原成 Index)
- Debug(A) == Debug(反归一化(B))(抹掉行号)才写入,否则原文件一字不动

只改代码行(LineKind::Code);表格行只改 **…** 单元格,散文 markdown 链接不碰;
链式索引由内向外改写,已迁移的有守卫不二次改。

三、access 提升为宿主函数 HostFn::Access(u16 id 212)
与旧取元逐字一致(Map 按键 / List 1-based / 缺键 missing map key);
进 HostFn 是为了两个后端共用同一实现,interp 里的特例已删除。

四、顺带修的两处真实语义缺陷
1. payload 继承外层"文本模式":`f text=[k](access(c,k))` 中 access 不被当调用
   → `()` 内永远允许 callee(args)
2. 遮蔽形状判定过宽:`[问候] ([格式化] "Bo")` 误判为遮蔽
   → 要求 `]` 后紧跟 `(`,否则落回方括号调用

五、全仓迁移结果
migrate labels: 256 index, 23 loop, 80 file written;0 文件被等价性拒绝;
迁移后 cargo test --release → 604 passed / 0 failed;再跑迁移幂等。

等价性检查先后抓出 4 类改写 bug(表格散文链接、payload 文本模式、链式索引、
遮蔽与方括号调用混淆),每类都是先拦下再修工具,未污染文件。

测试:6 个单测 + 3 个集成(干跑不写盘 / 写入后运行输出不变且幂等 /
等价失败文件不动);全量 604 passed / 0 failed(M3 后 595 + 9);双后端一致。

文档:doc/design/change-m7-migration.md
2026-10-22 15:33:31 +08:00

2.6 KiB
Raw Blame History


markup: occlusion title: 外联:把 Node 当作文档里的计算车间 description: 一次性执行、持久会话、显式传值,以及可读的结果。 import foreign:lib/foreign.mq.md

main

这份文档要回答一个很具体的问题:同一批订单,按区域汇总之后,总金额分别是多少? 数据已经写在文档里,计算交给 Node,结果回到文档里继续被阅读与断言。

订单 =

@ 区域 金额
1 华东 120
2 华东 300
3 华南 90
4 华南 140
5 华北 220

先做一次性执行。foreign.call 把订单编码成 JSON 放到 stdin, Node 读完、汇总、打印 JSON;外联再把 stdout 解析成 Marqdo 的值。 没有 shell,也没有隐式的 stdin 约定——传什么、读什么,都写在代码里。

汇总代码 =

const incoming = JSON.parse(require('fs').readFileSync(0, 'utf8'));

const byRegion = {};
for (const row of incoming) {
  byRegion[row["区域"]] = (byRegion[row["区域"]] || 0) + Number(row["金额"]);
}

console.log(JSON.stringify(byRegion));

汇总 = > foreign.call code=汇总代码 input=订单

print text=汇总


一次性执行适合「算完就走」。如果想让同一个 Node 内核保留变量, 就显式开启会话、显式设值、显式求值、显式关闭——状态不会藏在某个看不见的 cell 里。

会话 = > foreign.session_open lang="node" > foreign.session_set id=会话 name="orders" value=订单

排序代码 =

const ranked = Object.entries(
  orders.reduce((acc, row) => {
    acc[row["区域"]] = (acc[row["区域"]] || 0) + Number(row["金额"]);
    return acc;
  }, {})
).sort((a, b) => b[1] - a[1]);

console.log(ranked.map(([region, total]) => `${region}: ${total}`).join("\n"));

第一次 = > foreign.session_eval id=会话 code=排序代码

print text=stdout)

内核状态是持续的。下面这段代码在同一个orders上追加一条华北订单, 再重新排序;不需要重新传一遍整张表。

追加代码 =

orders.push({ 区域: "华北", 金额: 80 });

const rankedAgain = Object.entries(
  orders.reduce((acc, row) => {
    acc[row["区域"]] = (acc[row["区域"]] || 0) + Number(row["金额"]);
    return acc;
  }, {})
).sort((a, b) => b[1] - a[1]);

console.log(rankedAgain.map(([region, total]) => `${region}: ${total}`).join("\n"));

第二次 = > foreign.session_eval id=会话 code=追加代码

print text=stdout)

> foreign.session_close id=会话