Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
1bb16dd6db | ||
|
|
58ec2172d6 | ||
|
|
66926e9e0a | ||
|
|
dcf4c05663 | ||
|
|
f47a1e143a | ||
|
|
9cf98a98b5 | ||
|
|
f99d552d87 | ||
|
|
7d49c358c1 | ||
|
|
a32c0cd78f | ||
|
|
0a8f76d9b4 | ||
|
|
4e2419b598 | ||
|
|
f6374d1593 | ||
|
|
9ede4bc63d | ||
|
|
3ae8f2c843 | ||
|
|
e9c1a8a730 | ||
|
|
5554b1642c | ||
|
|
fe15603a91 | ||
|
|
1418742655 | ||
|
|
ed31a2b31d | ||
|
|
56ab52356f | ||
|
|
2e425c3010 |
No files matched your search
@@ -113,8 +113,10 @@ printf '%s\n' '{"id":5,"method":"repair_targets","params":{"code":"contract.arg_
|
||||
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
|
||||
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
|
||||
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
|
||||
| `- [item](coll)` | Foreach (unchanged) |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`); bind with `` `name` = `` then fence |
|
||||
| `$$` + `% marqdo: var=name` | Block formula bind (TeX comment; prefer over empty RHS) |
|
||||
| `- [item](coll)` | Foreach (**preferred**, nestable). Sugar: `- 对`coll`的每一项`item`` / `- for each `item` in `coll`` |
|
||||
| `` | Image writeback form (validated stem.ext / URL); text writeback stays HTML comment |
|
||||
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
|
||||
| Unmarked prose | Comment |
|
||||
|
||||
@@ -138,20 +140,19 @@ Chinese builtins (same functions, no import):
|
||||
|
||||
## Functions, calls, end-body
|
||||
|
||||
Prefer **body-inferred params** and **prose-unified** wording (v0.3). `` + `name` `` still works, but teach the inferred form first:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> greet who=Marqdo
|
||||
**greet who="Marqdo"**
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
*None*
|
||||
When we meet`who`, we **print text="Hello, `who`!"** and close with*None*.
|
||||
```
|
||||
|
||||
- Call: `> name key=value` or `> name value`.
|
||||
- Call: `**fn key="text"**` (bold; quote text literals) or `> fn key=text` (standalone `>`; bare words are text).
|
||||
- Nested helpers use deeper `#` (`##`, `###`, …).
|
||||
- After a helper with only side effects, end with `*None*` / whole-line `**` / `****` when later lines must stay in the outer function. Lone `---` is only a thematic break (skipped).
|
||||
- In bold assigns, prefer bare calls: `**摘要 = 结账摘要 …**` (omit `>`).
|
||||
@@ -163,9 +164,8 @@ Chinese builtins (same functions, no import):
|
||||
**y = x + 2**
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
*n + 1*
|
||||
For input`n`, do **n = n + 1** and return*n*.
|
||||
```
|
||||
|
||||
```markdown
|
||||
@@ -216,7 +216,7 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
|
||||
|
||||
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
|
||||
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
|
||||
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
|
||||
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only. **Engineering Knowledge(EKC)**:`marqdo knowledge|find|reuse|…` + `agent.preflight`(REUSE→ADAPT→CREATE)——见 [engineering-knowledge.md](../../doc/design/engineering-knowledge.md)。
|
||||
4. **Skill Compilation (v2)** — successful runs become `.mq.md` episodes; after enough evidence, `maybe_learn` compiles an executable skill (`llm_free`). Prefer `## run` over bare `## plan` when you want learning.
|
||||
5. **Adaptive Routing (P4)** — router is abstract (`marqdo` / `small-llm` / `llm` / `auto`); `jev` is a compat alias of `small-llm`. Decision via `router_model` (any llm handle). Policy Compilation writes `policies/router.mq.md`.
|
||||
|
||||
|
||||
@@ -126,6 +126,14 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v1.4.1**:view 标注连线——SVG mid→mid(underline 底中 → chip 顶中)· 帧 chip id 对齐 · L→R 密度
|
||||
- **v1.4.1**: View annot leaders — SVG mid→mid (mark bottom-center → chip top-center), frame chip id unify, L→R density
|
||||
- **v1.4.0**:叙述统一——`% marqdo: var=` · 臂/循环体叙述 · foreach 中英糖 · 图片自写回 · view 推断形参
|
||||
- **v1.4.0**: Prose-unified control flow — formula meta bind, arm/loop narrative, foreach sugar, image writeback, inferred-param view
|
||||
- **v1.3.3**:view 文档面 Structure——叙述保真 · 标记面 · 调用/循环帧 · `#mq-view-trace` · 静态站同源
|
||||
- **v1.3.3**: Browse document-surface Structure — narration, markers, call/loop frames, `#mq-view-trace`, static site parity
|
||||
- **v1.3.0**:Engineering Knowledge Compiler——L0–L4 · `reuse`/`find`/`duplicate` · Agent preflight(REUSE→ADAPT→CREATE)
|
||||
- **v1.3.0**: Engineering Knowledge Compiler — L0–L4 catalog, reuse/find/duplicate, Agent preflight (REUSE→ADAPT→CREATE)
|
||||
- **v1.2.0**:Web Artifact(ADR 0007)——Document/Endpoint · `web.serve`/`render`/`inspect` · `ext/data|security|net` · 移除 `compose_*`/`configure`
|
||||
- **v1.2.0**: Web Artifact (ADR 0007) — Document/Endpoint, web.serve/render/inspect, ext/data|security|net, compose_*/configure removed
|
||||
- **v1.1.1**:AI 栈收口——llm `ask`/`stream`/`collect` · Metadata Binding · Skill Compilation + Adaptive Routing · MCP 客户端 + resume · 可选 `plugins/llm`
|
||||
|
||||
+152
@@ -8,6 +8,158 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## v1.4.1 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 叙述标注连线**:Browse / `view output` 中 underline→chip 改为 SVG 正交连线(描述底边中点 → 轨道 → 短竖线 → 值顶边中点);同跨度多帧 chip 共用 annot id;可见 chip 按锚点 L→R;帧切换后重算密度。设计:[view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.1 && cargo build --release
|
||||
marqdo view public/00-welcome.mq.md --no-open
|
||||
marqdo view output public -o /tmp/mq-public
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web # CDN latest → 1.4.1
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 标注几何与帧 chip 对齐),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- 设计缺口文档 [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md):叙述 fence 卡、帧感知 chip 密度、L-leader 几何约定。
|
||||
|
||||
### Fixed
|
||||
- view L-leader:id 与 mark 错配、chip 逆序交叉、border 无色变黑碎段、横线穿过 chip 文字;现为 mid→mid SVG path。
|
||||
- 叙述 fence / 代码卡单层渲染;静态页隐藏 Run;主文函数引用 call chip + leader。
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.4.1**。
|
||||
|
||||
## v1.4.0 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**叙述统一 + 公式 meta + 图片自写回**:块公式 `% marqdo: var=`;分支/循环体与函数体同权叙述;foreach 中英糖;自写回图片 ``(扩展名校验)与 view/静态站同源标记;view 展示推断形参实值;欢迎页迁到 v0.3 叙述面。
|
||||
|
||||
```bash
|
||||
git checkout v1.4.0 && cargo build --release
|
||||
marqdo run tests/markup-v03/formula-meta-var.mq.md
|
||||
marqdo run tests/markup-v03/foreach-narrative.mq.md
|
||||
marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web # CDN latest → 1.4.0
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。Language 层在既有 `formula` / `branch-list` / `loop-list` 上扩展语义(块公式 TeX 注释绑定、臂/循环体叙述、foreach 糖);Runtime:自写回图片形态 + view 推断形参展示。设计:[fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)。
|
||||
|
||||
### Added
|
||||
- **块公式 meta 绑定**:`$$` 内 `% marqdo: var=<ident>`(剥离后解析;可无空 RHS);金样 `tests/markup-v03/formula-meta-var.mq.md`。
|
||||
- **控制流叙述统一**:臂/循环体 `parse_indented_body` 与函数体同权;分支条件行支持叙述前缀与行内 `**…**`;foreach 糖 `- 对…的每一项…` / `- for each … in …`。
|
||||
- **图片自写回**:路径/URL 且扩展名合法 → ``;文本仍 HTML 注释;view / `view output` 同源样式卡与 `<img>`。
|
||||
- **view 推断形参实值**:Browse 展示 body-inferred 参数绑定值;欢迎页 EN/ZH 迁 v0.3 叙述。
|
||||
|
||||
### Fixed
|
||||
- `ext/net/url.encode`:经 `lib/net` 包装,不再直接 `host_*`(金样 `ext_mq_md_never_calls_host`)。
|
||||
- PPA 源包:`ppa-build-source.sh` 本地 `.orig` 已在 build-area 时跳过重复 `cp`。
|
||||
- view:嵌套调用欢迎页与公式/代码卡渲染清理。
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.4.0**;词法评论段遇有序分支臂 / 循环头 / 图片自写回标记时断开,避免吞掉控制流行。
|
||||
|
||||
## v1.3.3 — 2026-10-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**view 文档面 Structure**:Browse 保真叙述与标记面(变量/语句/返回无源码定界符);表/循环/分支结构块;语句后绑定值、分支命中臂、函数多调用与循环迭代下拉(默认末帧);`#mq-view-trace` AI JSON。静态 `marqdo view output` 与 live view **同源渲染**(含用户站 `public/` → gh-pages)。
|
||||
|
||||
```bash
|
||||
git checkout v1.3.3 && cargo build --release
|
||||
marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
marqdo view output public -o public
|
||||
# Ubuntu: sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web # CDN latest → 1.3.3
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 文档面 + 帧选择),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- **Browse Structure 文档面**(`src/view/document.rs` · `annot.rs`):叙述保真、标记面、GFM 表 / `doc-loop` / `doc-branch`、CSS L-leader 标注带。
|
||||
- **StmtEvent / CallFrame / LoopFrame** 静默轨迹:post-stmt 绑定、分支 `call_id`、循环 `分 = 分数表[i] · value`;调用/迭代 picker(源码常显,只滤 chip)。
|
||||
- **`ViewExecutionReport`** JSON(`#mq-view-trace` · `/api/view-trace` · SSE `trace_json`)。
|
||||
- 设计:[view-document-annotations.md](doc/design/view-document-annotations.md) · [view-execution-trace.md](doc/design/view-execution-trace.md) · [view-frame-selection.md](doc/design/view-frame-selection.md);样例 `tests/view/document-annot-demo.mq.md`。
|
||||
|
||||
### Fixed
|
||||
- 多调用分支 taken 混叠;调用切换误藏未执行臂源码;循环头重复 chip。
|
||||
|
||||
### Changed
|
||||
- CLI / wasm / `ext/VERSION` **同步 1.3.3**;静态导出与 live view 共用 `build_file_view` → 文档面。
|
||||
|
||||
## Ext pack v1.3.2 — 2026-10-13
|
||||
|
||||
### Highlights
|
||||
|
||||
**Trailing slash 路由修复(CLI 仍为 v1.3.0)**:Go `ServeMux` 精确匹配导致 `/post/foo/`(带尾部斜杠)落入 404。新增 `withStripTrailingSlash` 中间件作为最外层 handler wrapper,所有下游中间件(RBAC、Tenant、路由)均看到规范化路径。覆盖静态路由、动态路由、根路径、查询参数保留。
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.3.2
|
||||
# 或:MARQDO_EXT_VERSION=1.3.2 marqdo ext add web
|
||||
```
|
||||
|
||||
### Fixed
|
||||
|
||||
- **web**: `/post/foo/` trailing slash now routes the same as `/post/foo` (dynamic and static routes). Root `/` unchanged. Query strings preserved after normalization.
|
||||
|
||||
## Ext pack v1.3.1 — 2026-10-08
|
||||
|
||||
### Highlights
|
||||
|
||||
**OIDC 路径型 `redirect_uri`(CLI 仍为 v1.3.0)**:`redirect_uri=/oidc/callback` 按请求 Host / `X-Forwarded-*` 拼绝对回调,写入会话供 token 交换;可选 `redirect_origins` allowlist。apex / www 多域名无需写死单一绝对 URI。
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.3.1
|
||||
# 或:MARQDO_EXT_VERSION=1.3.1 marqdo ext add web
|
||||
```
|
||||
|
||||
### Added
|
||||
- **路径型 redirect_uri**:绝对 URL 行为不变;路径模式解析 public origin,session 键 `oidc_redirect_uri`。
|
||||
- **`redirect_origins` / `回调来源`**:逗号分隔 origin allowlist(路径模式)。
|
||||
- **ABI**:`web_app_oidc` 透传 `redirect_origins`;`ext/security/oidc.attach` 文档同步。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.3.1**(`ext/VERSION`);与 CLI **v1.3.0** 可独立安装。
|
||||
|
||||
## v1.3.0 — 2026-09-28
|
||||
|
||||
### Highlights
|
||||
|
||||
**Engineering Knowledge Compiler(EKC)**:把仓库投影为 AI 可查询的工程知识系统——L0–L4 Catalog、Capability / Decision / Constraint / Failure、知识图、Reuse Preflight(REUSE→ADAPT→CREATE)与 Context Pack。本版 CLI 与扩展包 **同步为 1.3.0**。
|
||||
|
||||
- **杀手命令**:`marqdo reuse "task"` / `find` / `duplicate` / `impact` / `conflicts` / `stale` / `verify` / `knowledge`
|
||||
- **Agent**:`agent.preflight` · `agent_eng_*`;`plan … eng_preflight=True` 在造轮子前强制 EFI
|
||||
- **投影**:`.marqdo/catalog|knowledge|graph|agent/` + `engineering.yaml`;`catalog` 默认挂钩 EKC
|
||||
- **示例 / 金样**:`examples/engineering-knowledge/` · `tests/engineering/` · `tests/ext/eng-preflight.mq.md`
|
||||
|
||||
```bash
|
||||
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
|
||||
git checkout v1.3.0 && cargo build --release
|
||||
marqdo knowledge . -o .marqdo
|
||||
marqdo reuse "resolve configuration"
|
||||
marqdo ext add agent
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(知识编译器 + CLI + agent 插件),不触碰语言标记。
|
||||
|
||||
### Added
|
||||
- **`src/knowledge/` EKC**:L0–L4 IR、指纹、能力推导、图边、compile、find/reuse/preflight、impact/lifecycle/duplicate、metrics、policy、learn。
|
||||
- **CLI**:`knowledge` · `find` · `reuse` · `impact` · `conflicts` · `stale` · `duplicate` · `verify`;`catalog`/`sync` 默认编译 EKC(`--no-knowledge` 可关)。
|
||||
- **Agent**:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`;`ext/ai` `## preflight` + `plan eng_preflight`。
|
||||
- **规范**:`doc/design/engineering-knowledge.md`;提案叙事 `doc/next/008.md`(已实现标注)。
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
- **OKF type 注册表**扩展 Capability/Decision/Constraint/Failure/Context Pack/Policy 等([okf.md](doc/design/okf.md))。
|
||||
- **核心表面 Δ**:**无增删**。
|
||||
|
||||
## v1.2.0 — 2026-09-28
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+2
-2
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "1.1.1"
|
||||
version = "1.4.1"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -603,7 +603,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.1.1"
|
||||
version = "1.4.1"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "1.2.0"
|
||||
version = "1.4.1"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
|
||||
@@ -6,7 +6,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -123,6 +123,13 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
|
||||
# Engineering Knowledge Compiler(L0–L4 能力目录 / 复用门闩)
|
||||
marqdo knowledge [PATH] -o OUT_DIR
|
||||
marqdo find "authentication"
|
||||
marqdo reuse "implement oauth login"
|
||||
marqdo duplicate [--fail]
|
||||
marqdo verify
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
@@ -130,7 +137,7 @@ marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
|
||||
| `-o` / `--out` | `.marqdo` | 输出目录 |
|
||||
|
||||
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
`catalog` 成功后默认再跑 EKC(`--no-knowledge` 可关)。产物示例:`catalog.yaml`、`engineering.yaml`、`catalog/capabilities/`、`graph/graph.json`。设计见 [engineering-knowledge.md](doc/design/engineering-knowledge.md) · [catalog-cli.md](doc/design/catalog-cli.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
|
||||
智能体框架横向调研(LangGraph / CrewAI / 厂商 SDK 等 vs Marqdo 文档驱动优势):[agent-frameworks-and-marqdo.md](doc/research/agent-frameworks-and-marqdo.md) · 优化路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。
|
||||
|
||||
@@ -142,23 +149,28 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v1.2.0)
|
||||
## 现状(v1.4.1)
|
||||
|
||||
- **view 标注连线(v1.4.1)**:underline→chip SVG mid→mid(底边中点→轨道→短竖线→顶边中点)· 帧 chip 共用 id · L→R 密度 · [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)
|
||||
- **叙述统一 / 公式 meta / 图片自写回(v1.4.0)**:`% marqdo: var=` 块公式绑定 · 臂/循环体叙述与 foreach 中英糖 · `` 图片自写回 · view 推断形参实值 · [fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)
|
||||
- **view 文档面(v1.3.3)**:Browse Structure 叙述保真 · 标记面 · 分支/循环帧下拉 · AI `#mq-view-trace` · 静态 `view output` / gh-pages 同源 · [view-document-annotations.md](doc/design/view-document-annotations.md)
|
||||
- **Engineering Knowledge(v1.3.0)**:EKC L0–L4 · `marqdo knowledge|find|reuse|duplicate|verify|…` · Agent `preflight` / REUSE→ADAPT→CREATE · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
|
||||
- **Web Artifact(v1.2.0 · ADR 0007)**:Document/Endpoint 一等公民(`type: web|endpoint`)· facade `page`/`route`/`serve`/`render`/`inspect`/`use` · Resource 拆到 `ext/data`/`security`/`net` · 统一 View 表 · 破坏性移除 `compose_*`/`configure`
|
||||
- **AI 栈(v1.1.1)**:`ext/ai/llm` 语义 `ask`/`stream`/`collect` · Artifact Metadata Binding(`${env|arg|sys|secret}`)· Agent Skill Compilation + Adaptive Routing · MCP stdio 客户端 + resume 检查点 · 可选 `plugins/llm` Transport ABI
|
||||
- **AI 原生闭环(v1.1.0)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
|
||||
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
|
||||
- **`marqdo view`**:文档浏览器(**文档面** Structure + 标注 / 调用·循环帧 + 函数大纲/搜索 + Execution + Variables 浮窗;`view output` 同构)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页(默认挂钩 EKC)
|
||||
- **`marqdo knowledge` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`**:Engineering Knowledge Compiler([engineering-knowledge.md](doc/design/engineering-knowledge.md))
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6** + **Mid2 M7–M10**(datetime/url/toml/html/fs++/stats/log.fields 等,见 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md))
|
||||
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
|
||||
- **`web`**:**Artifact 模型(ADR [0007](doc/adr/0007-web-document-endpoint.md))** — `type: web|endpoint` Document/Endpoint;facade `page`/`route`/`serve`/`render`/`inspect`/`use`;Resource 在 `ext/data` · `ext/security` · `ext/net`;设计 [ext-web-artifact.md](doc/design/ext-web-artifact.md);原生 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md));示例 [marqdo-blog](examples/marqdo-blog/) · [web-client-site](examples/web-client-site/) · [anlian-mq](examples/anlian-mq/)
|
||||
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
|
||||
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
|
||||
- **`agent`**:A1–A4 + **MCP Server/Client stdio** + Skill Compilation + Adaptive Routing + resume;宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
|
||||
- **`agent`**:A1–A4 + **MCP Server/Client stdio** + Skill Compilation + Adaptive Routing + resume + **Engineering preflight**(`agent.preflight` / `eng_preflight`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md) · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
|
||||
- **`llm`**:语义 `ask`/`stream`/`collect`(OpenAI/Ollama;可选原生 `plugins/llm`)
|
||||
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
|
||||
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg,llm}`(`web` 为 Go;其余为 Rust)
|
||||
@@ -167,7 +179,7 @@ marqdo catalog public -o .marqdo
|
||||
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v1.2.0)
|
||||
### 如何使用最新 Marqdo(v1.4.1)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -182,7 +194,7 @@ marqdo catalog public -o .marqdo
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v1.2.0 # 或留在 main
|
||||
git checkout v1.4.1 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -221,7 +233,7 @@ marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.2.0
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.4.1
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.2.0"
|
||||
version = "1.4.1"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
Vendored
+31
@@ -1,3 +1,34 @@
|
||||
marqdo (1.4.1-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.1: View annot leaders — SVG mid-to-mid (mark bottom-center
|
||||
to chip top-center), unify frame chip ids, L-to-R chip density.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 15 Oct 2026 20:40:00 +0800
|
||||
|
||||
marqdo (1.4.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.4.0: Prose-unified control flow — block formula % marqdo: var=,
|
||||
arm/loop narrative + foreach sugar, image writeback ,
|
||||
view inferred-param values; welcome pages on v0.3 prose surface.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 15:53:00 +0800
|
||||
|
||||
marqdo (1.3.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.3.3: Browse document-surface Structure — narration-preserving
|
||||
markers, branch/loop frame pickers, ViewExecutionReport JSON; static
|
||||
view output / gh-pages share the same render path as live view.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 13:20:00 +0800
|
||||
|
||||
marqdo (1.3.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.3.0: Engineering Knowledge Compiler (EKC) — L0–L4 catalog,
|
||||
marqdo knowledge/find/reuse/duplicate/verify, Agent preflight
|
||||
(REUSE→ADAPT→CREATE), graph + context packs.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Mon, 28 Sep 2026 16:50:00 +0800
|
||||
|
||||
marqdo (1.2.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.2.0: Web Artifact rewrite (ADR 0007) — Document/Endpoint/Resource,
|
||||
|
||||
@@ -25,6 +25,7 @@
|
||||
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
|
||||
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单(早期方向) |
|
||||
| [design/okf.md](design/okf.md) | **Marqdo OKF 实现规范**(catalog v0 + 任务知识包) |
|
||||
| [design/engineering-knowledge.md](design/engineering-knowledge.md) | **Engineering Knowledge Compiler(EKC)**:L0–L4、reuse、EFI |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
|
||||
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
|
||||
|
||||
@@ -23,15 +23,20 @@ YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
# 别名(与早期草案一致)
|
||||
marqdo sync [PATH] -o OUT_DIR
|
||||
# 跳过 Engineering Knowledge 投影(仅旧式 catalog)
|
||||
marqdo catalog [PATH] -o OUT_DIR --no-knowledge
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
|
||||
| `--no-knowledge` | off | 不跑 EKC;默认在 catalog 成功后编译 L0–L4 / graph |
|
||||
|
||||
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
|
||||
|
||||
Engineering Knowledge 命令见 [engineering-knowledge.md](engineering-knowledge.md)(`find` / `reuse` / `duplicate` / …)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 生成物
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
# Engineering Knowledge Compiler(EKC)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted(v1 已落地)** |
|
||||
| 日期 | 2026-09-28 |
|
||||
| 提案 | [next/008.md](../next/008.md) |
|
||||
| 相关 | [okf.md](okf.md) · [catalog-cli.md](catalog-cli.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
## 1. 定位
|
||||
|
||||
Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识系统。Source of Truth 仍是 `*.mq.md`;`.marqdo/**` 是 GENERATED 投影。
|
||||
|
||||
```text
|
||||
.mq.md ──► EKC ──► Executable + Catalog L0–L4 + Graph + Context Pack
|
||||
│
|
||||
▼
|
||||
Agent preflight (REUSE → ADAPT → CREATE)
|
||||
```
|
||||
|
||||
**Engineering First Information (EFI)**:生成代码前先获得已有能力、约束、决策、失败经验与推荐复用。
|
||||
|
||||
## 2. 五层 Catalog
|
||||
|
||||
| 层 | 内容 | 落盘 |
|
||||
|----|------|------|
|
||||
| L0 Repository | 语言/规模 | `.marqdo/catalog/repository.mq.md` |
|
||||
| L1 Module | imports/exports/responsibility | `.marqdo/catalog/modules/` |
|
||||
| L2 Symbol | signature/calls/fingerprint | `.marqdo/catalog/symbols/` |
|
||||
| L3 Capability | 工程能做什么 | `.marqdo/catalog/capabilities/` |
|
||||
| L4 Knowledge | Decision/Constraint/Failure/… | `.marqdo/knowledge/{decisions,constraints,…}/` |
|
||||
|
||||
既有 `marqdo catalog` 根级 `catalog.yaml` / `index.md` / `modules/` / `concepts/` **保留**;`catalog` 成功后默认再跑 EKC(`--no-knowledge` 可关)。
|
||||
|
||||
## 3. 知识类型(OKF `type`)
|
||||
|
||||
| type | 含义 |
|
||||
|------|------|
|
||||
| `Capability` / `Function` | 能力与符号投影 |
|
||||
| `Decision` | 为什么这样做 |
|
||||
| `Constraint` | 必须/禁止 |
|
||||
| `Failure` / `AntiPattern` | 负面知识 |
|
||||
| `Pattern` / `Migration` / `Fact` | 模式、迁移、事实 |
|
||||
| `Marqdo Context Pack` | Agent 上下文制品 |
|
||||
| `Marqdo Policy` | 复用决议编译结果 |
|
||||
| `Marqdo Engineering Knowledge` | 总览 / `engineering.yaml` |
|
||||
|
||||
未知 type 优雅降级(可读,不专属逻辑)。
|
||||
|
||||
## 4. 图边
|
||||
|
||||
`implements` · `uses` · `depends_on` · `tested_by` · `documented_by` · `constrained_by` · `decided_by` · `supersedes` · `conflicts_with` · `deprecated_by` · `derived_from` · `failed_by` · `related_to`
|
||||
|
||||
落盘:`.marqdo/graph/graph.json` · `edges.json` · `index.json`。
|
||||
|
||||
## 5. CLI
|
||||
|
||||
```bash
|
||||
marqdo knowledge [PATH] -o .marqdo # compile(默认)
|
||||
marqdo knowledge preflight "task"
|
||||
marqdo knowledge record REUSE
|
||||
marqdo knowledge learn --task ... --failure ...
|
||||
marqdo find "authentication"
|
||||
marqdo reuse "implement oauth login"
|
||||
marqdo impact path/to/file.mq.md
|
||||
marqdo conflicts | stale | duplicate [--fail] | verify
|
||||
```
|
||||
|
||||
统一 `--json`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
|
||||
|
||||
## 6. Reuse 协议
|
||||
|
||||
三态:**REUSE → ADAPT → CREATE**(硬顺序)。Reuse budget:`min_candidates` / `allow_create_after`。仅 `create_allowed: true` 时允许盲生成。
|
||||
|
||||
## 7. Context Pack
|
||||
|
||||
`.marqdo/agent/contexts/task-<id>.mq.md`:Task / Existing Capabilities / APIs / Constraints / Decisions / Failures / Recommended / Forbidden。
|
||||
|
||||
## 8. Agent
|
||||
|
||||
- Plugin:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`
|
||||
- Facade:`agent.preflight` · `agent.eng_reuse` · `agent.eng_record`
|
||||
- `agent.plan … eng_preflight=True` 在 agent-kb 之前跑 EFI;缺知识图时 `missing_knowledge` 放行(兼容纯 agent-kb 测试)
|
||||
|
||||
## 9. 指标
|
||||
|
||||
`.marqdo/agent/episodes/reuse_metrics.json`:`reuse_ratio` / `adapt_ratio` / `novel_ratio` / `duplication_rate`。
|
||||
|
||||
## 10. 原则(五条)
|
||||
|
||||
1. Discover before Create
|
||||
2. Reuse before Adapt
|
||||
3. Adapt before Duplicate
|
||||
4. Verify before Promote
|
||||
5. Code changes update knowledge
|
||||
|
||||
**不做**:以向量库为知识模型;embedding 仅可选检索实现,默认关闭。Hybrid = lexical + symbol + capability + graph。
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**engineering-knowledge.md**](engineering-knowledge.md)(**EKC / EFI preflight**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
|
||||
## 0. 为什么要改掉旧方案
|
||||
|
||||
@@ -167,8 +167,9 @@ ext/
|
||||
**分层纪律(硬规则,勿破)**:
|
||||
|
||||
1. `ext/**/*.mq.md` **禁止**出现任何 `host_*` / `host_` 调用。
|
||||
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
|
||||
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
|
||||
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …;以及 EKC:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
|
||||
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF / EKC 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
|
||||
4. **Engineering preflight**:`agent.preflight` / `plan … eng_preflight=True` 在 agent-kb 之前解析 REUSE/ADAPT/CREATE(见 [engineering-knowledge.md](engineering-knowledge.md))。缺 `.marqdo` 知识图时返回 `missing_knowledge` 并放行,以兼容纯任务包测试。
|
||||
4. 进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。
|
||||
|
||||
官方 `ext/ai/` 用 `lib/*` 包装或插件注册名;见 [module-namespace.md](module-namespace.md) §8 · [ext-abi.md](ext-abi.md)。
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# 块公式元数据绑定 · 控制流叙述统一
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | Active |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 块公式 `% marqdo: var=`
|
||||
|
||||
在 `$$…$$` 块内用 **TeX 行注释**声明绑定名(渲染通常不可见;运行时剥离后解析公式体):
|
||||
|
||||
```markdown
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
```
|
||||
|
||||
- 指令:`% marqdo:` + 空白 + `var=<ident>`;未知键 → Error。
|
||||
- 可无前置 `` `f` = ``;若同时写空 RHS 与 `var=`,**同名允许、异名 Error**。
|
||||
- **保留**旧空 RHS + 后随 `$$`。
|
||||
- **不做**:行内 `$% marqdo:…$`;\`\`\` 代码围栏内语言注释 meta(本波)。
|
||||
- 行内公式继续传统绑定:`` `g` = $x+1$ ``(单 `$…$` → `formula`)或 `` `g` = $$x+1$$ ``。
|
||||
|
||||
无名叙述区 `$$` 仍仅展示;可执行区裸块既无空 RHS 又无 `var=` → Error。
|
||||
|
||||
---
|
||||
|
||||
## 2. 臂 / 循环体叙述(与函数体同权)
|
||||
|
||||
`parse_indented_body` 与函数体相同:消费 `` `名` `` / `**代码**` / `*返回*`;纯叙述跳过。
|
||||
斜体返回结束**当前臂或当前循环体**,不结束外层函数。
|
||||
|
||||
---
|
||||
|
||||
## 3. 循环头
|
||||
|
||||
| 面 | 写法 | 说明 |
|
||||
|----|------|------|
|
||||
| **推荐** | `- [项](xs)` / `- [`项`](`xs`)` | 支持嵌套 |
|
||||
| 中文糖 | `- 对`xs`的每一项`项`` | 可选后缀「遍历」 |
|
||||
| 英文糖 | `- for each `item` in `xs`` | 大小写不敏感 `for each` / `in` |
|
||||
|
||||
糖与链接头语义相同,可混用嵌套。
|
||||
|
||||
---
|
||||
|
||||
## 4. 分支条件行叙述
|
||||
|
||||
结构行仍以 `1.` / `2.` 开头。条件提取顺序:
|
||||
|
||||
1. 整段可解析为表达式(现状);
|
||||
2. 行内粗体代码条件 `**`n` > 0**`;
|
||||
3. 剥离「当/若/如果/when/if」与「时/则」后,将「大于/小于/等于…」映射为运算符再解析。
|
||||
|
||||
else:`N. *`(可夹「否则」等叙述,条件位仍为 `*`)。
|
||||
禁止无标记自然语言整句当条件。
|
||||
@@ -215,7 +215,9 @@ v0.3:
|
||||
| 表达式 `[键](集合)` | **取元**(与 foreach 同形;见 [collection-access-link.md](collection-access-link.md)) |
|
||||
| `修饰… [函数名] 实参…` | **方括号标记调用**(前置修饰 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md)) |
|
||||
| `` 集合[^键] `` | **过渡**:旧脚注取元(仍可用) |
|
||||
| ` ```lang ` | 外联(不变) |
|
||||
| ` ```lang ` | 外联(不变;绑定仍用 `` `名` = `` + 围栏) |
|
||||
| `$$` 内 `% marqdo: var=名` | 块公式绑定([fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)) |
|
||||
| `- 对`集`的每一项`项`` / `for each` | foreach 叙述糖;推荐 `- [项](集)` |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;模块顶与函数体内相同) |
|
||||
| 整行恰 `**` 或 `****` / `*None*` / `*无*` | **空返回**并结束本函数体(见 §7.2) |
|
||||
|
||||
|
||||
+10
-5
@@ -143,13 +143,18 @@ Marqdo 对齐的判断是:
|
||||
|
||||
| `type` | 状态 | 含义 | 主要生产者 |
|
||||
|--------|------|------|------------|
|
||||
| `Marqdo Catalog` | **v0 已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
|
||||
| `Marqdo Module` | **v0 已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
|
||||
| `Marqdo Task` | **规范已定;实现待做** | 一项可匹配的任务意图 | `plan` 晋升 |
|
||||
| `Marqdo Agent Skill` | **规范已定;实现待做** | 指向可执行工作簿的技能 | `plan` 晋升 |
|
||||
| `Marqdo Catalog` | **已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
|
||||
| `Marqdo Module` | **已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
|
||||
| `Marqdo Task` | **已实现** | 一项可匹配的任务意图 | `plan` 晋升 |
|
||||
| `Marqdo Agent Skill` | **已实现** | 指向可执行工作簿的技能 | `plan` 晋升 |
|
||||
| `Capability` / `Function` | **EKC** | 工程能力 / 符号投影 | `marqdo knowledge` |
|
||||
| `Decision` / `Constraint` / `Failure` / `AntiPattern` / `Pattern` / `Migration` / `Fact` | **EKC** | L4 工程知识 | 源 frontmatter + learn |
|
||||
| `Marqdo Context Pack` | **EKC** | Agent EFI 上下文制品 | `reuse` / `preflight` |
|
||||
| `Marqdo Policy` | **EKC** | 复用决议编译 | `marqdo reuse` |
|
||||
| `Marqdo Engineering Knowledge` | **EKC** | 工程知识总览 | `engineering.yaml` / `index.mq.md` |
|
||||
| 其他 | 开放 | 第三方/未来扩展 | — |
|
||||
|
||||
**不**引入 Google OKF 的 `Metric` / BigQuery 表类型作为 Marqdo 核心词汇;需要时可由用户包自行使用,运行时降级。
|
||||
完整 EKC 规范见 [engineering-knowledge.md](engineering-knowledge.md)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -34,7 +34,16 @@
|
||||
|
||||
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
|
||||
|
||||
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
|
||||
**推荐(块内元数据)**:在 `$$` 体内用 TeX 注释声明变量(见 [fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)):
|
||||
|
||||
````markdown
|
||||
$$
|
||||
% marqdo: var=f
|
||||
sin(x) + x
|
||||
$$
|
||||
````
|
||||
|
||||
**兼容**:空 RHS 赋值后跟展示数学块(与 `` `xs` = `` 后跟表格一致):
|
||||
|
||||
````markdown
|
||||
# main
|
||||
@@ -52,13 +61,14 @@ $$
|
||||
也支持:
|
||||
|
||||
- 单行围栏:下一行 `$$x^2 - 2$$`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`(历史面)
|
||||
- 行内:`` `g` = $x+1$ `` 或 `` `g` = $$x+1$$ ``
|
||||
|
||||
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
|
||||
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区裸 `$$` 若既无空 RHS 又无 `% marqdo: var=` → 报错。
|
||||
|
||||
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
|
||||
**行内 `$…$`:** 传统绑定 `` `名` = $…$ `` → `formula`;**不**使用 `$% marqdo:…$`(会破坏 Markdown/TeX 识别)。
|
||||
|
||||
### 2.3 从文本构造
|
||||
|
||||
|
||||
@@ -8,9 +8,11 @@
|
||||
|
||||
## 定位
|
||||
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` → `marqdo view`(及静态 `view output`)在对应语句下显示 **output-card**,并在源码面用 **writeback** 样式标出块本身。
|
||||
|
||||
## 存储格式
|
||||
## 存储格式(两种,可并存)
|
||||
|
||||
### 1. HTML 注释(文本 / 结构化输出)
|
||||
|
||||
```markdown
|
||||
*`n` = > len value=`xs` *
|
||||
@@ -30,11 +32,26 @@ pending
|
||||
-->
|
||||
```
|
||||
|
||||
- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
|
||||
### 2. Markdown 图片(生成图 / 审计友好)
|
||||
|
||||
当 `value` **看起来像图片引用**(扩展名 `.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` / `.svg` / …,或 `data:image/…`)时,`record` **自动**写成:
|
||||
|
||||
```markdown
|
||||

|
||||

|
||||
```
|
||||
|
||||
- 普通 Markdown 预览即可看见图;view / 静态站额外加 writeback 标记与 output-card 中的 `<img>`。
|
||||
- 非图片路径仍走注释块;把非图片硬写成 `` 时扫描会忽略(校验失败)。
|
||||
- `list` / `scan_path` 结果带 `kind`: `comment` | `image`。
|
||||
|
||||
### 共用规则
|
||||
|
||||
- 标记字为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
|
||||
- 默认在**调用行下方**插入或替换紧邻**无键**块
|
||||
- `at_end=true`:替换文件末尾的**无键**块
|
||||
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。
|
||||
- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。
|
||||
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽;`ensure` 在缺失时写入占位且不覆盖已有正文
|
||||
- `line=` / `行=`:显式锚点行号;主机侧有全局互斥锁
|
||||
|
||||
### 替换跨度与空行
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
|
||||
| 相关 | [view.md](view.md) · [view-static-interactive.md](view-static-interactive.md)(静态交互 / 公式代码视觉 · Proposal) · 源目录 [`public/`](../../public/) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,14 +4,14 @@
|
||||
|---|---|
|
||||
| 状态 | **v1(独立 debug 页)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [view-document-annotations.md](view-document-annotations.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
|
||||
## 分工
|
||||
|
||||
| 命令 | 角色 |
|
||||
|------|------|
|
||||
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
|
||||
| `marqdo view` | 文档浏览器:**叙述保真文档面** Structure + Execution + Source;函数大纲与搜索;跑后引出标注;**无断点**(见 [view-document-annotations.md](view-document-annotations.md)) |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;AST Structure + BP;**仅 live** |
|
||||
|
||||
静态 `gh-pages` / `view output` **不能**真断点。
|
||||
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
# View:文档面与结果引出标注
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view.md](view.md) · [view-debug.md](view-debug.md) · [view-markup-surface.md](view-markup-surface.md) · [view-execution-trace.md](view-execution-trace.md) · [view-frame-selection.md](view-frame-selection.md) · [view-prose-annot-gaps.md](view-prose-annot-gaps.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
`.mq.md` 是叙述与程序的同一载体。`marqdo view` 的 Structure 必须**保真叙述**,并在可执行标记旁展示运行结果。
|
||||
|
||||
旧 Browse Structure 用 AST 卡片重建语句,并用 `emit_comments` 只插入**语句行之前**的注释。当叙述与 `**…**` / `*…*` / `` `名` `` 在同一行时,该行被 Stmt 占用,叙述被丢弃——信息密度接近 debug,不适合文档浏览。
|
||||
|
||||
## 2. 模式分工
|
||||
|
||||
| 命令 | Structure | 叙述 | 结果 |
|
||||
|------|-----------|------|------|
|
||||
| `marqdo view`(Browse) | **文档面** | 保留并为主 | 跑后引出标注(callout + CSS L-leader) |
|
||||
| `marqdo debug` | AST 卡片 + BP gutter | 弱化/可折叠 | Variables / 步进;不做文档 callout |
|
||||
|
||||
断点与逐步执行**仅**在 debug。静态 `view output` 与 live view **共用** Browse 文档面渲染。
|
||||
|
||||
## 3. 视觉语法
|
||||
|
||||
```
|
||||
文本段…… `变量` …… **语句** …… *返回*
|
||||
━━━━━
|
||||
│
|
||||
└──→ 结果标注
|
||||
```
|
||||
|
||||
1. 叙述正文正常排版(Markdown)。
|
||||
2. 可执行片段高亮,并带底部分割线(underline)。
|
||||
3. 段落下方 **annotation band** 放结果 callout。
|
||||
4. **CSS L-leader**(绝对定位小盒 + `border-left` + `border-bottom`)连接锚点与 callout。**不使用 SVG。**
|
||||
5. 拥挤 / 极窄屏 / `prefers-reduced-motion`:取消长横折,改为编号 keyed 列表。
|
||||
|
||||
关联强度(递减):同色 underline + callout 色条 + label → CSS L-leader → keyed 编号。
|
||||
|
||||
对齐 [view.md](view.md) HIG:系统字体、无外链、浅色、克制装饰。
|
||||
|
||||
## 4. 文档面渲染
|
||||
|
||||
实现:`src/view/document.rs`;Browse 入口经 `render_module_structure` 调用。
|
||||
|
||||
| 源内容 | 呈现 |
|
||||
|--------|------|
|
||||
| 纯叙述段 | Markdown HTML;无 `comment` badge / 厚卡片 |
|
||||
| 含 `ProseBit` 的行 | 原文保留;Decl / BoldCode / ItalicReturn 包 `mark.mq-anchor`(字节偏移来自 `scan_prose_line`) |
|
||||
| 整行结构(`#` / `>` / `-` / `1.` / 表) | 表面语法保真(见 [view-markup-surface.md](view-markup-surface.md));整句可作锚点 |
|
||||
| 函数标题 | 轻量 heading + `id="fn-{line}"`(大纲跳转不变) |
|
||||
|
||||
Debug 仍走 `render_module_structure_mode(..., Debug)` 的 AST 卡片路径。
|
||||
|
||||
## 5. ViewAnnot
|
||||
|
||||
跑后(或 `--no-exec` 时为空)组装标注集,嵌入文档面 `data-*` 与 band HTML。
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `id` | 稳定短 id(页内唯一) |
|
||||
| `kind` | `bind` · `return` · `call` · `expr` · `branch` · `loop` · `writeback` |
|
||||
| `anchor_line` | 1-based 源行 |
|
||||
| `anchor_byte_start` / `anchor_byte_end` | 行内字节范围(可选;整行锚点可省略 end) |
|
||||
| `label` | 短标题(名 / return / arm / loop) |
|
||||
| `value` | 截断显示 |
|
||||
| `detail` | 完整文本(inspect) |
|
||||
|
||||
| kind | 数据来源 | 锚点 |
|
||||
|------|----------|------|
|
||||
| `bind` | **StmtEvent post-stmt**(赋值执行后的值);禁止用入口终态回填初始化行 | 该赋值行 |
|
||||
| `return` | 返回事件或入口返回 | ItalicReturn / Return |
|
||||
| `call` / `expr` / `writeback` | writeback 槽、调用摘要 | 语句行或 BoldCode |
|
||||
| `branch` | `ViewTrace`:命中 arm、次数 | 条件 / arm |
|
||||
| `loop` | `ViewTrace`:迭代次数、末次 item | While / ForEach 头 |
|
||||
|
||||
标记面、结构块、多调用帧与 AI JSON 见 [view-execution-trace.md](view-execution-trace.md)。
|
||||
|
||||
`ViewTrace` 由 tree 解释器在 capture 时静默收集,**不**写入 stderr;与 `trace_eval` 调试轨迹分离。Bytecode 后端可暂无 trace(标注降级为 writeback)。
|
||||
|
||||
## 6. 布局与密度
|
||||
|
||||
- 每段默认最多 **4** 个常显 callout;其余 hover / 「show more」。
|
||||
- Leader:按锚点 x 排序 callout,避免交叉;窄屏改为短竖线 + 堆叠。
|
||||
- 客户端:`ResizeObserver` 重算 leader 盒的 `left/top/width/height`。
|
||||
- 静态导出:页载 JS 跑一次布局。
|
||||
|
||||
右侧 **Variables** 仍为全集绑定;callout 为就地摘要,点击可打开同一 inspect。
|
||||
|
||||
## 7. 非目标
|
||||
|
||||
- 不在 view 内做断点 / 单步(见 [view-debug.md](view-debug.md))。
|
||||
- 不新增作者侧标注 DSL / frontmatter 指令。
|
||||
- 不引入外链字体、npm 组件或 SVG leader。
|
||||
- 不把 DB/auth 等塞进 view 壳层。
|
||||
|
||||
## 8. 验收
|
||||
|
||||
1. `inc-prose.mq.md`:叙述「对于输入变量…」完整可见;`n` / `n=n+1` / 返回高亮。
|
||||
2. 跑完后:值经 underline + CSS L-leader 连到下方标注(无 SVG)。
|
||||
3. 分支/循环样例:可见命中 arm 与迭代次数(有 ViewTrace 时)。
|
||||
4. `marqdo debug` 仍为 AST + 断点;叙述不抢主视觉。
|
||||
5. 无外链字体/新依赖;`view output` 可离线打开。
|
||||
|
||||
## 9. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:文档面、ViewAnnot、CSS L-leader、与 debug 分工 |
|
||||
| 2026-10-15 | bind = post-stmt;交叉链 view-execution-trace |
|
||||
@@ -0,0 +1,103 @@
|
||||
# View:执行轨迹与文档面保真
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [view.md](view.md) · [view-markup-surface.md](view-markup-surface.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`marqdo view` Browse Structure 必须同时做到:
|
||||
|
||||
1. **标记面**:变量名 / 可执行语句 / 返回值按表面渲染(无源码定界符字面量)。
|
||||
2. **结构块**:GFM 表、循环(`-`)、分支(`1.`)有正确 HTML 与缩进。
|
||||
3. **语句后值**:赋值行标注该语句执行后的值,不用入口终态回填。
|
||||
4. **执行臂**:高亮实际走的分支臂。
|
||||
5. **多调用帧**:同函数多次调用可用下拉切换经历。
|
||||
6. **AI 可读**:与 HTML 同源的 `ViewExecutionReport` JSON。
|
||||
|
||||
Debug 仍用 AST 卡片 + 断点;不做文档 callout。
|
||||
|
||||
## 2. 标记面
|
||||
|
||||
| 源标记 | 显示(无定界符) | class |
|
||||
|--------|------------------|-------|
|
||||
| `` `名` `` / `` `名`=默认 `` | `名`(默认次要后缀) | `mq-anchor mq-decl` |
|
||||
| `**…**`(可执行) | 内层文本 | `mq-anchor mq-code` |
|
||||
| `*…*`(返回) | 内层文本 | `mq-anchor mq-return` |
|
||||
|
||||
`data-byte-start/end` 仍为源码字节偏移(供 CSS L-leader)。软强调不进 anchor。
|
||||
|
||||
## 3. 结构块
|
||||
|
||||
| 块 | 呈现 |
|
||||
|----|------|
|
||||
| GFM 表 | `<table class="doc-table">` |
|
||||
| `-` 循环 | `<ul class="doc-loop">`,体按源缩进 `--doc-indent` |
|
||||
| `1.` 分支 | `<ol class="doc-branch">`;命中 `arm-taken`,未走 `arm-miss` |
|
||||
| 公式 / 外联代码 | 现有 formula-card / code-card |
|
||||
| `>` 调用 | 表面高亮,非整行灰 code |
|
||||
|
||||
## 4. StmtEvent / CallFrame
|
||||
|
||||
解释器 capture 时静默采集(非 `trace_eval` stderr):
|
||||
|
||||
```text
|
||||
StmtEvent {
|
||||
line, kind, // assign | return | call | branch | loop | bind_ref
|
||||
name?, value_after?, // post-stmt 或求值结果
|
||||
arm_index?, iter?,
|
||||
call_id // 当前用户函数调用帧
|
||||
}
|
||||
|
||||
CallFrame {
|
||||
call_id, fn_name, fn_line, ordinal,
|
||||
args_brief, // 短摘要供下拉
|
||||
events[] // 或全局 events 用 call_id 过滤
|
||||
}
|
||||
```
|
||||
|
||||
- Assign → 写入后的值挂在**该行**。
|
||||
- 循环内多次写入:UI 默认末次;可带次数。
|
||||
- Branch → taken `arm_index` + 条件摘要。
|
||||
- 进入用户函数分配 `call_id`;`# main` 单帧无下拉。
|
||||
|
||||
## 5. ViewExecutionReport(AI)
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"path": "…",
|
||||
"ok": true,
|
||||
"calls": [{ "call_id": 1, "fn": "等级说明", "ordinal": 1, "args_brief": "等级=及格" }],
|
||||
"events": [{ "line": 24, "kind": "assign", "name": "总分", "value_after": "0", "call_id": 0 }],
|
||||
"bindings_final": { "均分": "73", "等级": "及格" }
|
||||
}
|
||||
```
|
||||
|
||||
产出:页内 `#mq-view-trace` JSON;live `GET /api/view-trace?path=`;SSE `done.trace_json`。
|
||||
|
||||
## 6. UI
|
||||
|
||||
- 函数标题旁 `<select class="call-picker">`(调用数 ≥ 2)。
|
||||
- 循环头旁 `<select class="loop-picker">`(迭代数 ≥ 2);默认最后一轮;摘要 `分 = 分数表[i] · value`。
|
||||
- **源码常显**:切换帧只改 chip / 臂高亮,不 `hidden` 结构节点。详见 [view-frame-selection.md](view-frame-selection.md)。
|
||||
- CSS L-leader(非 SVG);拥挤 keyed 降级。
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. 无字面 `**` / 返回定界 `*` / 变量外层 `` ` ``(Source 除外)。
|
||||
2. 表为真表格;循环/分支有缩进列表;未选中臂源码仍可见。
|
||||
3. `总分 = 0` 标注 `0`,非终态累加。
|
||||
4. 命中臂可视化;多调用下只显示当前帧的 taken。
|
||||
5. 循环可按迭代切换;JSON 含 `loops`;单测覆盖。
|
||||
|
||||
## 8. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:标记面、结构块、StmtEvent、CallFrame、AI 报告 |
|
||||
| 2026-10-15 | 帧选择保真:call_id 分支、LoopFrame、源码常显 |
|
||||
@@ -0,0 +1,123 @@
|
||||
# View:调用帧 / 循环帧选择与结构保真
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-execution-trace.md](view-execution-trace.md) · [view-document-annotations.md](view-document-annotations.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题(对照实测)
|
||||
|
||||
1. **结构缺失**:切换函数调用下拉时,JS 按 `data-call-id` **隐藏** `.doc-exec`。未在本帧执行的分支臂体(赋值/返回)只有其它帧的 call_id,或仅有执行帧的 id → **未选中臂的源码被藏掉**,看起来像「臂消失 / 代码没渲染」。
|
||||
2. **调用记录混叠**:`Branch` 标注未带 `call_id`;`taken_arms` 按行号只保留最后一次命中。多帧下同一分支同时出现 `arm 1 taken` 与 `arm 2 taken`。
|
||||
3. **循环无帧**:循环只有总次数摘要;无法按迭代查看;`` - [分](分数表) `` 不能展示「当前是集合第几个元素」。
|
||||
|
||||
## 2. 定稿原则
|
||||
|
||||
| 原则 | 含义 |
|
||||
|------|------|
|
||||
| **源码常显** | 表 / 列表 / 分支臂 / 语句源码**永不**因帧选择 `hidden` |
|
||||
| **轨迹随帧** | 标注 chip、臂高亮、变量值随「当前调用帧 / 当前迭代」变化 |
|
||||
| **默认末帧** | 函数默认最后一次调用;循环默认最后一次迭代 |
|
||||
| **一帧一真相** | 同时只展示一个 call_id(函数)或一个 (loop_id, iter)(循环)的轨迹 |
|
||||
|
||||
## 3. 函数调用帧
|
||||
|
||||
### 数据
|
||||
|
||||
`BranchHit` / 相关 `StmtEvent` 必须带 `call_id`。`ViewAnnot` 的 branch/bind/return 同样带 `call_id`。
|
||||
|
||||
### UI
|
||||
|
||||
- 函数标题旁 `<select class="call-picker" data-fn="…" data-scope="fn">`
|
||||
- 选项:`1: 等级=及格` / `2: 等级=优秀`
|
||||
- 默认选中最后一次
|
||||
|
||||
### 客户端(`applyCallFrame`)
|
||||
|
||||
1. 读 `#mq-view-trace` JSON。
|
||||
2. 过滤 `events` where `call_id == selected`。
|
||||
3. **不**设置结构节点 `hidden`。
|
||||
4. 更新该函数作用域内:
|
||||
- `.annot-chip[data-call-id]`:仅显示匹配帧;无 call_id 的结构说明类可保留
|
||||
- `.doc-branch[data-line]`:按该帧的 branch 事件设置 `arm-taken` / `arm-miss`(全部臂仍可见)
|
||||
- 绑定 chip 的 `.annot-value`:用该帧 assign/return 事件刷新(同名同行取末次)
|
||||
|
||||
## 4. 循环迭代帧
|
||||
|
||||
### 数据
|
||||
|
||||
```text
|
||||
LoopFrame {
|
||||
loop_id, line,
|
||||
item_name?, // "分"
|
||||
collection?, // "分数表"
|
||||
iterations: [{ index, item_value, call_id }] // index 0-based
|
||||
}
|
||||
```
|
||||
|
||||
`StmtEvent` 增加可选 `loop_id`;循环体内事件带 `iter`(1-based 或 0-based,JSON 内统一 **0-based index**)。
|
||||
|
||||
### UI
|
||||
|
||||
- 循环头(`- [分](分数表)`)旁:`<select class="loop-picker" data-loop-id="…">`
|
||||
- 选项:`迭代 1: 分=92` … `迭代 4: 分=88`
|
||||
- 默认最后一次
|
||||
- 头旁摘要 chip:`分 = 分数表[3] · 88`(下标 0-based 显示为 `[i]`)
|
||||
|
||||
### 客户端(`applyLoopFrame`)
|
||||
|
||||
1. **只显示当前迭代**:带 `data-iter` 的 chip 仅保留选中项;其余 `hidden` + `is-frame-hidden`(SSR 默认已按末轮预隐藏)。
|
||||
2. 更新头摘要 chip(无 `data-iter`)为当前选项文案。
|
||||
3. 不隐藏循环体源码。
|
||||
|
||||
## 5. 分支臂渲染
|
||||
|
||||
- 所有臂(含 else)**始终**渲染完整头 + 体(含 `*返回*` / 赋值)。
|
||||
- `arm-miss` 仅降低不透明度,**不** `display:none` / `hidden`。
|
||||
- 高亮仅反映**当前帧**的 taken `arm_index`。
|
||||
|
||||
## 6. AI JSON 增量
|
||||
|
||||
`ViewExecutionReport` 增加:
|
||||
|
||||
```json
|
||||
"loops": [{
|
||||
"loop_id": 1,
|
||||
"line": 27,
|
||||
"item": "分",
|
||||
"collection": "分数表",
|
||||
"iters": [{ "index": 0, "value": "92" }, { "index": 3, "value": "88" }]
|
||||
}]
|
||||
```
|
||||
|
||||
`events[].call_id` 必填;循环体内事件带 `loop_id` + `iter`(index)。
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. 未选中分支臂源码始终可见(含返回句)。
|
||||
2. 切换「等级说明」调用:只显示该帧的 arm taken;变量/返回值对应该帧。
|
||||
3. 循环下拉默认最后一轮;`分 = 分数表[3] · 88`;切换迭代后体内累加值变化。
|
||||
4. `#mq-view-trace` 含 `loops` 与带 `call_id` 的 branch 事件。
|
||||
5. `cargo test --lib view::` 全绿。
|
||||
|
||||
## 8. 开发计划(已执行)
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| D0 | 本文档 + `view-execution-trace.md` 交叉引用 | ✅ |
|
||||
| D1 | `BranchHit.call_id`;`LoopFrame` / `LoopIter`;`StmtEvent.loop_id` | ✅ |
|
||||
| D2 | 解释器:foreach/while 推栈;BindRef `分=分数表[i]`;assign 带 iter | ✅ |
|
||||
| D3 | `build_view_annots`:分支带 call_id;LoopFrame 选项;报告 JSON `loops` | ✅ |
|
||||
| D4 | 文档面:源码不贴 `data-call-ids`;call picker `value=call_id`;loop picker;SSR taken=末帧 | ✅ |
|
||||
| D5 | JS:`applyCallFrame` / `applyLoopFrame` — 只滤 chip + 重算 arm,不 hidden 结构 | ✅ |
|
||||
| D6 | 单测:多调用不同臂、loop 末项、HTML 三臂返回 + picker | ✅ |
|
||||
|
||||
## 9. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:源码常显、帧过滤、循环迭代 picker |
|
||||
| 2026-10-15 | 按计划落地 D1–D6 |
|
||||
@@ -0,0 +1,145 @@
|
||||
# View:叙述面标注缺口(prose annot gaps)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [view-frame-selection.md](view-frame-selection.md) · [view-execution-trace.md](view-execution-trace.md) |
|
||||
|
||||
> **定位**:对既有文档面设计的**缺口专章**——写清用户可见的四类问题、根因(文件:行)与验收口径。不改写 ADR;不发明作者侧标注 DSL。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何「改了却几乎没变化」
|
||||
|
||||
| 原因 | 说明 |
|
||||
|------|------|
|
||||
| 错二进制 | PATH 上的 `marqdo` 可能仍是旧版(如 1.3.0);改动在源码 / `./target/debug/marqdo`。验收必须用 `cargo build && ./target/debug/marqdo view …` |
|
||||
| Chip 被溢出藏掉 | 同 band 堆多帧 return/print/who;`MAX_VISIBLE_ANNOTS=4` 把当前帧的 `who` 打成 `annot-chip-overflow`(`display:none`);帧切换不重算溢出 |
|
||||
| L-leader 几何错位 | `initAnnotLeaders` 里 `y0=0` 只在 `.annot-band` 顶画短折,**连不到**上方 underline;窄屏或 chip>4 时整段关掉 leaders |
|
||||
| 旧静态快照 | gh-pages / 旧 `view output` 不会自动刷新 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标视觉语法(既有,不新造)
|
||||
|
||||
锚定 [view-document-annotations.md](view-document-annotations.md) §3:
|
||||
|
||||
```
|
||||
文本段…… `变量` …… **语句** …… *返回*
|
||||
━━━━━
|
||||
│
|
||||
└──→ 结果标注 chip
|
||||
```
|
||||
|
||||
- underline:`mark.mq-anchor.mq-{decl|code|return}`
|
||||
- band:段落下方 `.annot-band` → leaders + chips
|
||||
- L-leader:CSS `border-left` + `border-bottom`(禁止 SVG)
|
||||
- 公式/代码:[view-static-interactive.md](view-static-interactive.md) G3 **一层主视觉**;卡下不叠 Bind dump
|
||||
- 帧:[view-frame-selection.md](view-frame-selection.md) **源码常显、只滤 chip**;默认末帧
|
||||
|
||||
---
|
||||
|
||||
## 3. 管线
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
CLI["marqdo view / view output"] --> build["build_file_view"]
|
||||
build --> cap["run_file_capture"]
|
||||
cap --> annot["build_view_annots"]
|
||||
annot --> doc["document::render_module_document"]
|
||||
doc --> page["html.rs page_file"]
|
||||
page --> js["initAnnotLeaders + initCallPickers"]
|
||||
```
|
||||
|
||||
| 步骤 | 位置 |
|
||||
|------|------|
|
||||
| CLI / 导出 | `src/main.rs` · `src/view/mod.rs` · `src/view/output.rs` |
|
||||
| Capture + Call 事件 | `src/interp.rs` |
|
||||
| Annot 组装 | `src/view/annot.rs` `build_view_annots` |
|
||||
| 文档面 HTML | `src/view/document.rs` |
|
||||
| 卡片 chrome | `src/view/render.rs` `render_*_assign_card` |
|
||||
| CSS / leader JS | `src/view/html.rs` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 四条用户问题 → 根因 → 验收
|
||||
|
||||
复现源:`public/00-welcome.mq.md` · `public/00-欢迎.mq.md`
|
||||
对照金样:`tests/view/document-annot-demo.mq.md` · `tests/markup-v03/inc-prose.mq.md`
|
||||
|
||||
### P1 — 叙述与代码同段时信息不显示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | underline 在,chip / 连线弱或无 |
|
||||
| 根因 | `html.rs` `initAnnotLeaders`:`y0=0` 相对 band;`document.rs` `MAX_VISIBLE_ANNOTS` 把当前帧 chip 溢出;PATH 旧 CLI |
|
||||
| 目标 | 同 `inc-prose`:underline + L-leader(从锚点底到 chip)+ 可见 chip |
|
||||
| 验收 | `./target/debug/marqdo view public/00-welcome.mq.md`:主文 `**greet…**` 与 `## greet` 体内均有可见 chip 与接到 underline 的 leader(宽屏) |
|
||||
|
||||
### P2 — 函数内变量不显示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `` `who` `` 有浅蓝 underline,无值 chip |
|
||||
| 根因 | bind chip 存在但带 `annot-chip-overflow`;`applyCallFrame` 只 `hidden` 非选中帧,不解除当前帧 overflow |
|
||||
| 目标 | 选中调用帧时常显 `who` · `print` · `return` 各一枚 |
|
||||
| 验收 | 切换「调用」下拉,三枚 chip 随帧变且默认可见(无需点 +N) |
|
||||
|
||||
### P3 — ` ```text ` 渲染不一致
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | 变成内联 `text marqdo ext add…`,无卡片 |
|
||||
| 根因 | Comment 围栏若进 `flush_para` → `join(" ")` → pulldown 当 inline code;应走 `render_narrative_fence` |
|
||||
| 目标 | 与 bound python 同 `.code-card` chrome(badge + `pre.code-body`),**无** Run/foot |
|
||||
| 验收 | welcome install 段:`data-lang="text"` + 两行 `marqdo ext add`;无 `<code>text marqdo` |
|
||||
|
||||
### P4 — 函数引用 / 代码卡未渲染
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `**greet who=…**` 无结果;或 `hi` python 只见头/Run、不见源码 |
|
||||
| 根因 | 同行多 Call 未与 BoldCode zip;或 Run 挤在 head;静态假 Run;错看 Debug 路径 |
|
||||
| 目标 | 主文两 greet 各有 call chip(stdout 摘要);`hi` = `render_code_assign_card` head→body→foot;静态藏 Run |
|
||||
| 验收 | 两枚 greet mark 均有非空 `data-annot-id`;`code-body` 含 `hello-from-python`;`MARQDO_VIEW_LIVE=false` 无 Run 按钮 |
|
||||
|
||||
### call_id 语义(写死)
|
||||
|
||||
| 位置 | call_id |
|
||||
|------|---------|
|
||||
| 主文 `**greet…**` 的 call chip | 入口帧(`# main` 的 call);结果为 stdout/返回摘要 |
|
||||
| `## greet` 体内 print / who / return | callee 的 CallFrame id;跟函数标题旁 picker |
|
||||
|
||||
---
|
||||
|
||||
## 5. 修复约定(实现红线)
|
||||
|
||||
1. **帧感知密度**:band 内按选中 `call_id` 计可见 chip;默认末帧;同帧最多 4 枚常显;溢出只藏非当前帧或多余 kind。切换后客户端重算 overflow + `layoutAll()`。
|
||||
2. **Leader 容器**:提升到 `.doc-block`(prose + band);`y0` = 锚点底相对 block;按锚点 x 排序再画线。
|
||||
3. **卡片**:只复用 Browse `render_*_assign_card` / `render_narrative_fence` + `html.rs` `.code-*` / `.formula-card`;本波不改 Debug AST 路径(除非回归红)。
|
||||
4. **静态 Run**:`MARQDO_VIEW_LIVE=false` 时隐藏 Run,不留禁用假按钮(对齐 view-static-interactive D5)。
|
||||
5. **非目标**:不做 debug 断点;不发明作者标注 DSL;不用 SVG leader;不单独发版/推 gh-pages(除非另嘱)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收命令
|
||||
|
||||
```bash
|
||||
cargo build -q
|
||||
./target/debug/marqdo version # 须为当前工作树版本
|
||||
./target/debug/marqdo view public/00-welcome.mq.md --no-open
|
||||
./target/debug/marqdo view tests/view/document-annot-demo.mq.md --no-open
|
||||
cargo test -q --lib view::
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:四问题、错二进制/溢出/leader 根因、帧感知密度与 leader 几何约定 |
|
||||
| 2026-10-15 | L-leader 拥挤/消失:同跨度多帧 chip **共用 annot id**;可见 chip 按锚点 x 重排;leader 挂 doc-block |
|
||||
| 2026-10-15 | L-leader 黑线碎段:JS `border*: "1.5px solid"` 无色覆盖 class → 改为 kind 色写入 shorthand;chip SSR/DOM 按锚点 L→R |
|
||||
| 2026-10-15 | L-leader 改为 SVG:描述底边中点 → 轨道 → 短竖线 → 值 chip 顶边中点;chip 间距加宽 |
|
||||
@@ -0,0 +1,239 @@
|
||||
# View:静态页交互与公式/代码卡视觉
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-10-15 |
|
||||
| 相关 | [view.md](view.md) · [user-site.md](user-site.md) · [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [ADR 0002 browser WASM](../adr/0002-browser-marqdo-wasm.md) |
|
||||
|
||||
**已确认(2026-10-15)**
|
||||
|
||||
| 决策 | 选择 |
|
||||
|------|------|
|
||||
| 引擎 | **B**(快照 + S1 帧切换 + 可选懒加载 WASM S2) |
|
||||
| 体验原则 | 静态页与 live view **尽量同构**;控件形态对齐;无服务端时用 WASM/JS 补齐 |
|
||||
| 视觉原则 | **一层主视觉**;一眼能懂;公式/代码不与 Bind chip / 源残留叠床架屋 |
|
||||
| 演示参数条 | **要**(历史实参 select + 可编辑;S1 切帧 / S2 重跑) |
|
||||
| code-card Run | 有 WASM 时可用;否则隐藏(不对齐「假按钮」) |
|
||||
| 公式 Bind chip | **卡内不显示**;Variables 可留终值 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机(对照 `public/00-欢迎.mq.md` / gh-pages)
|
||||
|
||||
静态导出(`marqdo view output` → `gh-pages`)与 live `marqdo view` 已共用**文档面 Structure** 渲染路径,但用户站实测仍有三类落差:
|
||||
|
||||
1. **交互控件缺失 / 偏弱**
|
||||
- 函数「问候」仅有参数 chip「谁」,没有可切换的调用帧下拉(即便源里 `> 问候` 写了两次)。
|
||||
- 参数行 `+ 谁` 在文档面呈声明高亮,读者无法在静态页改「谁」并看到新输出。
|
||||
- 外联 `code-card` 的 Run 在静态模式被禁用(`Run is available in live marqdo view`)。
|
||||
- 静态 stdin 仅在有 preset 时显示只读提示,**不能**再跑。
|
||||
|
||||
2. **无服务端时仍可交互的预期**
|
||||
用户站是纯静态托管:没有 `/api/run`。合理路径是 **页内 JS** 和/或 **嵌入 Marqdo WASM**,在浏览器里重算 Structure 标注、Execution 区,甚至模拟 `input` / 外联(沙箱约束另定)。
|
||||
|
||||
3. **公式 / 代码块视觉凌乱**
|
||||
同一赋值同时出现多层表象,信息重复、线框错位:
|
||||
|
||||
| 层 | 公式 `f = $$…$$` | 外联 `hi = ```python…``` |
|
||||
|----|------------------|---------------------------|
|
||||
| A 卡片 | `formula` badge + KaTeX | `code` badge + 高亮源码 + cmd/Run |
|
||||
| B 标注 chip | `f` → `x^2 - 2` | `hi` → 整段 fence 摘要 |
|
||||
| C 源残留 | 卡片外/旁再露 `$$` 或 ASCII | 卡片下再露 `python print…` 明文 |
|
||||
|
||||
再叠加 CSS L-leader 与卡内边框,首屏显得碎、重复、「坏掉的线」。
|
||||
|
||||
**本文件只定问题与方案;确认前不改代码。**
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状解剖
|
||||
|
||||
### 2.1 静态 vs live(同一 `page_file`)
|
||||
|
||||
| 能力 | Live | Static(`LinkMode::Static`) |
|
||||
|------|------|------------------------------|
|
||||
| 文档面 Structure + annot | ✅(跑后) | ✅(导出时跑后写入) |
|
||||
| call / loop picker JS | ✅(读 `#mq-view-trace`) | ✅(同源 JS;若轨迹未写入则无控件) |
|
||||
| `/api/run` · Stream | ✅ | ❌ |
|
||||
| stdin 表单 | ✅ 可再跑 | 只读 hint(或无) |
|
||||
| code-card Run | ✅ `POST` 外联 | ❌ 禁用按钮 |
|
||||
| WASM 重算 | ❌(未接) | ❌(未接) |
|
||||
|
||||
结论:**不是「静态另做一套皮肤」**,而是「导出瞬间的快照 + 部分 JS 帧切换」;**没有**浏览器内重执行闭环。
|
||||
|
||||
### 2.2 欢迎页结构(问题复现源)
|
||||
|
||||
```text
|
||||
> 问候 谁=marqdo
|
||||
> 问候 谁=marqdo user
|
||||
## 问候
|
||||
+ `谁`
|
||||
> 打印 内容=欢迎,`谁`!
|
||||
`f` = $$ x^2 - 2 $$
|
||||
`hi` = ```python … ```
|
||||
```
|
||||
|
||||
- 期望:`## 问候` 旁 **调用** 下拉(`1: 谁=marqdo` / `2: 谁=marqdo user`),切换时打印行的绑定/输出随帧变。
|
||||
- 现状风险:若导出时 CallFrame < 2、或 picker 未挂上、或读者期望的是「编辑谁」而非「选历史调用」,都会表现为「没有下拉框」。
|
||||
- 公式/代码:`SpecialAssign` → formula/code **card**,同时又对同名绑定建 **Bind annot**,文档面还可能保留块源视觉 → 三重展示。
|
||||
|
||||
### 2.3 已有红线(方案不得破坏)
|
||||
|
||||
- 代码即文档:`.mq.md` 源可读;不发明第二套嵌套 DSL(见 web-artifact / marqdo-dev)。
|
||||
- Browse ≠ Debug:静态站不做断点。
|
||||
- `public/**/*.html` 不入库;gh-pages 由 CI/`view output` 生成([user-site.md](user-site.md))。
|
||||
- 外链字体禁令仍在 [view.md](view.md);WASM/重型资源须 **可选加载**,默认站可降级为纯快照。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标(验收口径)
|
||||
|
||||
### G1 — 帧与参数交互(静态可读、可拨)
|
||||
|
||||
1. 同函数 ≥2 次调用时,静态页 **必有**「调用」下拉;默认末次;切换只改 chip/臂/相关输出,**源码常显**(同 [view-frame-selection.md](view-frame-selection.md))。
|
||||
2. 导出保证写入完整 `#mq-view-trace`(含 `calls` / `events` / 可选 `loops`)。
|
||||
3. (增强)演示向参数可提供 **受控输入**:默认值来自末次调用或 FM;改参后可触发页内重算(见 §5 引擎选项)。
|
||||
|
||||
### G2 — 无服务端可重算(可选引擎)
|
||||
|
||||
| 档位 | 能力 | 依赖 |
|
||||
|------|------|------|
|
||||
| **S0 快照**(现状加强) | 导出时跑完;帧 picker;只读 Execution | 无 WASM |
|
||||
| **S1 页内重放轨迹** | 不重跑程序,只切换已序列化帧/标注 | JSON only |
|
||||
| **S2 WASM 重跑** | `marqdo_wasm` + bridge:改 stdin/实参后重跑,刷新 Structure/Execution | WASM 包(可 CDN/`public/wasm/`) |
|
||||
| **S3 外联沙箱** | code-card Run:浏览器内 pyodide **或** 明确标「仅 live」 | 可选;默认可关 |
|
||||
|
||||
默认用户站:**S0 + S1 必达**;**S2 为推荐主路径**(与「用 wasm 模拟输出」对齐);S3 单独开关。
|
||||
|
||||
### G3 — 公式 / 代码视觉单层真相
|
||||
|
||||
对「特殊赋值」块约定 **一层主视觉 + 至多一层结果**:
|
||||
|
||||
| 块 | 主视觉 | 允许的结果层 | 禁止 |
|
||||
|----|--------|--------------|------|
|
||||
| 公式 | KaTeX(formula-card 精简) | 无 Bind chip,或仅在 Variables | 再渲一份 `$$` 明文;annot 与卡重复同一 TeX |
|
||||
| 外联代码 | 高亮源码(code-card) | 运行输出区 `code-out`;静态可藏 Run 或接 S2/S3 | annot 再贴整段 fence;卡下重复裸源 |
|
||||
| 普通赋值 | 标记面语句 | Bind chip + L-leader | — |
|
||||
|
||||
Leader:仅连接「主视觉锚点 → 唯一结果 chip」;卡内不用第二套 L 线。
|
||||
|
||||
---
|
||||
|
||||
## 4. 问题清单(成文)
|
||||
|
||||
| ID | 问题 | 严重度 | 根因假设 |
|
||||
|----|------|--------|----------|
|
||||
| P1 | 静态页看不到调用/循环下拉 | 高 | 轨迹未导出完整 / picker 条件(≥2)未满足 / 读者要的是编辑参而非选帧 |
|
||||
| P2 | 不能改参/stdin 再看输出 | 高 | Static 禁用 `/api/run`;无 WASM 闭环 |
|
||||
| P3 | code-card Run 静态无效 | 中 | `initForeignCards` 显式禁用 |
|
||||
| P4 | 公式卡 + chip + `$$` 三重 | 高 | card 与 Bind annot 叠加;块源未完全被 SpecialAssign 吞掉 |
|
||||
| P5 | 代码卡 + chip + 明文三重 | 高 | 同 P4 |
|
||||
| P6 | 卡内/旁碎线、错位 | 中 | leader 锚到错误节点;卡 CSS 与 annot-band 叠层 |
|
||||
| P7 | 静态 stdin 体验差 | 中 | 仅有只读 hint |
|
||||
|
||||
---
|
||||
|
||||
## 5. 解决方案(详案,待选)
|
||||
|
||||
### 5.1 引擎策略(三选一,推荐 **B**)
|
||||
|
||||
| 方案 | 做法 | 优点 | 代价 |
|
||||
|------|------|------|------|
|
||||
| **A. 纯快照 + S1** | 加强导出轨迹与 picker;不引入 WASM | 体积小、离线稳 | 不能改参真重算 |
|
||||
| **B. 快照默认 + 可选 WASM(S0/S1/S2)** | `view output` 仍嵌入跑后 HTML;页脚/侧栏「在浏览器中重跑」懒加载 WASM;改参后 patch Structure/Execution | 对齐用户预期;无 WASM 时仍可读 | 打包/加载体积;宿主能力子集 |
|
||||
| **C. 静态页全面 WASM 首屏** | 打开即 WASM 跑 | 交互最强 | 冷启动慢;gh-pages 带宽;与「文档先可读」冲突 |
|
||||
|
||||
**推荐 B**:文档先可读(S0),帧切换不依赖 WASM(S1),需要改参/演示时再拉 WASM(S2)。
|
||||
|
||||
### 5.2 交互控件(与文档面一致)
|
||||
|
||||
1. **调用 / 循环 picker**(已有组件)
|
||||
- 导出验收:欢迎页「问候」必须出现调用下拉。
|
||||
- 单测:对 `00-欢迎.mq.md` / `document-annot-demo` 断言 HTML 含 `call-picker` 且 options≥2。
|
||||
|
||||
2. **演示参数条(新,窄范围)**
|
||||
- 仅当函数被标记为「可演示」**或**静态页检测到 ≥1 形参且存在 CallFrame 时,在函数标题旁增加:
|
||||
`谁 [ text input | select(历史实参) ] [应用]`
|
||||
- **不**改 `.mq.md` 语法;数据来自 trace 的 `args_brief` / 末次绑定。
|
||||
- 「应用」:S1 仅切换已有帧;S2 调 WASM `run` 后替换 `#structure` / Execution。
|
||||
|
||||
3. **stdin**
|
||||
- 静态:若源含 `input`,渲染与 live 同形的 textarea +「重跑」(S2)或说明「需 WASM」。
|
||||
- 无 input 则不显示。
|
||||
|
||||
### 5.3 公式 / 代码去重(视觉)
|
||||
|
||||
**规则:SpecialAssign 行只走 card,不再为同名同值挂 Bind chip。**
|
||||
|
||||
```text
|
||||
公式赋值行
|
||||
└─ formula-card(badge + 名 + KaTeX)
|
||||
└─ ✗ 不再 render_annot_band(Bind f)
|
||||
└─ ✗ 不再在卡外输出 $$ 源
|
||||
|
||||
外联赋值行
|
||||
└─ code-card(badge + 名 + 高亮体 + 可选 Run)
|
||||
└─ ✗ 不再 Bind chip 贴 fence 全文
|
||||
└─ 运行结果只进 .code-out
|
||||
```
|
||||
|
||||
静态 Run 策略(与 §5.1 对齐):
|
||||
|
||||
- S0:隐藏 Run,或保留禁用并 tooltip「打开 live view / 启用 WASM」。
|
||||
- S2:Run → WASM 宿主 `foreign`(若 WASM 支持)或提示不支持。
|
||||
- S3:可选 Pyodide(默认关)。
|
||||
|
||||
CSS:formula-card / code-card 与 `.annot-band` 垂直节奏统一;禁止对 KaTeX 节点拉 L-leader。
|
||||
|
||||
### 5.4 导出管线
|
||||
|
||||
```text
|
||||
marqdo view output
|
||||
→ build_file_view(跑 + annot + trace_json) // 已有
|
||||
→ page_file(Static)
|
||||
+ 嵌入 #mq-view-trace
|
||||
+ (可选)data-wasm-url / 懒加载脚本
|
||||
+ 公式/代码去重后的 structure_html
|
||||
→ public/ + gh-pages
|
||||
```
|
||||
|
||||
`--no-exec`:文档面无标注;可提示「本页为结构-only」;S2 仍可尝试 WASM 首跑(可选,默认关以免惊喜执行)。
|
||||
|
||||
### 5.5 明确不做(本提案)
|
||||
|
||||
- 静态页断点调试(仍属 `marqdo debug`)。
|
||||
- 在 `public/*.mq.md` 发明新的「交互表」DSL(除非另开设计并获批)。
|
||||
- 默认全站加载 Pyodide。
|
||||
- 提交生成 HTML 进 `main`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 分阶段开发计划(确认后执行)
|
||||
|
||||
| 阶段 | 内容 | 交付 | 依赖确认 |
|
||||
|------|------|------|----------|
|
||||
| **D0** | 本文定稿;选定引擎 **A/B/C**;是否要「演示参数条」 | 状态 → Active | **本次决策** |
|
||||
| **D1** | P4/P5/P6:SpecialAssign 与 Bind 互斥;卡 CSS;去掉重复源 | 欢迎页公式/代码干净;单测 | D0 |
|
||||
| **D2** | P1:导出轨迹验收 + 欢迎页 call-picker 金样;修任何「≥2 调用无下拉」bug | HTML 断言 | D0 |
|
||||
| **D3** | P2/P7 S1 夯实:静态 stdin UI 形态;无 WASM 时文案清晰 | UX | D0 |
|
||||
| **D4** | (若选 B)S2:静态页懒加载 WASM;「应用参数 / 重跑」刷新 Structure+Execution | `public/wasm` 或 CDN 策略;体积预算 | D0=B |
|
||||
| **D5** | P3:code-card 与 S2/S3 策略落地;默认隐藏无效 Run | — | D1+D4 |
|
||||
| **D6** | `build-public` / pages CI 回归;更新 [user-site.md](user-site.md) · [view.md](view.md) 验收条 | gh-pages 抽检欢迎页 | D1–D5 |
|
||||
|
||||
建议默认路径:**D0 选 B → D1 → D2 → D3 → D4 → D5 → D6**。
|
||||
|
||||
---
|
||||
|
||||
## 7. 决策记录
|
||||
|
||||
见文首「已确认」。开发按 §6:D1 → D2 → D3 → D4 → D5 → D6。
|
||||
|
||||
---
|
||||
|
||||
## 8. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-10-15 | 初稿:静态交互缺口、公式/代码凌乱、S0–S3 与阶段 D0–D6 |
|
||||
| 2026-10-15 | Active:引擎 B;对齐 live;干净视觉;演示参数条;Run 接 WASM 否则隐藏 |
|
||||
+6
-4
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.0.2 方向) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
|
||||
---
|
||||
|
||||
@@ -77,7 +77,7 @@ OUT_DIR/
|
||||
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
|
||||
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
|
||||
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
|
||||
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
|
||||
- 渲染逻辑与实时 `view` **共用**同一路径:`build_file_view` → 文档面 Structure(`document.rs` + annots)→ `page_file`(同一 CSS/JS,含 call/loop picker、`#mq-view-trace`)。禁止第二套皮肤。`--no-exec` 时仍出文档面,但无运行标注。
|
||||
|
||||
示例:
|
||||
|
||||
@@ -90,14 +90,16 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
|
||||
## 4. 信息架构
|
||||
|
||||
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
|
||||
侧栏文件索引 + 主区:**文档面 Structure** · 执行 · 源码。Structure(Browse)为叙述保真文档面:标记面(变量/语句/返回无源码定界符)、表/列表/分支结构保真,跑后结果经 **CSS L-leader** 引出——见 [view-document-annotations.md](view-document-annotations.md) · [view-execution-trace.md](view-execution-trace.md)。**不是** AST 卡片栈(那是 debug)。
|
||||
|
||||
结构旁**右侧栏**(现有 outline 槽)为:
|
||||
|
||||
| 区块 | 内容 |
|
||||
|------|------|
|
||||
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
|
||||
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
|
||||
|
||||
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
|
||||
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板;终态亦可刷新 Structure 内标注。
|
||||
|
||||
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||||
|
||||
|
||||
+2818
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: resolve_config
|
||||
capability: config.resolve
|
||||
status: stable
|
||||
---
|
||||
|
||||
Use when: final normalized configuration is required.
|
||||
|
||||
# config
|
||||
|
||||
## resolve_config
|
||||
+ `path`
|
||||
|
||||
`defaults` =
|
||||
|
||||
| host | port |
|
||||
|------|------|
|
||||
| localhost | 8080 |
|
||||
|
||||
* defaults
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Engineering Knowledge demo
|
||||
description: Tiny project demonstrating Capability Catalog + reuse + decisions.
|
||||
---
|
||||
|
||||
# Engineering Knowledge demo
|
||||
|
||||
This folder is a miniature “large engineering” slice: config resolution already exists.
|
||||
Before generating a new loader, run:
|
||||
|
||||
```bash
|
||||
marqdo knowledge examples/engineering-knowledge -o examples/engineering-knowledge/.marqdo
|
||||
marqdo reuse "load and resolve configuration" examples/engineering-knowledge -o examples/engineering-knowledge/.marqdo
|
||||
marqdo duplicate examples/engineering-knowledge -o examples/engineering-knowledge/.marqdo
|
||||
```
|
||||
|
||||
Expected: **REUSE config.resolve**, not a new `load_configuration`.
|
||||
|
||||
# main
|
||||
|
||||
* "see README via catalog/reuse CLI"
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
type: Decision
|
||||
id: ADR-022
|
||||
title: Cache is not persistence
|
||||
status: accepted
|
||||
applies_to:
|
||||
- config.resolve
|
||||
---
|
||||
|
||||
# Cache is not persistence
|
||||
|
||||
## Decision
|
||||
|
||||
Redis is only used for ephemeral cache.
|
||||
|
||||
## Reason
|
||||
|
||||
The application must remain correct when Redis is unavailable.
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
type: Constraint
|
||||
id: C-014
|
||||
title: Centralized config resolution
|
||||
status: stable
|
||||
applies_to:
|
||||
- config.resolve
|
||||
---
|
||||
|
||||
# Centralized config resolution
|
||||
|
||||
All configuration resolution must go through `resolve_config`.
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
type: Failure
|
||||
id: F-008
|
||||
title: Do not invent a second config loader
|
||||
status: resolved
|
||||
---
|
||||
|
||||
# Do not invent a second config loader
|
||||
|
||||
## Failed approach
|
||||
|
||||
Added `load_configuration` beside `resolve_config`.
|
||||
|
||||
## Failure
|
||||
|
||||
Divergent defaults and error handling.
|
||||
|
||||
## Correct approach
|
||||
|
||||
Call `resolve_config`.
|
||||
+1
-1
@@ -1 +1 @@
|
||||
1.2.0
|
||||
1.4.1
|
||||
@@ -2104,6 +2104,51 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st
|
||||
|
||||
*out*
|
||||
|
||||
## preflight
|
||||
+ `task`
|
||||
+ `root`="."
|
||||
+ `marqdo_dir`=None
|
||||
+ `min_candidates`=3
|
||||
+ `allow_create_after`=2
|
||||
+ `reuse_threshold`=0.72
|
||||
+ `adapt_threshold`=0.45
|
||||
|
||||
Engineering First Information gate (008 / EKC). Reads compiled `.marqdo` knowledge.
|
||||
Returns `{status,decision,create_allowed,existing,constraints,decisions,failures,recommended,context_path}`.
|
||||
Hard rule: generate only when `create_allowed` is true (or decision is REUSE/ADAPT).
|
||||
|
||||
1. `marqdo_dir`
|
||||
**pf = > agent_eng_preflight task=`task` root=`root` marqdo_dir=`marqdo_dir` min_candidates=`min_candidates` allow_create_after=`allow_create_after` reuse_threshold=`reuse_threshold` adapt_threshold=`adapt_threshold`**
|
||||
2. *
|
||||
**pf = > agent_eng_preflight task=`task` root=`root` min_candidates=`min_candidates` allow_create_after=`allow_create_after` reuse_threshold=`reuse_threshold` adapt_threshold=`adapt_threshold`**
|
||||
|
||||
*pf*
|
||||
|
||||
## eng_reuse
|
||||
+ `task`
|
||||
+ `root`="."
|
||||
+ `marqdo_dir`=None
|
||||
|
||||
Alias of `preflight` focused on REUSE / ADAPT / CREATE payload.
|
||||
|
||||
1. `marqdo_dir`
|
||||
*> agent_eng_reuse task=`task` root=`root` marqdo_dir=`marqdo_dir`*
|
||||
2. *
|
||||
*> agent_eng_reuse task=`task` root=`root`*
|
||||
|
||||
## eng_record
|
||||
+ `decision`
|
||||
+ `root`="."
|
||||
+ `marqdo_dir`=None
|
||||
+ `duplicated`=False
|
||||
|
||||
Record REUSE/ADAPT/CREATE into `.marqdo/agent/episodes/reuse_metrics.json`.
|
||||
|
||||
1. `marqdo_dir`
|
||||
*> agent_eng_record decision=`decision` root=`root` marqdo_dir=`marqdo_dir` duplicated=`duplicated`*
|
||||
2. *
|
||||
*> agent_eng_record decision=`decision` root=`root` duplicated=`duplicated`*
|
||||
|
||||
## plan
|
||||
+ `goal`
|
||||
+ `workbook_dir`=None
|
||||
@@ -2127,9 +2172,14 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st
|
||||
+ `trace`=False
|
||||
+ `resume_id`=None
|
||||
+ `resume_dir`=.marqdo/agent-resume
|
||||
+ `eng_preflight`=False
|
||||
+ `marqdo_dir`=.marqdo
|
||||
+ `allow_create_after`=2
|
||||
|
||||
Multi-step with OKF agent-kb. Default workbook is `kb_dir/resources/<slug>.mq.md`. While task file count `< explore_n` and skill is not llm_free, force a new explore variant under `kb_dir/explore/<slug>/`. Code-first: llm_free hits skip parent LLM. File children return via `# main`; `plan` exposes that as `result`.
|
||||
|
||||
Engineering Knowledge preflight when `eng_preflight=True`: REUSE/ADAPT preferred; CREATE only if `create_allowed`. Production agents should enable this; tests that only exercise agent-kb may leave it false.
|
||||
|
||||
Reuse lookup: exact → alias → canonicalize → optional local n-gram `near` when `near_match=True` and score ≥ `near_threshold`. Non-hit path: optional `soft_match=True` parent REUSE/NEW over ranked `agent_kb_near_match` candidates; else decompose before first child spawn (`DECISION: RUN` / `CONTINUE`+patch / solidified `DONE`). Then `await` → revise loop. Process events (`decision` / `round` / `done` / tools) are always attached on the result map for audit and view process cards; `stream=True` additionally SSE-publishes them (and parent `delta`). `echo=True` prints `plan:decompose` / `plan:await` / deltas. `trace=True` writes events to writeback slot `trace`. Quiet child subtasks stay quiet.
|
||||
|
||||
**tools = > json.get value=`self` key="tools"**
|
||||
@@ -2140,6 +2190,32 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
|
||||
**explore_attempt = None**
|
||||
**skel_kind = skeleton**
|
||||
**events = > json.parse text=[]**
|
||||
**eng = None**
|
||||
|
||||
1. `eng_preflight`
|
||||
**eng = > agent_eng_preflight task=`goal` marqdo_dir=`marqdo_dir` allow_create_after=`allow_create_after`**
|
||||
**eng_status = > json.get value=`eng` key="status"**
|
||||
**eng_decision = > json.get value=`eng` key="decision"**
|
||||
**eng_allowed = > json.get value=`eng` key="create_allowed"**
|
||||
1. `eng_status` == missing_knowledge
|
||||
**_ = 1**
|
||||
2. `eng_decision` == REUSE
|
||||
> agent_eng_record decision="REUSE" marqdo_dir=`marqdo_dir`
|
||||
**_ = 1**
|
||||
3. `eng_decision` == ADAPT
|
||||
> agent_eng_record decision="ADAPT" marqdo_dir=`marqdo_dir`
|
||||
**_ = 1**
|
||||
4. `eng_allowed`
|
||||
> agent_eng_record decision="CREATE" marqdo_dir=`marqdo_dir`
|
||||
**_ = 1**
|
||||
5. *
|
||||
**out = > json.parse text={"status":"blocked","cache":"eng-block","eng":true}**
|
||||
**out = > json.set map=`out` key="decision" value="BLOCKED"**
|
||||
**out = > json.set map=`out` key="preflight" value=`eng`**
|
||||
**out = > json.set map=`out` key="events" value=`events`**
|
||||
*out*
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
**tf = > agent_kb_task_files kb_dir=`kb_dir` goal=`goal` tools=`tools`**
|
||||
**nfiles = > json.get value=`tf` key="count"**
|
||||
|
||||
+10
-1
@@ -289,11 +289,20 @@ Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
Hoist receiver fields before the result table — table cells can shadow `self` /
|
||||
column names (`model`, `usage`), so `[model](self)` / `[total_tokens](usage)`
|
||||
inside the table is unsafe.
|
||||
|
||||
**mdl = [model](self)**
|
||||
**b = [backend](self)**
|
||||
**nm = [name](self)**
|
||||
**tt = [total_tokens](usage)**
|
||||
|
||||
`result` =
|
||||
|
||||
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls |
|
||||
|------|-------|--------|---------|-------|------|-----------|--------|------------|
|
||||
| `text` | [model](self) | `finish` | [backend](self) | `usage` | [name](self) | 1 | [total_tokens](usage) | `tc` |
|
||||
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | 1 | `tt` | `tc` |
|
||||
|
||||
*result*
|
||||
|
||||
|
||||
+8
-1
@@ -240,11 +240,18 @@ import openai:ext/ai/llm/openai.mq.md
|
||||
2. *
|
||||
**_ = 1**
|
||||
|
||||
表单元格会遮蔽 `自` / 列名,先取出字段再组结果表。
|
||||
|
||||
**mdl = [model](自)**
|
||||
**b = [backend](自)**
|
||||
**nm = [name](自)**
|
||||
**tt = [total_tokens](usage)**
|
||||
|
||||
`result` =
|
||||
|
||||
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls |
|
||||
|------|-------|--------|---------|-------|------|-----------|--------|------------|
|
||||
| `text` | [model](自) | `finish` | [backend](自) | `usage` | [name](自) | 1 | [total_tokens](usage) | `tc` |
|
||||
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | 1 | `tt` | `tc` |
|
||||
|
||||
*result*
|
||||
|
||||
|
||||
+13
-2
@@ -183,6 +183,15 @@ import json:lib/json.mq.md
|
||||
|
||||
*out*
|
||||
|
||||
## 工程预检
|
||||
+ `任务`
|
||||
+ `根目录`="."
|
||||
+ `知识目录`=None
|
||||
|
||||
Engineering First Information 门闩。转发 `agent.preflight`。
|
||||
|
||||
*> agent.preflight task=`任务` root=`根目录` marqdo_dir=`知识目录`*
|
||||
|
||||
## 多步
|
||||
+ `目标`
|
||||
+ `工作簿目录`=None
|
||||
@@ -204,14 +213,16 @@ import json:lib/json.mq.md
|
||||
+ `流式`=False
|
||||
+ `打印增量`=False
|
||||
+ `轨迹`=False
|
||||
+ `工程预检`=False
|
||||
+ `工程知识目录`=.marqdo
|
||||
|
||||
多步工作簿默认写入 OKF `知识库目录/resources/<slug>.mq.md`;仅当传入 `工作簿目录` 时才用临时 runs。转发至英文 `agent.plan`。`流式` / `打印增量` / `轨迹` 对应 `stream` / `echo` / `trace`;`软命中` → `soft_match`;`近义命中` / `近义阈值` → `near_match` / `near_threshold`。
|
||||
多步工作簿默认写入 OKF `知识库目录/resources/<slug>.mq.md`;仅当传入 `工作簿目录` 时才用临时 runs。转发至英文 `agent.plan`。`流式` / `打印增量` / `轨迹` 对应 `stream` / `echo` / `trace`;`软命中` → `soft_match`;`近义命中` / `近义阈值` → `near_match` / `near_threshold`。`工程预检` → `eng_preflight`。
|
||||
|
||||
**model = > json.get value=`self` key="model"**
|
||||
**tools = > json.get value=`self` key="tools"**
|
||||
**standing = > json.get value=`self` key="standing"**
|
||||
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
|
||||
*> en.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` soft_match=`软命中` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数` stream=`流式` echo=`打印增量` trace=`轨迹`*
|
||||
*> en.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` soft_match=`软命中` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数` stream=`流式` echo=`打印增量` trace=`轨迹` eng_preflight=`工程预检` marqdo_dir=`工程知识目录`*
|
||||
|
||||
## 解析
|
||||
+ `任务`
|
||||
|
||||
+3
-2
@@ -1,9 +1,10 @@
|
||||
---
|
||||
title: ext/net/url
|
||||
description: URL helpers (stdlib host wrappers). ADR 0007.
|
||||
description: URL helpers (stdlib wrappers). ADR 0007.
|
||||
import net:lib/net.mq.md
|
||||
---
|
||||
|
||||
## encode
|
||||
+ `text`
|
||||
|
||||
*> host_url_encode text=`text`*
|
||||
*> net.url_encode text=`text`*
|
||||
+11
-1
@@ -21,11 +21,21 @@ import sys:lib/sys.mq.md
|
||||
+ `client_id`
|
||||
+ `client_secret`
|
||||
+ `redirect_uri`
|
||||
+ `redirect_origins`=None
|
||||
+ `scopes`="openid profile email"
|
||||
+ `callback_path`=None
|
||||
+ `authorize_url`=None
|
||||
+ `token_url`=None
|
||||
+ `userinfo_url`=None
|
||||
|
||||
`redirect_uri` may be an absolute URL (`https://qdqc.com/oidc/callback`) or a path
|
||||
(`/oidc/callback`). Path mode resolves the absolute callback from the login request
|
||||
Host (`X-Forwarded-Proto` / `X-Forwarded-Host` when behind a reverse proxy) and stores
|
||||
it in the session so token exchange uses the same string.
|
||||
|
||||
Optional `redirect_origins` is a comma-separated allowlist
|
||||
(`https://qdqc.com,https://www.qdqc.com`). When set, path-mode origins must match.
|
||||
The IdP must still register every absolute callback URL that will be used.
|
||||
|
||||
> _load
|
||||
*> web_app_oidc app=`app` issuer=`issuer` client_id=`client_id` client_secret=`client_secret` redirect_uri=`redirect_uri` scopes=`scopes` callback_path=`callback_path` authorize_url=`authorize_url` token_url=`token_url` userinfo_url=`userinfo_url`*
|
||||
*> web_app_oidc app=`app` issuer=`issuer` client_id=`client_id` client_secret=`client_secret` redirect_uri=`redirect_uri` redirect_origins=`redirect_origins` scopes=`scopes` callback_path=`callback_path` authorize_url=`authorize_url` token_url=`token_url` userinfo_url=`userinfo_url`*
|
||||
+2
-2
@@ -11,7 +11,7 @@ Persist run output in .mq.md (Jupyter-style writeback)
|
||||
+ `key`=None
|
||||
+ `line`=None
|
||||
|
||||
Write `value` to `<!-- marqdo-out … -->` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` replaces the unkeyed EOF block. With `key=` (e.g. `ok` / `error`), replace or create that named slot only — slots do not overwrite each other. Optional `line=` anchors the block under that source line (needed when writing from a subtask).
|
||||
Write `value` into the entry file. Image-like values (`.png` / `.svg` / … or `data:image/…`) become `` (or ``); other values use `<!-- marqdo-out … -->`. Default: insert or replace the block immediately below the call; `at_end=true` replaces the unkeyed EOF block. With `key=` (e.g. `ok` / `error`), replace or create that named slot only — slots do not overwrite each other. Optional `line=` anchors the block under that source line (needed when writing from a subtask).
|
||||
|
||||
*> host_writeback_record value=`value` at_end=`at_end` key=`key` line=`line`*
|
||||
|
||||
@@ -51,6 +51,6 @@ List all output blocks in the entry file (includes `key` when named).
|
||||
## scan_path
|
||||
+ `path`
|
||||
|
||||
List `<!-- marqdo-out … -->` slots in any file (workbook inspection).
|
||||
List writeback slots in any file (HTML comment and `` image forms; workbook inspection).
|
||||
|
||||
*> host_writeback_scan_path path=`path`*
|
||||
+2
-2
@@ -11,7 +11,7 @@ description: 将运行结果写回 .mq.md(Jupyter 式自写回)
|
||||
+ `键`=None
|
||||
+ `行`=None
|
||||
|
||||
在入口文件中写入 `<!-- marqdo-out … -->`。默认在调用行下方插入或替换;`末尾=true` 时替换无键末尾块。带 `键=`(如 `ok` / `error` / `成功` / `失败`)时只更新该命名槽,互不覆盖。可选 `行=` 锚定到指定源码行(子任务写回时需要)。
|
||||
在入口文件中写入自写回块:若 `值` 像图片路径/URL(`.png` / `.svg` / … 或 `data:image/…`)则写成 ``,否则写成 `<!-- marqdo-out … -->`。默认在调用行下方插入或替换;`末尾=true` 时替换无键末尾块。带 `键=`(如 `ok` / `error` / `成功` / `失败`)时只更新该命名槽,互不覆盖。可选 `行=` 锚定到指定源码行(子任务写回时需要)。
|
||||
|
||||
*> host_writeback_record value=`值` at_end=`末尾` key=`键` line=`行`*
|
||||
|
||||
@@ -51,6 +51,6 @@ description: 将运行结果写回 .mq.md(Jupyter 式自写回)
|
||||
## 扫描路径
|
||||
+ `路径`
|
||||
|
||||
扫描任意文件中的 `<!-- marqdo-out … -->` 槽(工作簿观察)。
|
||||
扫描任意文件中的自写回槽(注释块与 `` 图片;工作簿观察)。
|
||||
|
||||
*> host_writeback_scan_path path=`路径`*
|
||||
@@ -0,0 +1,497 @@
|
||||
//! Engineering Knowledge preflight / reuse (reads `.marqdo` projections).
|
||||
//! Does not call host_* — consumes compiled knowledge graph artifacts.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
|
||||
args.get(key)
|
||||
.and_then(|v| v.as_str())
|
||||
.ok_or_else(|| format!("missing string arg `{key}`"))
|
||||
}
|
||||
|
||||
fn arg_f64(args: &Value, key: &str, default: f64) -> f64 {
|
||||
match args.get(key) {
|
||||
Some(Value::Number(n)) => n.as_f64().unwrap_or(default),
|
||||
Some(Value::String(s)) => s.parse().unwrap_or(default),
|
||||
_ => default,
|
||||
}
|
||||
}
|
||||
|
||||
fn arg_usize(args: &Value, key: &str, default: usize) -> usize {
|
||||
match args.get(key) {
|
||||
Some(Value::Number(n)) => n.as_u64().unwrap_or(default as u64) as usize,
|
||||
Some(Value::String(s)) => s.parse().unwrap_or(default),
|
||||
_ => default,
|
||||
}
|
||||
}
|
||||
|
||||
fn char_bigram_tf(text: &str) -> HashMap<String, f64> {
|
||||
let chars: Vec<char> = text.chars().filter(|c| !c.is_whitespace()).collect();
|
||||
let mut m = HashMap::new();
|
||||
if chars.is_empty() {
|
||||
return m;
|
||||
}
|
||||
if chars.len() == 1 {
|
||||
m.insert(chars[0].to_string(), 1.0);
|
||||
return m;
|
||||
}
|
||||
for w in chars.windows(2) {
|
||||
let key: String = w.iter().collect();
|
||||
*m.entry(key).or_insert(0.0) += 1.0;
|
||||
}
|
||||
m
|
||||
}
|
||||
|
||||
fn cosine_tf(a: &HashMap<String, f64>, b: &HashMap<String, f64>) -> f64 {
|
||||
let mut na = 0.0;
|
||||
let mut nb = 0.0;
|
||||
for v in a.values() {
|
||||
na += v * v;
|
||||
}
|
||||
for v in b.values() {
|
||||
nb += v * v;
|
||||
}
|
||||
if na == 0.0 || nb == 0.0 {
|
||||
return 0.0;
|
||||
}
|
||||
let mut dot = 0.0;
|
||||
for (k, va) in a {
|
||||
if let Some(vb) = b.get(k) {
|
||||
dot += va * vb;
|
||||
}
|
||||
}
|
||||
dot / (na.sqrt() * nb.sqrt())
|
||||
}
|
||||
|
||||
|
||||
fn resolve_marqdo_root(start: &str) -> PathBuf {
|
||||
let mut cur = PathBuf::from(start);
|
||||
if cur.is_file() {
|
||||
if let Some(p) = cur.parent() {
|
||||
cur = p.to_path_buf();
|
||||
}
|
||||
}
|
||||
for _ in 0..8 {
|
||||
let cand = cur.join(".marqdo");
|
||||
if cand.join("engineering.yaml").exists() || cand.join("graph/graph.json").exists() {
|
||||
return cand;
|
||||
}
|
||||
if !cur.pop() {
|
||||
break;
|
||||
}
|
||||
}
|
||||
PathBuf::from(start).join(".marqdo")
|
||||
}
|
||||
|
||||
#[derive(Clone)]
|
||||
struct CapHit {
|
||||
id: String,
|
||||
name: String,
|
||||
score: f64,
|
||||
implemented_by: Vec<String>,
|
||||
}
|
||||
|
||||
fn load_capabilities(marqdo: &Path) -> Vec<(String, String, Vec<String>, String)> {
|
||||
// returns (id, name, implemented_by, material)
|
||||
let mut out = Vec::new();
|
||||
let eng = marqdo.join("engineering.yaml");
|
||||
if let Ok(raw) = fs::read_to_string(&eng) {
|
||||
let mut cur_id = String::new();
|
||||
let mut cur_name = String::new();
|
||||
let mut impls = Vec::new();
|
||||
let mut in_caps = false;
|
||||
let mut in_impl = false;
|
||||
for line in raw.lines() {
|
||||
let t = line.trim_end();
|
||||
if t.trim() == "capabilities:" {
|
||||
in_caps = true;
|
||||
continue;
|
||||
}
|
||||
if in_caps && !line.starts_with(' ') && !line.starts_with('\t') && !t.trim().is_empty()
|
||||
{
|
||||
if t.trim() == "knowledge:" {
|
||||
if !cur_id.is_empty() {
|
||||
out.push((
|
||||
cur_id.clone(),
|
||||
cur_name.clone(),
|
||||
impls.clone(),
|
||||
format!("{cur_name} {cur_id}"),
|
||||
));
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
if !in_caps {
|
||||
continue;
|
||||
}
|
||||
let trimmed = t.trim();
|
||||
if let Some(rest) = trimmed.strip_prefix("- id:") {
|
||||
if !cur_id.is_empty() {
|
||||
out.push((
|
||||
cur_id.clone(),
|
||||
cur_name.clone(),
|
||||
impls.clone(),
|
||||
format!("{cur_name} {cur_id}"),
|
||||
));
|
||||
}
|
||||
cur_id = rest.trim().trim_matches('"').to_string();
|
||||
cur_name.clear();
|
||||
impls.clear();
|
||||
in_impl = false;
|
||||
} else if let Some(rest) = trimmed.strip_prefix("name:") {
|
||||
cur_name = rest.trim().trim_matches('"').to_string();
|
||||
} else if trimmed == "implemented_by:" {
|
||||
in_impl = true;
|
||||
} else if in_impl {
|
||||
if let Some(rest) = trimmed.strip_prefix("- ") {
|
||||
impls.push(rest.trim().trim_matches('"').to_string());
|
||||
} else if !trimmed.is_empty() && !line.starts_with(' ') {
|
||||
in_impl = false;
|
||||
}
|
||||
}
|
||||
}
|
||||
if !cur_id.is_empty() {
|
||||
out.push((
|
||||
cur_id.clone(),
|
||||
cur_name.clone(),
|
||||
impls,
|
||||
format!("{cur_name} {cur_id}"),
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
// Also scan catalog/capabilities/*.md
|
||||
let cap_dir = marqdo.join("catalog/capabilities");
|
||||
if let Ok(rd) = fs::read_dir(cap_dir) {
|
||||
for ent in rd.flatten() {
|
||||
let p = ent.path();
|
||||
if !p
|
||||
.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.map(|s| s.ends_with(".md"))
|
||||
.unwrap_or(false)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
let Ok(src) = fs::read_to_string(&p) else {
|
||||
continue;
|
||||
};
|
||||
let id = fm_field(&src, "id").unwrap_or_else(|| {
|
||||
p.file_stem()
|
||||
.and_then(|s| s.to_str())
|
||||
.unwrap_or("cap")
|
||||
.to_string()
|
||||
});
|
||||
let name = fm_field(&src, "name").unwrap_or_else(|| id.clone());
|
||||
if out.iter().any(|(i, _, _, _)| i == &id) {
|
||||
continue;
|
||||
}
|
||||
out.push((id.clone(), name.clone(), Vec::new(), format!("{name} {id} {src}")));
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn fm_field(source: &str, key: &str) -> Option<String> {
|
||||
let prefix = format!("{key}:");
|
||||
for line in source.lines() {
|
||||
let t = line.trim();
|
||||
if t == "---" {
|
||||
continue;
|
||||
}
|
||||
if let Some(rest) = t.strip_prefix(&prefix) {
|
||||
return Some(rest.trim().trim_matches('"').to_string());
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn load_knowledge_titles(marqdo: &Path, kind_subdir: &str) -> Vec<(String, String)> {
|
||||
let dir = marqdo.join("knowledge").join(kind_subdir);
|
||||
let mut out = Vec::new();
|
||||
let Ok(rd) = fs::read_dir(dir) else {
|
||||
return out;
|
||||
};
|
||||
for ent in rd.flatten() {
|
||||
let p = ent.path();
|
||||
let Ok(src) = fs::read_to_string(&p) else {
|
||||
continue;
|
||||
};
|
||||
let id = fm_field(&src, "id").unwrap_or_else(|| {
|
||||
p.file_stem()
|
||||
.and_then(|s| s.to_str())
|
||||
.unwrap_or("k")
|
||||
.to_string()
|
||||
});
|
||||
let title = fm_field(&src, "title").unwrap_or_else(|| id.clone());
|
||||
out.push((id, title));
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn rank_caps(task: &str, caps: &[(String, String, Vec<String>, String)]) -> Vec<CapHit> {
|
||||
let qv = char_bigram_tf(task);
|
||||
let mut hits = Vec::new();
|
||||
for (id, name, impls, material) in caps {
|
||||
let mut score = cosine_tf(&qv, &char_bigram_tf(material));
|
||||
if name.to_ascii_lowercase().contains(&task.to_ascii_lowercase())
|
||||
|| task
|
||||
.to_ascii_lowercase()
|
||||
.split_whitespace()
|
||||
.any(|t| t.len() > 2 && name.to_ascii_lowercase().contains(t))
|
||||
{
|
||||
score = (score + 0.35).min(1.0);
|
||||
}
|
||||
if score > 0.12 {
|
||||
hits.push(CapHit {
|
||||
id: id.clone(),
|
||||
name: name.clone(),
|
||||
score,
|
||||
implemented_by: impls.clone(),
|
||||
});
|
||||
}
|
||||
}
|
||||
hits.sort_by(|a, b| {
|
||||
b.score
|
||||
.partial_cmp(&a.score)
|
||||
.unwrap_or(std::cmp::Ordering::Equal)
|
||||
});
|
||||
hits
|
||||
}
|
||||
|
||||
fn relevant_knowledge(task: &str, items: &[(String, String)], cap_names: &[String]) -> Vec<String> {
|
||||
let task_l = task.to_ascii_lowercase();
|
||||
items
|
||||
.iter()
|
||||
.filter(|(id, title)| {
|
||||
let m = format!("{id} {title}").to_ascii_lowercase();
|
||||
task_l.split_whitespace().any(|t| t.len() > 3 && m.contains(t))
|
||||
|| cap_names.iter().any(|c| m.contains(&c.to_ascii_lowercase()))
|
||||
})
|
||||
.map(|(id, title)| format!("{title} ({id})"))
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// `agent_eng_preflight` — Engineering First Information gate.
|
||||
pub fn eng_preflight(args: &Value) -> Result<Value, String> {
|
||||
let task = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?;
|
||||
let root = args
|
||||
.get("root")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or(".");
|
||||
let marqdo = args
|
||||
.get("marqdo_dir")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(PathBuf::from)
|
||||
.unwrap_or_else(|| resolve_marqdo_root(root));
|
||||
|
||||
if !marqdo.join("engineering.yaml").exists() && !marqdo.join("graph/graph.json").exists() {
|
||||
return Ok(json!({
|
||||
"status": "missing_knowledge",
|
||||
"create_allowed": false,
|
||||
"decision": "CREATE",
|
||||
"error": "run `marqdo knowledge` first",
|
||||
"existing": [],
|
||||
"recommended": [],
|
||||
}));
|
||||
}
|
||||
|
||||
let reuse_threshold = arg_f64(args, "reuse_threshold", 0.72);
|
||||
let adapt_threshold = arg_f64(args, "adapt_threshold", 0.45);
|
||||
let allow_create_after = arg_usize(args, "allow_create_after", 2);
|
||||
let min_candidates = arg_usize(args, "min_candidates", 3);
|
||||
|
||||
let caps = load_capabilities(&marqdo);
|
||||
let ranked = rank_caps(task, &caps);
|
||||
let existing: Vec<String> = ranked.iter().take(8).map(|c| c.name.clone()).collect();
|
||||
let cap_names = existing.clone();
|
||||
|
||||
let constraints = relevant_knowledge(
|
||||
task,
|
||||
&load_knowledge_titles(&marqdo, "constraints"),
|
||||
&cap_names,
|
||||
);
|
||||
let decisions = relevant_knowledge(
|
||||
task,
|
||||
&load_knowledge_titles(&marqdo, "decisions"),
|
||||
&cap_names,
|
||||
);
|
||||
let failures = relevant_knowledge(
|
||||
task,
|
||||
&load_knowledge_titles(&marqdo, "failures"),
|
||||
&cap_names,
|
||||
);
|
||||
|
||||
let best = ranked.first();
|
||||
let best_score = best.map(|c| c.score).unwrap_or(0.0);
|
||||
let analyzed = ranked.len().max(1).min(min_candidates.max(allow_create_after));
|
||||
|
||||
let (decision, create_allowed, recommended, reason) = if best_score >= reuse_threshold {
|
||||
let b = best.unwrap();
|
||||
(
|
||||
"REUSE",
|
||||
false,
|
||||
vec![format!("REUSE {}", b.name)],
|
||||
vec![
|
||||
"score meets REUSE threshold".into(),
|
||||
"same capability semantics".into(),
|
||||
],
|
||||
)
|
||||
} else if best_score >= adapt_threshold {
|
||||
let b = best.unwrap();
|
||||
(
|
||||
"ADAPT",
|
||||
false,
|
||||
vec![format!("ADAPT {}", b.name)],
|
||||
vec!["near match — wrap/compose/extend".into()],
|
||||
)
|
||||
} else if analyzed >= allow_create_after {
|
||||
(
|
||||
"CREATE",
|
||||
true,
|
||||
vec!["CREATE new capability".into()],
|
||||
vec!["no existing capability satisfies constraints".into()],
|
||||
)
|
||||
} else {
|
||||
(
|
||||
"CREATE",
|
||||
false,
|
||||
vec![],
|
||||
vec![format!(
|
||||
"insufficient candidates ({analyzed} < {allow_create_after})"
|
||||
)],
|
||||
)
|
||||
};
|
||||
|
||||
// Write context pack
|
||||
let contexts = marqdo.join("agent/contexts");
|
||||
let _ = fs::create_dir_all(&contexts);
|
||||
let mut h: u64 = 5381;
|
||||
for b in task.as_bytes() {
|
||||
h = h.wrapping_mul(33).wrapping_add(u64::from(*b));
|
||||
}
|
||||
let tid = format!("{h:016x}")[..12].to_string();
|
||||
let ctx_path = contexts.join(format!("task-{tid}.mq.md"));
|
||||
let pack = format!(
|
||||
"---\ntype: Marqdo Context Pack\ntitle: Engineering Context\ndecision: {decision}\ncreate_allowed: {create_allowed}\n---\n\n# Engineering Context\n\n## Task\n\n{task}\n\n## Existing Capabilities\n\n{existing}\n\n## Recommended Reuse\n\n{recommended}\n",
|
||||
existing = existing
|
||||
.iter()
|
||||
.map(|e| format!("- {e}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n"),
|
||||
recommended = recommended
|
||||
.iter()
|
||||
.enumerate()
|
||||
.map(|(i, r)| format!("{}. {r}", i + 1))
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n"),
|
||||
);
|
||||
let _ = fs::write(&ctx_path, pack);
|
||||
|
||||
let status = if create_allowed {
|
||||
"ready_create"
|
||||
} else if decision == "REUSE" || decision == "ADAPT" {
|
||||
"ready"
|
||||
} else if decision == "CREATE" && !create_allowed {
|
||||
"blocked"
|
||||
} else {
|
||||
"ready"
|
||||
};
|
||||
|
||||
Ok(json!({
|
||||
"status": status,
|
||||
"intent": { "capability": best.map(|c| c.name.clone()).unwrap_or_else(|| task.to_string()) },
|
||||
"existing": existing,
|
||||
"constraints": constraints,
|
||||
"decisions": decisions,
|
||||
"failures": failures,
|
||||
"recommended": recommended,
|
||||
"create_allowed": create_allowed,
|
||||
"decision": decision,
|
||||
"confidence": best_score,
|
||||
"reason": reason,
|
||||
"context_path": ctx_path.display().to_string(),
|
||||
"candidates": ranked.iter().take(8).map(|c| json!({
|
||||
"id": c.id,
|
||||
"name": c.name,
|
||||
"score": c.score,
|
||||
"implemented_by": c.implemented_by,
|
||||
})).collect::<Vec<_>>(),
|
||||
}))
|
||||
}
|
||||
|
||||
/// `agent_eng_reuse` — alias of preflight focused on decision payload.
|
||||
pub fn eng_reuse(args: &Value) -> Result<Value, String> {
|
||||
let mut pf = eng_preflight(args)?;
|
||||
if let Some(obj) = pf.as_object_mut() {
|
||||
obj.insert(
|
||||
"protocol".into(),
|
||||
json!("REUSE|ADAPT|CREATE"),
|
||||
);
|
||||
}
|
||||
Ok(pf)
|
||||
}
|
||||
|
||||
/// `agent_eng_record` — append reuse metrics under `.marqdo/agent/episodes`.
|
||||
pub fn eng_record(args: &Value) -> Result<Value, String> {
|
||||
let decision = arg_text(args, "decision")?;
|
||||
let root = args
|
||||
.get("root")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or(".");
|
||||
let marqdo = args
|
||||
.get("marqdo_dir")
|
||||
.and_then(|v| v.as_str())
|
||||
.map(PathBuf::from)
|
||||
.unwrap_or_else(|| resolve_marqdo_root(root));
|
||||
let duplicated = matches!(args.get("duplicated"), Some(Value::Bool(true)));
|
||||
|
||||
let path = marqdo.join("agent/episodes/reuse_metrics.json");
|
||||
if let Some(p) = path.parent() {
|
||||
let _ = fs::create_dir_all(p);
|
||||
}
|
||||
let mut m = if let Ok(raw) = fs::read_to_string(&path) {
|
||||
serde_json::from_str::<Value>(&raw).unwrap_or(json!({}))
|
||||
} else {
|
||||
json!({})
|
||||
};
|
||||
let get_u = |v: &Value, k: &str| v.get(k).and_then(|x| x.as_u64()).unwrap_or(0);
|
||||
let mut reused = get_u(&m, "reused");
|
||||
let mut adapted = get_u(&m, "adapted");
|
||||
let mut created = get_u(&m, "created");
|
||||
let mut dups = get_u(&m, "duplicated");
|
||||
match decision.to_ascii_uppercase().as_str() {
|
||||
"REUSE" => reused += 1,
|
||||
"ADAPT" => adapted += 1,
|
||||
"CREATE" => {
|
||||
created += 1;
|
||||
if duplicated {
|
||||
dups += 1;
|
||||
}
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
m = json!({
|
||||
"generated_functions": get_u(&m, "generated_functions") + 1,
|
||||
"reused": reused,
|
||||
"adapted": adapted,
|
||||
"created": created,
|
||||
"duplicated": dups,
|
||||
});
|
||||
let gen = m["generated_functions"].as_u64().unwrap_or(1) as f64;
|
||||
m["reuse_ratio"] = json!(reused as f64 / gen);
|
||||
m["adapt_ratio"] = json!(adapted as f64 / gen);
|
||||
m["novel_ratio"] = json!(created as f64 / gen);
|
||||
m["duplication_rate"] = json!(if created == 0 {
|
||||
0.0
|
||||
} else {
|
||||
dups as f64 / created as f64
|
||||
});
|
||||
fs::write(&path, serde_json::to_string_pretty(&m).unwrap_or_default())
|
||||
.map_err(|e| e.to_string())?;
|
||||
Ok(m)
|
||||
}
|
||||
@@ -1,6 +1,7 @@
|
||||
//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route.
|
||||
|
||||
mod corpus;
|
||||
mod eng;
|
||||
mod kb;
|
||||
mod mcp_client;
|
||||
mod mcp_server;
|
||||
@@ -930,6 +931,9 @@ kb_ffi!(agent_resume_save, resume::resume_save, "agent_resume_save");
|
||||
kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load");
|
||||
kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear");
|
||||
kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list");
|
||||
kb_ffi!(agent_eng_preflight, eng::eng_preflight, "agent_eng_preflight");
|
||||
kb_ffi!(agent_eng_reuse, eng::eng_reuse, "agent_eng_reuse");
|
||||
kb_ffi!(agent_eng_record, eng::eng_record, "agent_eng_record");
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
@@ -1155,6 +1159,27 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_eng_preflight",
|
||||
"task",
|
||||
agent_eng_preflight,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_eng_reuse", "task", agent_eng_reuse) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_eng_record",
|
||||
"decision",
|
||||
agent_eng_record,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
|
||||
@@ -256,6 +256,9 @@ func OIDC(appBag map[string]any, opts map[string]any) (map[string]any, error) {
|
||||
"scopes": cfg.ScopesCSV(),
|
||||
"callback_path": cfg.Callback(),
|
||||
}
|
||||
if cfg.RedirectOrigins != "" {
|
||||
bag["redirect_origins"] = cfg.RedirectOrigins
|
||||
}
|
||||
if cfg.AuthorizeURL != "" {
|
||||
bag["authorize_url"] = cfg.AuthorizeURL
|
||||
}
|
||||
|
||||
@@ -117,11 +117,17 @@ func (st *state) handleOIDCStart(w http.ResponseWriter, r *http.Request) {
|
||||
http.Error(w, err.Error(), http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
redirectURI, err := st.oidc.ResolveRedirectURI(r)
|
||||
if err != nil {
|
||||
http.Error(w, err.Error(), http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
session.SetValue(sid, "oidc_state", state)
|
||||
session.SetValue(sid, "oidc_verifier", verifier)
|
||||
session.SetValue(sid, "oidc_redirect_uri", redirectURI)
|
||||
next := loginDest(r, st.oidcFallbackNext(r))
|
||||
session.SetValue(sid, "oidc_next", next)
|
||||
loc, err := st.oidc.AuthorizeRedirect(state, oidc.PKCEChallengeS256(verifier))
|
||||
loc, err := st.oidc.AuthorizeRedirect(state, oidc.PKCEChallengeS256(verifier), redirectURI)
|
||||
if err != nil {
|
||||
http.Error(w, err.Error(), http.StatusInternalServerError)
|
||||
return
|
||||
@@ -164,6 +170,15 @@ func (st *state) handleOIDCCallback(w http.ResponseWriter, r *http.Request) {
|
||||
}
|
||||
verifier, _ := session.GetValue(sid, "oidc_verifier")
|
||||
verifierS, _ := verifier.(string)
|
||||
redirVal, _ := session.GetValue(sid, "oidc_redirect_uri")
|
||||
redirectURI, _ := redirVal.(string)
|
||||
if redirectURI == "" && !st.oidc.IsPathRedirect() {
|
||||
redirectURI = strings.TrimSpace(st.oidc.RedirectURI)
|
||||
}
|
||||
if redirectURI == "" {
|
||||
http.Error(w, "oidc: missing redirect_uri in session", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
nextVal, _ := session.GetValue(sid, "oidc_next")
|
||||
next, _ := nextVal.(string)
|
||||
if next == "" {
|
||||
@@ -171,9 +186,10 @@ func (st *state) handleOIDCCallback(w http.ResponseWriter, r *http.Request) {
|
||||
}
|
||||
session.DelKey(sid, "oidc_state")
|
||||
session.DelKey(sid, "oidc_verifier")
|
||||
session.DelKey(sid, "oidc_redirect_uri")
|
||||
session.DelKey(sid, "oidc_next")
|
||||
|
||||
tok, err := st.oidc.ExchangeCode(oidcClient(), code, verifierS)
|
||||
tok, err := st.oidc.ExchangeCode(oidcClient(), code, verifierS, redirectURI)
|
||||
if err != nil {
|
||||
http.Error(w, "oidc token exchange: "+err.Error(), http.StatusBadGateway)
|
||||
return
|
||||
|
||||
@@ -247,6 +247,7 @@ func NewHandler(appBag map[string]any, entryDir string) (http.Handler, error) {
|
||||
handler := withMiddleware(mux, mw)
|
||||
handler = withRBAC(handler, authCfg.gates, authCfg.loginPath)
|
||||
handler = withTenant(handler, st.tenant)
|
||||
handler = withStripTrailingSlash(handler)
|
||||
return handler, nil
|
||||
}
|
||||
|
||||
@@ -641,6 +642,21 @@ func withTenant(next http.Handler, cfg tenant.Config) http.Handler {
|
||||
})
|
||||
}
|
||||
|
||||
// withStripTrailingSlash rewrites request URLs so that paths like /post/foo/
|
||||
// are routed as /post/foo. The root path "/" is left unchanged.
|
||||
func withStripTrailingSlash(next http.Handler) http.Handler {
|
||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
path := r.URL.Path
|
||||
if len(path) > 1 && path[len(path)-1] == '/' {
|
||||
r.URL.Path = strings.TrimRight(path, "/")
|
||||
if r.URL.Path == "" {
|
||||
r.URL.Path = "/"
|
||||
}
|
||||
}
|
||||
next.ServeHTTP(w, r)
|
||||
})
|
||||
}
|
||||
|
||||
func withMiddleware(next http.Handler, mw middleware.Config) http.Handler {
|
||||
h := next
|
||||
if mw.BodyLimit != nil && *mw.BodyLimit > 0 {
|
||||
|
||||
@@ -152,3 +152,65 @@ func TestNewHandlerIconsRedirectSitemap404(t *testing.T) {
|
||||
t.Fatalf("home missing icon link: %s", rec.Body.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestTrailingSlashNormalization(t *testing.T) {
|
||||
page := map[string]any{"title": "Home", "intro": "<p>home</p>"}
|
||||
a := app.New(map[string]any{"page": page})
|
||||
about := map[string]any{"title": "About", "intro": "<h1>About</h1>", "_route": "/about"}
|
||||
var err error
|
||||
a, err = app.Route(a, "/about", about)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
// Dynamic route: /post/{slug}
|
||||
post := map[string]any{"title": "Post", "intro": "<h1>Post</h1>", "_route": "/post/{slug}"}
|
||||
a, err = app.Route(a, "/post/{slug}", post)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
h, err := httpx.NewHandler(a, "")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
// Static route: /about should work with and without trailing slash.
|
||||
rec := httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/about", nil))
|
||||
if rec.Code != 200 || !strings.Contains(rec.Body.String(), "About") {
|
||||
t.Fatalf("about (no slash) code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
|
||||
rec = httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/about/", nil))
|
||||
if rec.Code != 200 || !strings.Contains(rec.Body.String(), "About") {
|
||||
t.Fatalf("about (trailing slash) code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
|
||||
// Dynamic route: /post/hello should work with and without trailing slash.
|
||||
rec = httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/post/hello", nil))
|
||||
if rec.Code != 200 {
|
||||
t.Fatalf("post/hello (no slash) code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
|
||||
rec = httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/post/hello/", nil))
|
||||
if rec.Code != 200 {
|
||||
t.Fatalf("post/hello (trailing slash) code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
|
||||
// Root path "/" should still work.
|
||||
rec = httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/", nil))
|
||||
if rec.Code != 200 || !strings.Contains(rec.Body.String(), "Home") {
|
||||
t.Fatalf("root code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
|
||||
// Query string should be preserved after trailing slash strip.
|
||||
rec = httptest.NewRecorder()
|
||||
h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/about/?foo=bar", nil))
|
||||
if rec.Code != 200 || !strings.Contains(rec.Body.String(), "About") {
|
||||
t.Fatalf("about (trailing slash + query) code=%d body=%q", rec.Code, rec.Body.String())
|
||||
}
|
||||
}
|
||||
@@ -20,8 +20,11 @@ type Config struct {
|
||||
ClientID string
|
||||
ClientSecret string
|
||||
RedirectURI string
|
||||
Scopes string
|
||||
CallbackPath string
|
||||
// RedirectOrigins is an optional comma-separated allowlist of origins
|
||||
// (e.g. "https://qdqc.com,https://www.qdqc.com") used when RedirectURI is a path.
|
||||
RedirectOrigins string
|
||||
Scopes string
|
||||
CallbackPath string
|
||||
// AuthorizeURL / TokenURL / UserInfoURL override discovery when set.
|
||||
AuthorizeURL string
|
||||
TokenURL string
|
||||
@@ -36,11 +39,35 @@ func (c Config) Enabled() bool {
|
||||
(strings.TrimSpace(c.Issuer) != "" || strings.TrimSpace(c.AuthorizeURL) != "")
|
||||
}
|
||||
|
||||
// IsPathRedirect reports whether RedirectURI is a path (resolved per request Host).
|
||||
func (c Config) IsPathRedirect() bool {
|
||||
s := strings.TrimSpace(c.RedirectURI)
|
||||
if s == "" {
|
||||
return false
|
||||
}
|
||||
if strings.HasPrefix(s, "/") {
|
||||
return true
|
||||
}
|
||||
u, err := url.Parse(s)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
// scheme-relative or bare path without host
|
||||
return u.Scheme == "" && u.Host == "" && u.Path != ""
|
||||
}
|
||||
|
||||
// Callback reports the local path (default /oidc/callback).
|
||||
func (c Config) Callback() string {
|
||||
p := strings.TrimSpace(c.CallbackPath)
|
||||
if p == "" {
|
||||
if u, err := url.Parse(c.RedirectURI); err == nil && u.Path != "" {
|
||||
ru := strings.TrimSpace(c.RedirectURI)
|
||||
if c.IsPathRedirect() {
|
||||
if !strings.HasPrefix(ru, "/") {
|
||||
ru = "/" + ru
|
||||
}
|
||||
return ru
|
||||
}
|
||||
if u, err := url.Parse(ru); err == nil && u.Path != "" {
|
||||
return u.Path
|
||||
}
|
||||
return "/oidc/callback"
|
||||
@@ -51,6 +78,91 @@ func (c Config) Callback() string {
|
||||
return p
|
||||
}
|
||||
|
||||
// PublicOrigin derives scheme://host from a login/callback request.
|
||||
// Prefers X-Forwarded-Proto + X-Forwarded-Host (first value), else Host + TLS.
|
||||
func PublicOrigin(r *http.Request) (string, error) {
|
||||
if r == nil {
|
||||
return "", fmt.Errorf("oidc: nil request")
|
||||
}
|
||||
scheme := strings.TrimSpace(r.Header.Get("X-Forwarded-Proto"))
|
||||
if i := strings.IndexByte(scheme, ','); i >= 0 {
|
||||
scheme = strings.TrimSpace(scheme[:i])
|
||||
}
|
||||
if scheme == "" {
|
||||
if r.TLS != nil {
|
||||
scheme = "https"
|
||||
} else {
|
||||
scheme = "http"
|
||||
}
|
||||
}
|
||||
host := strings.TrimSpace(r.Header.Get("X-Forwarded-Host"))
|
||||
if i := strings.IndexByte(host, ','); i >= 0 {
|
||||
host = strings.TrimSpace(host[:i])
|
||||
}
|
||||
if host == "" {
|
||||
host = strings.TrimSpace(r.Host)
|
||||
}
|
||||
if host == "" {
|
||||
return "", fmt.Errorf("oidc: empty Host")
|
||||
}
|
||||
return scheme + "://" + host, nil
|
||||
}
|
||||
|
||||
// ResolveRedirectURI returns the absolute redirect_uri for this request.
|
||||
// Absolute RedirectURI is returned unchanged; path RedirectURI is joined to the request origin.
|
||||
func (c Config) ResolveRedirectURI(r *http.Request) (string, error) {
|
||||
ru := strings.TrimSpace(c.RedirectURI)
|
||||
if ru == "" {
|
||||
return "", fmt.Errorf("oidc: empty redirect_uri")
|
||||
}
|
||||
if !c.IsPathRedirect() {
|
||||
return ru, nil
|
||||
}
|
||||
origin, err := PublicOrigin(r)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
path := ru
|
||||
if !strings.HasPrefix(path, "/") {
|
||||
path = "/" + path
|
||||
}
|
||||
abs := origin + path
|
||||
if err := c.checkOriginAllowlist(origin); err != nil {
|
||||
return "", err
|
||||
}
|
||||
return abs, nil
|
||||
}
|
||||
|
||||
// AllowedOrigins returns trimmed non-empty origins from RedirectOrigins.
|
||||
func (c Config) AllowedOrigins() []string {
|
||||
raw := strings.TrimSpace(c.RedirectOrigins)
|
||||
if raw == "" {
|
||||
return nil
|
||||
}
|
||||
var out []string
|
||||
for _, p := range strings.Split(raw, ",") {
|
||||
p = strings.TrimRight(strings.TrimSpace(p), "/")
|
||||
if p != "" {
|
||||
out = append(out, p)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func (c Config) checkOriginAllowlist(origin string) error {
|
||||
allowed := c.AllowedOrigins()
|
||||
if len(allowed) == 0 {
|
||||
return nil
|
||||
}
|
||||
origin = strings.TrimRight(strings.TrimSpace(origin), "/")
|
||||
for _, a := range allowed {
|
||||
if strings.EqualFold(a, origin) {
|
||||
return nil
|
||||
}
|
||||
}
|
||||
return fmt.Errorf("oidc: origin %q not in redirect_origins", origin)
|
||||
}
|
||||
|
||||
type discoveryDoc struct {
|
||||
AuthorizationEndpoint string `json:"authorization_endpoint"`
|
||||
TokenEndpoint string `json:"token_endpoint"`
|
||||
@@ -126,14 +238,19 @@ func PKCEChallengeS256(verifier string) string {
|
||||
}
|
||||
|
||||
// AuthorizeRedirect builds the browser redirect to the IdP authorize endpoint.
|
||||
func (c Config) AuthorizeRedirect(state, codeChallenge string) (string, error) {
|
||||
// redirectURI must be the absolute URI used for this login (same value later for token exchange).
|
||||
func (c Config) AuthorizeRedirect(state, codeChallenge, redirectURI string) (string, error) {
|
||||
if c.AuthorizeURL == "" {
|
||||
return "", fmt.Errorf("oidc: authorize URL not resolved")
|
||||
}
|
||||
redirectURI = strings.TrimSpace(redirectURI)
|
||||
if redirectURI == "" {
|
||||
return "", fmt.Errorf("oidc: empty redirect_uri")
|
||||
}
|
||||
q := url.Values{}
|
||||
q.Set("response_type", "code")
|
||||
q.Set("client_id", c.ClientID)
|
||||
q.Set("redirect_uri", c.RedirectURI)
|
||||
q.Set("redirect_uri", redirectURI)
|
||||
q.Set("scope", c.ScopesCSV())
|
||||
q.Set("state", state)
|
||||
if codeChallenge != "" {
|
||||
@@ -160,17 +277,22 @@ type TokenResponse struct {
|
||||
}
|
||||
|
||||
// ExchangeCode swaps authorization code for tokens (client_secret_post).
|
||||
func (c Config) ExchangeCode(client *http.Client, code, codeVerifier string) (*TokenResponse, error) {
|
||||
// redirectURI must match the absolute URI sent in AuthorizeRedirect.
|
||||
func (c Config) ExchangeCode(client *http.Client, code, codeVerifier, redirectURI string) (*TokenResponse, error) {
|
||||
if c.TokenURL == "" {
|
||||
return nil, fmt.Errorf("oidc: token URL not resolved")
|
||||
}
|
||||
redirectURI = strings.TrimSpace(redirectURI)
|
||||
if redirectURI == "" {
|
||||
return nil, fmt.Errorf("oidc: empty redirect_uri")
|
||||
}
|
||||
if client == nil {
|
||||
client = &http.Client{Timeout: 15 * time.Second}
|
||||
}
|
||||
form := url.Values{}
|
||||
form.Set("grant_type", "authorization_code")
|
||||
form.Set("code", code)
|
||||
form.Set("redirect_uri", c.RedirectURI)
|
||||
form.Set("redirect_uri", redirectURI)
|
||||
form.Set("client_id", c.ClientID)
|
||||
form.Set("client_secret", c.ClientSecret)
|
||||
if codeVerifier != "" {
|
||||
@@ -313,15 +435,16 @@ func ParseConfig(m map[string]any) Config {
|
||||
m = nested
|
||||
}
|
||||
c := Config{
|
||||
Issuer: firstStr(m, "issuer", "发行方", "issuer_url"),
|
||||
ClientID: firstStr(m, "client_id", "客户端编号", "客户端id", "clientId"),
|
||||
ClientSecret: firstStr(m, "client_secret", "客户端密钥", "clientSecret"),
|
||||
RedirectURI: firstStr(m, "redirect_uri", "回调", "回调地址", "redirect"),
|
||||
Scopes: firstStr(m, "scopes", "范围", "scope"),
|
||||
CallbackPath: firstStr(m, "callback_path", "回调路径"),
|
||||
AuthorizeURL: firstStr(m, "authorize_url", "授权地址"),
|
||||
TokenURL: firstStr(m, "token_url", "令牌地址"),
|
||||
UserInfoURL: firstStr(m, "userinfo_url", "用户信息地址"),
|
||||
Issuer: firstStr(m, "issuer", "发行方", "issuer_url"),
|
||||
ClientID: firstStr(m, "client_id", "客户端编号", "客户端id", "clientId"),
|
||||
ClientSecret: firstStr(m, "client_secret", "客户端密钥", "clientSecret"),
|
||||
RedirectURI: firstStr(m, "redirect_uri", "回调", "回调地址", "redirect"),
|
||||
RedirectOrigins: firstStr(m, "redirect_origins", "回调来源", "redirect_origin"),
|
||||
Scopes: firstStr(m, "scopes", "范围", "scope"),
|
||||
CallbackPath: firstStr(m, "callback_path", "回调路径"),
|
||||
AuthorizeURL: firstStr(m, "authorize_url", "授权地址"),
|
||||
TokenURL: firstStr(m, "token_url", "令牌地址"),
|
||||
UserInfoURL: firstStr(m, "userinfo_url", "用户信息地址"),
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
package oidc_test
|
||||
|
||||
import (
|
||||
"crypto/tls"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/oidc"
|
||||
@@ -46,4 +50,138 @@ func TestPKCEAndParse(t *testing.T) {
|
||||
if c.Callback() != "/oidc/callback" {
|
||||
t.Fatalf("callback=%s", c.Callback())
|
||||
}
|
||||
if c.IsPathRedirect() {
|
||||
t.Fatal("absolute redirect should not be path mode")
|
||||
}
|
||||
}
|
||||
|
||||
func TestPathRedirectParseAndCallback(t *testing.T) {
|
||||
c := oidc.ParseConfig(map[string]any{
|
||||
"issuer": "https://id.example.com",
|
||||
"client_id": "app_x",
|
||||
"client_secret": "secret",
|
||||
"redirect_uri": "/oidc/callback",
|
||||
"redirect_origins": "https://qdqc.com,https://www.qdqc.com",
|
||||
})
|
||||
if !c.Enabled() {
|
||||
t.Fatal("expected enabled")
|
||||
}
|
||||
if !c.IsPathRedirect() {
|
||||
t.Fatal("expected path mode")
|
||||
}
|
||||
if c.Callback() != "/oidc/callback" {
|
||||
t.Fatalf("callback=%s", c.Callback())
|
||||
}
|
||||
origins := c.AllowedOrigins()
|
||||
if len(origins) != 2 || origins[0] != "https://qdqc.com" {
|
||||
t.Fatalf("origins=%v", origins)
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolveRedirectURIAbsolute(t *testing.T) {
|
||||
c := oidc.Config{RedirectURI: "https://qdqc.com/oidc/callback"}
|
||||
r, _ := http.NewRequest(http.MethodGet, "http://www.qdqc.com/oidc/login", nil)
|
||||
r.Host = "www.qdqc.com"
|
||||
got, err := c.ResolveRedirectURI(r)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got != "https://qdqc.com/oidc/callback" {
|
||||
t.Fatalf("got=%s", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolveRedirectURIPathFromHost(t *testing.T) {
|
||||
c := oidc.Config{RedirectURI: "/oidc/callback"}
|
||||
r, _ := http.NewRequest(http.MethodGet, "http://qdqc.com/oidc/login", nil)
|
||||
r.Host = "qdqc.com"
|
||||
got, err := c.ResolveRedirectURI(r)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got != "http://qdqc.com/oidc/callback" {
|
||||
t.Fatalf("got=%s", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolveRedirectURIPathTLS(t *testing.T) {
|
||||
c := oidc.Config{RedirectURI: "/oidc/callback"}
|
||||
r, _ := http.NewRequest(http.MethodGet, "https://qdqc.com/oidc/login", nil)
|
||||
r.Host = "qdqc.com"
|
||||
r.TLS = &tls.ConnectionState{}
|
||||
got, err := c.ResolveRedirectURI(r)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got != "https://qdqc.com/oidc/callback" {
|
||||
t.Fatalf("got=%s", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolveRedirectURIXForwarded(t *testing.T) {
|
||||
c := oidc.Config{RedirectURI: "/oidc/callback"}
|
||||
r, _ := http.NewRequest(http.MethodGet, "http://127.0.0.1:18085/oidc/login", nil)
|
||||
r.Host = "127.0.0.1:18085"
|
||||
r.Header.Set("X-Forwarded-Proto", "https")
|
||||
r.Header.Set("X-Forwarded-Host", "www.qdqc.com, other.example")
|
||||
got, err := c.ResolveRedirectURI(r)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got != "https://www.qdqc.com/oidc/callback" {
|
||||
t.Fatalf("got=%s", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolveRedirectURIAllowlistReject(t *testing.T) {
|
||||
c := oidc.Config{
|
||||
RedirectURI: "/oidc/callback",
|
||||
RedirectOrigins: "https://qdqc.com,https://www.qdqc.com",
|
||||
}
|
||||
r, _ := http.NewRequest(http.MethodGet, "https://evil.example/oidc/login", nil)
|
||||
r.Host = "evil.example"
|
||||
r.Header.Set("X-Forwarded-Proto", "https")
|
||||
_, err := c.ResolveRedirectURI(r)
|
||||
if err == nil || !strings.Contains(err.Error(), "redirect_origins") {
|
||||
t.Fatalf("expected allowlist error, got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolveRedirectURIAllowlistOK(t *testing.T) {
|
||||
c := oidc.Config{
|
||||
RedirectURI: "/oidc/callback",
|
||||
RedirectOrigins: "https://qdqc.com,https://www.qdqc.com",
|
||||
}
|
||||
r, _ := http.NewRequest(http.MethodGet, "https://www.qdqc.com/oidc/login", nil)
|
||||
r.Host = "www.qdqc.com"
|
||||
r.Header.Set("X-Forwarded-Proto", "https")
|
||||
got, err := c.ResolveRedirectURI(r)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got != "https://www.qdqc.com/oidc/callback" {
|
||||
t.Fatalf("got=%s", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAuthorizeRedirectUsesExplicitURI(t *testing.T) {
|
||||
c := oidc.Config{
|
||||
ClientID: "app_x",
|
||||
AuthorizeURL: "https://id.example.com/oauth2/authorize",
|
||||
RedirectURI: "/oidc/callback",
|
||||
}
|
||||
loc, err := c.AuthorizeRedirect("st", "ch", "https://www.qdqc.com/oidc/callback")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
u, err := url.Parse(loc)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got := u.Query().Get("redirect_uri"); got != "https://www.qdqc.com/oidc/callback" {
|
||||
t.Fatalf("redirect_uri=%s", got)
|
||||
}
|
||||
if u.Query().Get("state") != "st" {
|
||||
t.Fatal("state")
|
||||
}
|
||||
}
|
||||
@@ -219,7 +219,7 @@ static int register_core(void) {
|
||||
if (host_register((char *)"web_auth_logout", (char *)"session_id", web_auth_logout) != 0) return 1;
|
||||
if (host_register((char *)"web_auth_new", (char *)"users,session_ttl", web_auth_new) != 0) return 1;
|
||||
if (host_register((char *)"web_app_auth", (char *)"app,users,session_ttl,admin_prefix,login_redirect,logout_redirect,login_path,register,register_path,default_role,session_url", web_app_auth) != 0) return 1;
|
||||
if (host_register((char *)"web_app_oidc", (char *)"app,issuer,client_id,client_secret,redirect_uri,scopes,callback_path,authorize_url,token_url,userinfo_url", web_app_oidc) != 0) return 1;
|
||||
if (host_register((char *)"web_app_oidc", (char *)"app,issuer,client_id,client_secret,redirect_uri,redirect_origins,scopes,callback_path,authorize_url,token_url,userinfo_url", web_app_oidc) != 0) return 1;
|
||||
if (host_register((char *)"web_app_gate", (char *)"app,path,roles,permissions,match,on_deny,exclude", web_app_gate) != 0) return 1;
|
||||
if (host_register((char *)"web_app_rbac", (char *)"app,catalog,desk", web_app_rbac) != 0) return 1;
|
||||
if (host_register((char *)"web_app_tenant", (char *)"app,mode,param,column,default_scope", web_app_tenant) != 0) return 1;
|
||||
|
||||
+41
-52
@@ -1,29 +1,59 @@
|
||||
---
|
||||
title: Welcome to Marqdo
|
||||
description: User docs home — code is documentation (English)
|
||||
description: User-docs home — code as documentation (English)
|
||||
import math:lib/math.mq.md
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Hi — thanks for reading this far. I am Marqdo’s developer. Marqdo is a language where *code is documentation, and documentation is code*: Markdown markers are the program structure, so what you read is what runs.
|
||||
Hello — and welcome. I built Marqdo so that code is documentation and documentation is code: Markdown markers are the program structure, so what you read is what runs.
|
||||
|
||||
AI already prefers Markdown-shaped output. The idea was: why keep docs and code as two separate worlds? So Marqdo was born as a “docs are code” language. To keep every source renderable as Markdown, files use the `.mq.md` suffix. From early on we aimed for richer tooling — auto-generated YAML for OKF-style knowledge bases, even auto-generated slides — those are later goals. Happily, it already works well as a blogging tool: yes, this site is generated by Marqdo. And when AI writes Marqdo, you tend to burn fewer tokens — wallets everywhere thank you.
|
||||
AI systems already favor Markdown-shaped output. That raised a simple question: why keep docs and programs as two separate artifacts? Marqdo is the answer. The `.mq.md` suffix exists so a file stays renderable as Markdown while remaining executable. Richer OKF-style YAML catalogs and even slide decks are on the roadmap; for now this site itself is generated by Marqdo — and that often saves tokens when an AI is writing with you.
|
||||
|
||||
The language is still young: structure markers, bilingual core names (`print` / `打印`, …), importable stdlibs (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
|
||||
The language is still early: structural markers, English/Chinese builtin aliases (`print` / `打印` …), an importable standard library (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Join in at [GitHub](https://github.com/cflmy/marqdo).
|
||||
|
||||
## Install
|
||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
||||
|
||||
Pick one way to get the CLI:
|
||||
Want a quick hello? Calls only run when they sit in the entry `# main` — `##` children are methods until something calls them. Try **greet who="marqdo"**. Names can include spaces: **greet who="marqdo user"**.
|
||||
|
||||
| Method | Notes |
|
||||
|--------|-------|
|
||||
Beyond the basics, Marqdo ships table, time, text, files, system, math, foreign, and more. Math and foreign deserve a special mention.
|
||||
|
||||
Write a math block and bind it with a TeX comment:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
Then plot it: **_svg = math.plot formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
Foreign lets you embed another language. Bind `hi` to a small Python block:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
Under Markdown this stays easy to read — which is the point: code as documentation, documentation as code.
|
||||
|
||||
Welcome again — enjoy exploring Marqdo.
|
||||
|
||||
## greet
|
||||
|
||||
When we meet a visitor `who`, we **print text="Welcome, `who`!"** and close with*None*.
|
||||
|
||||
## install
|
||||
|
||||
Install the interpreter (CLI) in any of these ways:
|
||||
|
||||
| Way | Notes |
|
||||
|------|------|
|
||||
| Ubuntu PPA | `sudo add-apt-repository ppa:cflmy/marqdo` then `sudo apt install marqdo` |
|
||||
| GitHub Releases | Prebuilt Windows / Linux zips at [releases](https://github.com/cflmy/marqdo/releases) |
|
||||
| From source | `cargo build --release` (needs Rust) |
|
||||
| GitHub Releases | Prebuilt Windows / Linux packages from [releases](https://github.com/cflmy/marqdo/releases) |
|
||||
| From source | `cargo build --release` (needs a local Rust toolchain) |
|
||||
|
||||
Official extensions version independently of the CLI:
|
||||
Official extensions update independently of the CLI:
|
||||
|
||||
```text
|
||||
marqdo ext add web
|
||||
@@ -31,44 +61,3 @@ marqdo ext add quantum
|
||||
```
|
||||
|
||||
`ext add` tries CDN https://ext.marqdo.com first, then GitHub, then the proxy mirror. See [`features/05-extensions.mq.md`](features/05-extensions.mq.md).
|
||||
|
||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
||||
|
||||
A small function to say hello:
|
||||
|
||||
> greet who=marqdo
|
||||
|
||||
Named args can include spaces:
|
||||
|
||||
> greet who=marqdo user
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Welcome, `who`!
|
||||
|
||||
*None*
|
||||
|
||||
Beyond the basics above, Marqdo also ships standard libraries: table, time, text, files, system, math, foreign, and more.
|
||||
|
||||
Math and foreign deserve a special mention. With the math library you can bind a formula like this:
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
Then plot it:
|
||||
|
||||
**`_svg` = > math.plot formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
The foreign library lets you call external code, for example:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
Under Markdown this stays easy to read — which is the point: Marqdo’s design is code as documentation, documentation as code.
|
||||
|
||||
Welcome again — enjoy exploring Marqdo.
|
||||
+32
-44
@@ -7,12 +7,42 @@ description: 用户文档首页 — 代码即文档(中文版)
|
||||
|
||||
# main
|
||||
|
||||
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门*代码即文档,文档即代码*的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
|
||||
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门「代码即文档,文档即代码」的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
|
||||
|
||||
AI 偏爱 Markdown结构的输出。作者的念头是:何必再把文档和代码拆成两套?我们来实现一个文档即代码的语言,所以marqdo应运而生,为了确保代码一定可以被渲染,marqdo的文件后缀定义为了`.mq.md`。在开发之处我们就尝试希望更丰富的支持,自动生成一个yaml文件使得 OKF 式知识库便捷的自动配置,乃至自动生成ppt,自然这都是以后的目标了。不过相当不错的是,至少这会成为一个不错的博客工具——对,这个站点就是 Marqdo 生成的,而且AI输出的时候会节约不少token,你知道的,token烧的太多,钱包会可怜的饿瘦的。
|
||||
AI 偏爱 Markdown 结构的输出。我当时的念头很简单——何必再把文档和代码拆成两套?于是有了 marqdo。为了让文件既能当文档渲染又能执行,后缀定为 `.mq.md`。更远的目标还有 OKF 式知识库的 YAML、甚至自动生成 PPT;眼下它至少已经是个不错的博客工具——对,这个站点就是 Marqdo 生成的。AI 写 `.mq.md` 时往往更省 token,钱包也会轻松一点。
|
||||
|
||||
语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
|
||||
|
||||
English docs: [`00-welcome.mq.md`](00-welcome.mq.md)(English prose and English builtins).
|
||||
|
||||
想先打个招呼?调用写在入口 `# main` 里才会真的跑——子标题里的方法要等你叫到它。比如:**问候 谁="marqdo"**。名字里可以带空格:**问候 谁="marqdo user"**。
|
||||
|
||||
除了这些基本面,标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。
|
||||
|
||||
比方说,直接写一块公式,并用 TeX 注释标上变量名:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
接着画出来:**_svg = 数学.绘图 formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
外联则允许嵌一段别的语言。把`hi`绑成下面这样即可:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的:代码即文档,文档即代码。
|
||||
|
||||
最后,再次欢迎你,尽情体验 marqdo 吧!
|
||||
|
||||
## 问候
|
||||
|
||||
见到访客`谁`时,我们 **打印 内容="欢迎,`谁`!"**,然后收束为*None*。
|
||||
|
||||
## 安装
|
||||
|
||||
解释器(CLI)任选其一:
|
||||
@@ -31,45 +61,3 @@ marqdo ext add quantum
|
||||
```
|
||||
|
||||
`ext add` 下载顺序:CDN https://ext.marqdo.com → GitHub → proxy 镜像。详见本站 [`features/05-扩展.mq.md`](features/05-扩展.mq.md)。
|
||||
|
||||
English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English builtins).
|
||||
|
||||
用一个小函数打个招呼:
|
||||
|
||||
> 问候 谁=marqdo
|
||||
|
||||
具名实参可以带空格:
|
||||
|
||||
> 问候 谁=marqdo user
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> 打印 内容=欢迎,`谁`!
|
||||
|
||||
*None*
|
||||
|
||||
除了上面的一些基本内容之外,我还开发了这个语言的一些标准库,包括表、时间、文本、文件、系统、数学和外联等标准库。
|
||||
|
||||
其中数学库和外联库是我要着重提到的,例如数学库,你可以通过下面的方式调用:
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
之后让我们画个图像吧!
|
||||
|
||||
**`_svg` = > 数学.绘图 formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
外联库则允许你调用外部代码,例如:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
这些代码在markdown下面都非常的易读,就像我说的,marqdo的设计思想就是代码即文档,
|
||||
文档即代码。
|
||||
|
||||
最后,再次欢迎你,尽情体验marqdo吧!
|
||||
@@ -5,12 +5,14 @@ description: Local browse and static export from the interpreter
|
||||
|
||||
# main
|
||||
|
||||
Milestone: `marqdo view` and `view output`.
|
||||
Milestone: `marqdo view` and `view output` (v1.4.1 mid→mid annot leaders + document surface).
|
||||
|
||||
Local: `marqdo view public`
|
||||
|
||||
Static export: `marqdo view output public -o public`
|
||||
|
||||
Executable user docs live under `public/`. Generated HTML (`index.html` / `pages/`) is for hosting; CI publishes to `gh-pages`.
|
||||
Browse Structure keeps narration, highlights executable markers, and attaches
|
||||
run results (values, taken branch arms, call/loop frames). The same render path
|
||||
builds this user docs site; CI publishes to `gh-pages`.
|
||||
|
||||
> print text=Docs site: generated by the Marqdo interpreter, not hand-written HTML.
|
||||
@@ -5,12 +5,13 @@ description: 本地浏览与静态导出由解释器生成
|
||||
|
||||
# main
|
||||
|
||||
里程碑:`marqdo view` 与 `view output`。
|
||||
里程碑:`marqdo view` 与 `view output`(v1.4.1 mid→mid 标注连线 + 文档面)。
|
||||
|
||||
本地浏览:`marqdo view public`
|
||||
|
||||
静态导出:`marqdo view output public -o public`
|
||||
|
||||
用户可执行文档在 `public/`;生成的 HTML(`index.html` / `pages/`)供静态托管,CI 发布到 `gh-pages`。
|
||||
Browse Structure 保真叙述、高亮可执行标记,并挂载运行结果(变量值、分支命中臂、调用/循环帧)。
|
||||
用户站与 live view 同源渲染;CI 发布到 `gh-pages`。
|
||||
|
||||
> 打印 内容=文档站:由 Marqdo 解释器生成,不是手写 HTML。
|
||||
@@ -124,7 +124,10 @@ if [ "$REUSE_ORIG" -eq 1 ]; then
|
||||
echo "==> reusing published ${ORIG_NAME} (debian-only bump; do not rewrite orig)"
|
||||
echo " source: ${ORIG_SRC}"
|
||||
sha256sum "$ORIG_SRC"
|
||||
cp -f "$ORIG_SRC" "$BUILD_AREA/$ORIG_NAME"
|
||||
# Local fallback may already be build-area/ORIG_NAME — do not cp onto itself.
|
||||
if [ "$(realpath "$ORIG_SRC")" != "$(realpath "$BUILD_AREA/$ORIG_NAME" 2>/dev/null || echo "")" ]; then
|
||||
cp -f "$ORIG_SRC" "$BUILD_AREA/$ORIG_NAME"
|
||||
fi
|
||||
# Unpack orig (top dir is usually ${VER} or marqdo-${VER})
|
||||
tar -xJf "$BUILD_AREA/$ORIG_NAME" -C "$(dirname "$PKG_ROOT")"
|
||||
if [ ! -d "$PKG_ROOT" ]; then
|
||||
|
||||
+94
-1
@@ -1,7 +1,98 @@
|
||||
//! Captured program run (for tests and `view`).
|
||||
|
||||
use crate::value::Value;
|
||||
use crate::host::PlotArtifact;
|
||||
use crate::value::Value;
|
||||
|
||||
/// Silent execution trace for view annotations (not stderr `trace_eval`).
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct ViewTrace {
|
||||
pub branches: Vec<BranchHit>,
|
||||
pub loops: Vec<LoopHit>,
|
||||
/// Per-statement post-state / control events (tree capture).
|
||||
pub events: Vec<StmtEvent>,
|
||||
/// User-function invocations (tree capture).
|
||||
pub calls: Vec<CallFrame>,
|
||||
/// Foreach / while loop frames with per-iteration item values.
|
||||
pub loop_frames: Vec<LoopFrame>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct BranchHit {
|
||||
pub line: u32,
|
||||
pub arm_index: usize,
|
||||
pub count: u32,
|
||||
/// Call frame that took this arm (`0` = entry / `# main`).
|
||||
pub call_id: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct LoopHit {
|
||||
pub line: u32,
|
||||
pub iterations: u32,
|
||||
pub last_item: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct LoopFrame {
|
||||
pub loop_id: u32,
|
||||
pub line: u32,
|
||||
pub item_name: Option<String>,
|
||||
pub collection: Option<String>,
|
||||
pub iterations: Vec<LoopIter>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct LoopIter {
|
||||
/// 0-based iteration index.
|
||||
pub index: u32,
|
||||
pub item_value: String,
|
||||
pub call_id: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct StmtEvent {
|
||||
pub line: u32,
|
||||
pub kind: StmtEventKind,
|
||||
pub name: Option<String>,
|
||||
pub value_after: Option<String>,
|
||||
pub arm_index: Option<usize>,
|
||||
/// 0-based iteration index when inside a loop.
|
||||
pub iter: Option<u32>,
|
||||
pub call_id: u32,
|
||||
pub loop_id: Option<u32>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum StmtEventKind {
|
||||
Assign,
|
||||
Return,
|
||||
Call,
|
||||
Branch,
|
||||
Loop,
|
||||
BindRef,
|
||||
}
|
||||
|
||||
impl StmtEventKind {
|
||||
pub fn as_str(self) -> &'static str {
|
||||
match self {
|
||||
StmtEventKind::Assign => "assign",
|
||||
StmtEventKind::Return => "return",
|
||||
StmtEventKind::Call => "call",
|
||||
StmtEventKind::Branch => "branch",
|
||||
StmtEventKind::Loop => "loop",
|
||||
StmtEventKind::BindRef => "bind_ref",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CallFrame {
|
||||
pub call_id: u32,
|
||||
pub fn_name: String,
|
||||
pub fn_line: u32,
|
||||
pub ordinal: u32,
|
||||
pub args_brief: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct RunCapture {
|
||||
@@ -10,4 +101,6 @@ pub struct RunCapture {
|
||||
pub plots: Vec<PlotArtifact>,
|
||||
/// Entry-function bindings after a successful tree-backend run (empty for bytecode).
|
||||
pub bindings: std::collections::HashMap<String, Value>,
|
||||
/// Branch/loop/stmt hits collected during tree capture (empty for bytecode).
|
||||
pub view_trace: ViewTrace,
|
||||
}
|
||||
+244
-26
@@ -1,7 +1,11 @@
|
||||
//! Jupyter-style output persistence in `.mq.md` (`<!-- marqdo-out … -->`).
|
||||
//! Jupyter-style output persistence in `.mq.md`.
|
||||
//!
|
||||
//! Optional **named slots**: `<!-- marqdo-out ok -->` / `<!-- marqdo-out error -->`
|
||||
//! so success and failure results do not overwrite each other.
|
||||
//! Two surface forms (both scanned / replaced):
|
||||
//! - HTML comment: `<!-- marqdo-out … -->` (text / structured output)
|
||||
//! - Markdown image: `` (image refs; validated)
|
||||
//!
|
||||
//! Optional **named slots**: `marqdo-out ok` / `marqdo-out error` so success and
|
||||
//! failure results do not overwrite each other.
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::sync::Mutex;
|
||||
@@ -14,14 +18,30 @@ const MAGIC: &str = "marqdo-out";
|
||||
/// Serialize all writeback file mutations (sync + subtask writers).
|
||||
static WRITEBACK_LOCK: Mutex<()> = Mutex::new(());
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
enum BlockKind {
|
||||
Comment,
|
||||
Image,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
struct BlockSpan {
|
||||
start: usize,
|
||||
end: usize,
|
||||
/// Comment body text, or image URL/path for [`BlockKind::Image`].
|
||||
body: String,
|
||||
start_line: u32,
|
||||
/// Named slot from header (`marqdo-out ok` → `ok`); `None` = legacy unkeyed.
|
||||
key: Option<String>,
|
||||
kind: BlockKind,
|
||||
}
|
||||
|
||||
/// View-facing writeback piece under a statement line.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct WritebackEntry {
|
||||
pub key: Option<String>,
|
||||
pub body: String,
|
||||
pub is_image: bool,
|
||||
}
|
||||
|
||||
fn display_value(v: &Value) -> String {
|
||||
@@ -119,13 +139,71 @@ fn line_number_at(source: &str, byte: usize) -> u32 {
|
||||
+ 1
|
||||
}
|
||||
|
||||
fn format_block(body: &str, key: Option<&str>) -> String {
|
||||
fn format_comment_block(body: &str, key: Option<&str>) -> String {
|
||||
match key {
|
||||
Some(k) => format!("<!-- {MAGIC} {k}\n{body}\n-->"),
|
||||
None => format!("<!-- {MAGIC}\n{body}\n-->"),
|
||||
}
|
||||
}
|
||||
|
||||
fn format_image_block(url: &str, key: Option<&str>) -> String {
|
||||
match key {
|
||||
Some(k) => format!(""),
|
||||
None => format!(""),
|
||||
}
|
||||
}
|
||||
|
||||
fn format_block_for_value(body: &str, key: Option<&str>) -> Result<String, String> {
|
||||
if looks_like_image_ref(body) {
|
||||
validate_image_ref(body)?;
|
||||
Ok(format_image_block(body.trim(), key))
|
||||
} else {
|
||||
Ok(format_comment_block(body, key))
|
||||
}
|
||||
}
|
||||
|
||||
/// True when `s` looks like a path/URL that should persist as ``.
|
||||
pub fn looks_like_image_ref(s: &str) -> bool {
|
||||
validate_image_ref(s).is_ok()
|
||||
}
|
||||
|
||||
/// Accept local/relative paths and http(s) URLs with a known image extension,
|
||||
/// or `data:image/…` URIs.
|
||||
pub fn validate_image_ref(s: &str) -> Result<(), String> {
|
||||
let t = s.trim().trim_matches('"').trim_matches('\'');
|
||||
if t.is_empty() {
|
||||
return Err("writeback image: empty path".into());
|
||||
}
|
||||
if t.starts_with("data:image/") {
|
||||
return Ok(());
|
||||
}
|
||||
// Strip query/fragment for extension check.
|
||||
let no_query = t.split_once('?').map(|(p, _)| p).unwrap_or(t);
|
||||
let path_part = no_query.split_once('#').map(|(p, _)| p).unwrap_or(no_query);
|
||||
let file = path_part.rsplit('/').next().unwrap_or(path_part);
|
||||
// Require a real extension (reject bare names like `svg` / `png`).
|
||||
let Some((stem, ext)) = file.rsplit_once('.') else {
|
||||
return Err(format!(
|
||||
"writeback image: path needs an image extension (got `{t}`)"
|
||||
));
|
||||
};
|
||||
if stem.is_empty() {
|
||||
return Err(format!("writeback image: invalid file name `{t}`"));
|
||||
}
|
||||
let ext = ext.to_ascii_lowercase();
|
||||
const OK: &[&str] = &[
|
||||
"png", "jpg", "jpeg", "gif", "webp", "svg", "bmp", "ico", "avif", "tif", "tiff",
|
||||
];
|
||||
if OK.contains(&ext.as_str()) {
|
||||
Ok(())
|
||||
} else {
|
||||
Err(format!(
|
||||
"writeback image: not an image path/URL (got `{t}`; need .{})",
|
||||
OK.join("/.")
|
||||
))
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_header_key(header: &str) -> Option<String> {
|
||||
let mut parts = header.split_whitespace();
|
||||
let first = parts.next()?;
|
||||
@@ -160,11 +238,43 @@ fn parse_one_block(block: &str, start_byte: usize, source: &str) -> Option<Block
|
||||
body,
|
||||
start_line: line_number_at(source, start_byte),
|
||||
key,
|
||||
kind: BlockKind::Comment,
|
||||
})
|
||||
}
|
||||
|
||||
/// `` on a single source line.
|
||||
fn parse_image_line(line: &str, line_start: usize, source: &str) -> Option<BlockSpan> {
|
||||
let trimmed = line.trim();
|
||||
let rest = trimmed.strip_prefix("?;
|
||||
let alt = rest[..alt_end].trim();
|
||||
if !alt.split_whitespace().any(|t| t == MAGIC) {
|
||||
return None;
|
||||
}
|
||||
let key = parse_header_key(alt);
|
||||
let after_alt = &rest[alt_end + 2..];
|
||||
let url_end = after_alt.rfind(')')?;
|
||||
let url = after_alt[..url_end].trim();
|
||||
if url.is_empty() || validate_image_ref(url).is_err() {
|
||||
return None;
|
||||
}
|
||||
// Span covers the trimmed image on its line (indent kept outside).
|
||||
let trim_start = line.find(trimmed).unwrap_or(0);
|
||||
let start = line_start + trim_start;
|
||||
let end = start + trimmed.len();
|
||||
Some(BlockSpan {
|
||||
start,
|
||||
end,
|
||||
body: url.to_string(),
|
||||
start_line: line_number_at(source, start),
|
||||
key,
|
||||
kind: BlockKind::Image,
|
||||
})
|
||||
}
|
||||
|
||||
fn scan_blocks(source: &str) -> Vec<BlockSpan> {
|
||||
let mut out = Vec::new();
|
||||
// HTML comment blocks
|
||||
let mut i = 0usize;
|
||||
while i < source.len() {
|
||||
let rest = &source[i..];
|
||||
@@ -186,6 +296,16 @@ fn scan_blocks(source: &str) -> Vec<BlockSpan> {
|
||||
}
|
||||
i = abs + end_rel + 3;
|
||||
}
|
||||
// Image writebacks (line-oriented)
|
||||
let mut line_start = 0usize;
|
||||
for line in source.split_inclusive('\n') {
|
||||
let content = line.trim_end_matches(['\r', '\n']);
|
||||
if let Some(b) = parse_image_line(content, line_start, source) {
|
||||
out.push(b);
|
||||
}
|
||||
line_start += line.len();
|
||||
}
|
||||
out.sort_by_key(|b| b.start);
|
||||
out
|
||||
}
|
||||
|
||||
@@ -323,7 +443,7 @@ fn find_keyed_in_cluster(source: &str, after_line: u32, key: &str) -> Option<Blo
|
||||
/// Replace keyed block under `anchor` line, or insert into that cluster (not EOF).
|
||||
fn replace_or_insert_keyed_at(source: &str, anchor: u32, key: &str, body: &str) -> Result<String, String> {
|
||||
let key = normalize_slot_key(key);
|
||||
let block = format_block(body, Some(&key));
|
||||
let block = format_block_for_value(body, Some(&key))?;
|
||||
if let Some(existing) = find_keyed_in_cluster(source, anchor, &key) {
|
||||
return Ok(splice_block(source, existing.start, existing.end, &block));
|
||||
}
|
||||
@@ -438,13 +558,13 @@ pub fn record(
|
||||
let stripped = find_eof_block(&source)
|
||||
.map(|b| strip_span(&source, b.start, span_end_including_nl(&source, b.end)))
|
||||
.unwrap_or_else(|| source.clone());
|
||||
append_eof(&stripped, &format_block(&body, None))
|
||||
append_eof(&stripped, &format_block_for_value(&body, None)?)
|
||||
} else {
|
||||
let line = anchor.ok_or_else(|| "writeback: missing anchor line".to_string())?;
|
||||
let stripped = find_adjacent_block(&source, line)
|
||||
.map(|b| strip_span(&source, b.start, span_end_including_nl(&source, b.end)))
|
||||
.unwrap_or_else(|| source.clone());
|
||||
insert_after_line(&stripped, line, &format_block(&body, None))?
|
||||
insert_after_line(&stripped, line, &format_block_for_value(&body, None)?)?
|
||||
};
|
||||
persist(ctx, &next)?;
|
||||
Ok(Value::Text(body.clone()))
|
||||
@@ -549,10 +669,15 @@ fn slots_from_source(source: &str) -> Value {
|
||||
.map(|b| {
|
||||
let anchor = anchor_line_above(source, b.start_line);
|
||||
let at_eof = b.key.is_none() && is_eof_block(source, &b);
|
||||
let kind = match b.kind {
|
||||
BlockKind::Comment => "comment",
|
||||
BlockKind::Image => "image",
|
||||
};
|
||||
let mut entries = vec![
|
||||
("line".into(), Value::Int(anchor as i64)),
|
||||
("body".into(), Value::Text(b.body)),
|
||||
("at_end".into(), Value::Bool(at_eof)),
|
||||
("kind".into(), Value::Text(kind.into())),
|
||||
];
|
||||
if let Some(k) = b.key {
|
||||
entries.push(("key".into(), Value::Text(k)));
|
||||
@@ -584,29 +709,49 @@ pub fn ensure_slot(
|
||||
})
|
||||
}
|
||||
|
||||
/// Map statement line → body for adjacent blocks (keyed slots included under their anchor).
|
||||
pub fn writeback_map(source: &str) -> HashMap<u32, String> {
|
||||
let mut map = HashMap::new();
|
||||
/// Structured writebacks keyed by the statement line above the block cluster.
|
||||
pub fn writeback_entries(source: &str) -> HashMap<u32, Vec<WritebackEntry>> {
|
||||
let mut map: HashMap<u32, Vec<WritebackEntry>> = HashMap::new();
|
||||
for b in scan_blocks(source) {
|
||||
let anchor = anchor_line_above(source, b.start_line);
|
||||
let piece = match &b.key {
|
||||
Some(k) => format!("[{k}]\n{}", b.body),
|
||||
None => b.body.clone(),
|
||||
};
|
||||
if b.key.is_none() && is_eof_block(source, &b) {
|
||||
map.insert(0, piece);
|
||||
let anchor = if b.key.is_none() && is_eof_block(source, &b) {
|
||||
0
|
||||
} else {
|
||||
map.entry(anchor)
|
||||
.and_modify(|e| {
|
||||
e.push_str("\n\n");
|
||||
e.push_str(&piece);
|
||||
})
|
||||
.or_insert(piece);
|
||||
}
|
||||
anchor_line_above(source, b.start_line)
|
||||
};
|
||||
let entry = WritebackEntry {
|
||||
key: b.key.clone(),
|
||||
body: b.body.clone(),
|
||||
is_image: b.kind == BlockKind::Image,
|
||||
};
|
||||
map.entry(anchor).or_default().push(entry);
|
||||
}
|
||||
map
|
||||
}
|
||||
|
||||
/// Map statement line → combined body for adjacent blocks (keyed slots included).
|
||||
/// Image slots are encoded as a markdown image line so view/static can render `<img>`.
|
||||
pub fn writeback_map(source: &str) -> HashMap<u32, String> {
|
||||
let mut map = HashMap::new();
|
||||
for (anchor, entries) in writeback_entries(source) {
|
||||
let mut pieces = Vec::new();
|
||||
for e in entries {
|
||||
let content = if e.is_image {
|
||||
format!("", e.body)
|
||||
} else {
|
||||
e.body
|
||||
};
|
||||
let piece = match &e.key {
|
||||
Some(k) => format!("[{k}]\n{content}"),
|
||||
None => content,
|
||||
};
|
||||
pieces.push(piece);
|
||||
}
|
||||
map.insert(anchor, pieces.join("\n\n"));
|
||||
}
|
||||
map
|
||||
}
|
||||
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
@@ -614,7 +759,7 @@ mod tests {
|
||||
#[test]
|
||||
fn parse_and_insert_adjacent() {
|
||||
let src = "# main\n\n**x = 1**\n";
|
||||
let block = format_block("1", None);
|
||||
let block = format_comment_block("1", None);
|
||||
let next = insert_after_line(src, 3, &block).unwrap();
|
||||
assert!(next.contains("marqdo-out"));
|
||||
assert!(!next.contains("@line"));
|
||||
@@ -625,6 +770,79 @@ mod tests {
|
||||
assert!(!replaced.contains("marqdo-out"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn image_writeback_scan_and_format() {
|
||||
assert!(looks_like_image_ref("plot.svg"));
|
||||
assert!(looks_like_image_ref("https://ex.com/a.PNG"));
|
||||
assert!(looks_like_image_ref("data:image/png;base64,xx"));
|
||||
assert!(looks_like_image_ref("plots/a.svg?v=1"));
|
||||
assert!(!looks_like_image_ref("readme.txt"));
|
||||
assert!(!looks_like_image_ref("42"));
|
||||
assert!(!looks_like_image_ref("svg")); // bare name, not an extension
|
||||
assert!(!looks_like_image_ref(".svg"));
|
||||
let block = format_image_block("out/plot.svg", Some("ok"));
|
||||
assert_eq!(block, "");
|
||||
let src = "# main\n\n**x = 1**\n\n\n> print text=tail\n";
|
||||
let blocks = scan_blocks(src);
|
||||
assert_eq!(blocks.len(), 1);
|
||||
assert_eq!(blocks[0].kind, BlockKind::Image);
|
||||
assert_eq!(blocks[0].body, "out/plot.svg");
|
||||
assert_eq!(blocks[0].key.as_deref(), Some("ok"));
|
||||
let map = writeback_map(src);
|
||||
assert_eq!(
|
||||
map.get(&3).map(|s| s.as_str()),
|
||||
Some("[ok]\n")
|
||||
);
|
||||
// Invalid image URL in marqdo-out alt → not a writeback slot
|
||||
let bad = "# main\n\n\n";
|
||||
assert!(scan_blocks(bad).is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unkeyed_comment_and_image_replace_each_other() {
|
||||
let src = "# main\n\n**x = 1**\n<!-- marqdo-out\nold\n-->\n\n> print text=tail\n";
|
||||
let line = 3u32;
|
||||
let to_image = {
|
||||
let stripped = find_adjacent_block(src, line)
|
||||
.map(|b| strip_span(src, b.start, span_end_including_nl(src, b.end)))
|
||||
.unwrap_or_else(|| src.to_string());
|
||||
insert_after_line(
|
||||
&stripped,
|
||||
line,
|
||||
&format_block_for_value("fig.svg", None).unwrap(),
|
||||
)
|
||||
.unwrap()
|
||||
};
|
||||
assert!(to_image.contains(""));
|
||||
assert!(!to_image.contains("<!-- marqdo-out"));
|
||||
let blocks = scan_blocks(&to_image);
|
||||
assert_eq!(blocks.len(), 1);
|
||||
assert_eq!(blocks[0].kind, BlockKind::Image);
|
||||
|
||||
let to_text = {
|
||||
let stripped = find_adjacent_block(&to_image, line)
|
||||
.map(|b| strip_span(&to_image, b.start, span_end_including_nl(&to_image, b.end)))
|
||||
.unwrap_or_else(|| to_image.clone());
|
||||
insert_after_line(
|
||||
&stripped,
|
||||
line,
|
||||
&format_block_for_value("hello", None).unwrap(),
|
||||
)
|
||||
.unwrap()
|
||||
};
|
||||
assert!(to_text.contains("<!-- marqdo-out\nhello\n-->"));
|
||||
assert!(!to_text.contains("![marqdo-out]"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn record_format_picks_image_for_svg_path() {
|
||||
let s = format_block_for_value("figs/a.svg", None).unwrap();
|
||||
assert_eq!(s, "");
|
||||
let t = format_block_for_value("hello", None).unwrap();
|
||||
assert!(t.contains("<!-- marqdo-out"));
|
||||
assert!(format_block_for_value("notes.txt", None).unwrap().contains("<!--"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn writeback_map_uses_line_above() {
|
||||
let src = "# main\n\n**x = 1**\n<!-- marqdo-out\n42\n-->\n\n> print text=tail\n";
|
||||
@@ -671,7 +889,7 @@ mod tests {
|
||||
let stripped = find_adjacent_block(s, line)
|
||||
.map(|b| strip_span(s, b.start, span_end_including_nl(s, b.end)))
|
||||
.unwrap_or_else(|| s.to_string());
|
||||
insert_after_line(&stripped, line, &format_block(body, None)).unwrap()
|
||||
insert_after_line(&stripped, line, &format_comment_block(body, None)).unwrap()
|
||||
};
|
||||
let once = strip_insert(src, "a");
|
||||
let twice = strip_insert(&once, "b");
|
||||
|
||||
+357
-3
@@ -17,6 +17,9 @@ use crate::debug::{emit_trace, DebugController};
|
||||
use crate::diagnostics::{bail_at, Span};
|
||||
use crate::host::{call_host, HostContext, HostFn};
|
||||
use crate::input_feed::InputFeed;
|
||||
use crate::capture::{
|
||||
BranchHit, CallFrame, LoopFrame, LoopHit, LoopIter, StmtEvent, StmtEventKind, ViewTrace,
|
||||
};
|
||||
use crate::value::Value;
|
||||
use std::sync::Arc;
|
||||
|
||||
@@ -27,6 +30,14 @@ pub struct Interpreter {
|
||||
pub captured_stdout: String,
|
||||
/// Bindings in the entry (`# main` / sole object) env after it finishes.
|
||||
pub entry_bindings: HashMap<String, Value>,
|
||||
/// Silent branch/loop hits for `marqdo view` annotations.
|
||||
pub view_trace: ViewTrace,
|
||||
next_call_id: u32,
|
||||
call_stack: Vec<u32>,
|
||||
fn_ordinals: HashMap<String, u32>,
|
||||
next_loop_id: u32,
|
||||
/// Active loops: `(loop_id, iter_index_0based)`.
|
||||
loop_stack: Vec<(u32, u32)>,
|
||||
current_span: Span,
|
||||
input: InputFeed,
|
||||
host: HostContext,
|
||||
@@ -82,6 +93,12 @@ impl Interpreter {
|
||||
capture: false,
|
||||
captured_stdout: String::new(),
|
||||
entry_bindings: HashMap::new(),
|
||||
view_trace: ViewTrace::default(),
|
||||
next_call_id: 1,
|
||||
call_stack: Vec::new(),
|
||||
fn_ordinals: HashMap::new(),
|
||||
next_loop_id: 1,
|
||||
loop_stack: Vec::new(),
|
||||
current_span: Span::new(1, 1),
|
||||
input: InputFeed::new(false, Vec::new()),
|
||||
host: HostContext::for_run(path, Default::default(), Vec::new()),
|
||||
@@ -97,6 +114,12 @@ impl Interpreter {
|
||||
capture: true,
|
||||
captured_stdout: String::new(),
|
||||
entry_bindings: HashMap::new(),
|
||||
view_trace: ViewTrace::default(),
|
||||
next_call_id: 1,
|
||||
call_stack: Vec::new(),
|
||||
fn_ordinals: HashMap::new(),
|
||||
next_loop_id: 1,
|
||||
loop_stack: Vec::new(),
|
||||
current_span: Span::new(1, 1),
|
||||
input: InputFeed::new(true, Vec::new()),
|
||||
host: HostContext::for_capture(path, Default::default()),
|
||||
@@ -150,6 +173,172 @@ impl Interpreter {
|
||||
}
|
||||
}
|
||||
|
||||
fn current_call_id(&self) -> u32 {
|
||||
self.call_stack.last().copied().unwrap_or(0)
|
||||
}
|
||||
|
||||
fn loop_ctx(&self) -> (Option<u32>, Option<u32>) {
|
||||
self.loop_stack
|
||||
.last()
|
||||
.map(|(id, iter)| (Some(*id), Some(*iter)))
|
||||
.unwrap_or((None, None))
|
||||
}
|
||||
|
||||
fn push_view_call(&mut self, fun: &Function, env: &Env) {
|
||||
if !self.capture {
|
||||
return;
|
||||
}
|
||||
let call_id = self.next_call_id;
|
||||
self.next_call_id += 1;
|
||||
let ordinal = {
|
||||
let e = self.fn_ordinals.entry(fun.name.clone()).or_insert(0);
|
||||
*e += 1;
|
||||
*e
|
||||
};
|
||||
let args_brief = fun
|
||||
.params
|
||||
.iter()
|
||||
.filter_map(|p| {
|
||||
env.get(&p.name)
|
||||
.map(|v| format!("{}={}", p.name, brief_trace_val(v)))
|
||||
})
|
||||
.collect::<Vec<_>>()
|
||||
.join(", ");
|
||||
self.view_trace.calls.push(CallFrame {
|
||||
call_id,
|
||||
fn_name: fun.name.clone(),
|
||||
fn_line: fun.span.line,
|
||||
ordinal,
|
||||
args_brief,
|
||||
});
|
||||
self.call_stack.push(call_id);
|
||||
}
|
||||
|
||||
fn pop_view_call(&mut self) {
|
||||
if self.capture {
|
||||
self.call_stack.pop();
|
||||
}
|
||||
}
|
||||
|
||||
fn begin_view_loop(
|
||||
&mut self,
|
||||
line: u32,
|
||||
item: Option<&str>,
|
||||
collection: Option<&str>,
|
||||
) -> u32 {
|
||||
let loop_id = self.next_loop_id;
|
||||
self.next_loop_id += 1;
|
||||
self.view_trace.loop_frames.push(LoopFrame {
|
||||
loop_id,
|
||||
line,
|
||||
item_name: item.map(|s| s.to_string()),
|
||||
collection: collection.map(|s| s.to_string()),
|
||||
iterations: Vec::new(),
|
||||
});
|
||||
self.loop_stack.push((loop_id, 0));
|
||||
loop_id
|
||||
}
|
||||
|
||||
fn enter_loop_iter(&mut self, loop_id: u32, index: u32, item_value: &str) {
|
||||
if let Some((_, cur)) = self.loop_stack.iter_mut().rev().find(|(id, _)| *id == loop_id)
|
||||
{
|
||||
*cur = index;
|
||||
}
|
||||
let call_id = self.current_call_id();
|
||||
if let Some(fr) = self
|
||||
.view_trace
|
||||
.loop_frames
|
||||
.iter_mut()
|
||||
.find(|f| f.loop_id == loop_id)
|
||||
{
|
||||
fr.iterations.push(LoopIter {
|
||||
index,
|
||||
item_value: item_value.to_string(),
|
||||
call_id,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
fn end_view_loop(&mut self, loop_id: u32) {
|
||||
if self
|
||||
.loop_stack
|
||||
.last()
|
||||
.map(|(id, _)| *id == loop_id)
|
||||
.unwrap_or(false)
|
||||
{
|
||||
self.loop_stack.pop();
|
||||
}
|
||||
}
|
||||
|
||||
fn record_stmt_event(&mut self, mut ev: StmtEvent) {
|
||||
if self.capture {
|
||||
if ev.loop_id.is_none() || ev.iter.is_none() {
|
||||
let (lid, iter) = self.loop_ctx();
|
||||
if ev.loop_id.is_none() {
|
||||
ev.loop_id = lid;
|
||||
}
|
||||
if ev.iter.is_none() {
|
||||
ev.iter = iter;
|
||||
}
|
||||
}
|
||||
self.view_trace.events.push(ev);
|
||||
}
|
||||
}
|
||||
|
||||
fn record_branch_hit(&mut self, line: u32, arm_index: usize) {
|
||||
let call_id = self.current_call_id();
|
||||
if let Some(existing) = self.view_trace.branches.iter_mut().find(|h| {
|
||||
h.line == line && h.arm_index == arm_index && h.call_id == call_id
|
||||
}) {
|
||||
existing.count += 1;
|
||||
} else {
|
||||
self.view_trace.branches.push(BranchHit {
|
||||
line,
|
||||
arm_index,
|
||||
count: 1,
|
||||
call_id,
|
||||
});
|
||||
}
|
||||
let (loop_id, iter) = self.loop_ctx();
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line,
|
||||
kind: StmtEventKind::Branch,
|
||||
name: None,
|
||||
value_after: Some(format!("arm {}", arm_index + 1)),
|
||||
arm_index: Some(arm_index),
|
||||
iter,
|
||||
call_id,
|
||||
loop_id,
|
||||
});
|
||||
}
|
||||
|
||||
fn record_loop_hit(&mut self, line: u32, iterations: u32, last_item: Option<String>) {
|
||||
if let Some(existing) = self.view_trace.loops.iter_mut().find(|h| h.line == line) {
|
||||
existing.iterations = iterations;
|
||||
if last_item.is_some() {
|
||||
existing.last_item = last_item.clone();
|
||||
}
|
||||
} else {
|
||||
self.view_trace.loops.push(LoopHit {
|
||||
line,
|
||||
iterations,
|
||||
last_item: last_item.clone(),
|
||||
});
|
||||
}
|
||||
let (loop_id, _) = self.loop_ctx();
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line,
|
||||
kind: StmtEventKind::Loop,
|
||||
name: None,
|
||||
value_after: Some(format!("{iterations} iters")),
|
||||
arm_index: None,
|
||||
// Summary event: total count (not 0-based index).
|
||||
iter: Some(iterations),
|
||||
call_id: self.current_call_id(),
|
||||
loop_id,
|
||||
});
|
||||
}
|
||||
|
||||
/// Run a function by name anywhere in the module (for `lib/subtask` workers).
|
||||
pub fn invoke_function(
|
||||
&mut self,
|
||||
@@ -337,6 +526,7 @@ impl Interpreter {
|
||||
}
|
||||
|
||||
let ret = Value::None;
|
||||
self.push_view_call(fun, &env);
|
||||
self.host.push_call_frame(&fun.name);
|
||||
let body_result = (|| -> Result<Value> {
|
||||
for stmt in &fun.body {
|
||||
@@ -347,6 +537,7 @@ impl Interpreter {
|
||||
Ok(ret)
|
||||
})();
|
||||
self.host.pop_call_frame();
|
||||
self.pop_view_call();
|
||||
let ret = body_result?;
|
||||
if capture_entry_env {
|
||||
self.entry_bindings = env.vars_clone();
|
||||
@@ -402,6 +593,18 @@ impl Interpreter {
|
||||
],
|
||||
);
|
||||
}
|
||||
if self.capture {
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line: span.line,
|
||||
kind: StmtEventKind::Assign,
|
||||
name: Some(name.clone()),
|
||||
value_after: Some(v.as_display()),
|
||||
arm_index: None,
|
||||
iter: None,
|
||||
call_id: self.current_call_id(),
|
||||
loop_id: None,
|
||||
});
|
||||
}
|
||||
env.set(name.clone(), v);
|
||||
Ok(None)
|
||||
}
|
||||
@@ -425,6 +628,18 @@ impl Interpreter {
|
||||
&[("kind", "return"), ("value", display.as_str())],
|
||||
);
|
||||
}
|
||||
if self.capture {
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line: span.line,
|
||||
kind: StmtEventKind::Return,
|
||||
name: None,
|
||||
value_after: Some(v.as_display()),
|
||||
arm_index: None,
|
||||
iter: None,
|
||||
call_id: self.current_call_id(),
|
||||
loop_id: None,
|
||||
});
|
||||
}
|
||||
Ok(Some(v))
|
||||
}
|
||||
Stmt::Call { call, span } => {
|
||||
@@ -437,7 +652,26 @@ impl Interpreter {
|
||||
&[("kind", "call"), ("callee", call.callee.as_str())],
|
||||
);
|
||||
}
|
||||
let _ = self.eval_call(module, fun, env, call)?;
|
||||
let stdout_before = self.captured_stdout.len();
|
||||
let v = self.eval_call(module, fun, env, call)?;
|
||||
if self.capture {
|
||||
let (loop_id, iter) = self.loop_ctx();
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line: span.line,
|
||||
kind: StmtEventKind::Call,
|
||||
name: Some(call.callee.clone()),
|
||||
value_after: Some(call_event_brief(
|
||||
&v,
|
||||
&self.captured_stdout,
|
||||
stdout_before,
|
||||
&call.callee,
|
||||
)),
|
||||
arm_index: None,
|
||||
iter,
|
||||
call_id: self.current_call_id(),
|
||||
loop_id,
|
||||
});
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
Stmt::Expr { value, span } => {
|
||||
@@ -450,7 +684,30 @@ impl Interpreter {
|
||||
&[("kind", "expr")],
|
||||
);
|
||||
}
|
||||
let _ = self.eval_expr(module, fun, env, value)?;
|
||||
let stdout_before = self.captured_stdout.len();
|
||||
let v = self.eval_expr(module, fun, env, value)?;
|
||||
if self.capture {
|
||||
let (loop_id, iter) = self.loop_ctx();
|
||||
let name = match value {
|
||||
Expr::Call(c) => Some(c.callee.clone()),
|
||||
_ => None,
|
||||
};
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line: span.line,
|
||||
kind: StmtEventKind::Call,
|
||||
name: name.clone(),
|
||||
value_after: Some(call_event_brief(
|
||||
&v,
|
||||
&self.captured_stdout,
|
||||
stdout_before,
|
||||
name.as_deref().unwrap_or("expr"),
|
||||
)),
|
||||
arm_index: None,
|
||||
iter,
|
||||
call_id: self.current_call_id(),
|
||||
loop_id,
|
||||
});
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
Stmt::Branch { arms, span } => {
|
||||
@@ -463,12 +720,15 @@ impl Interpreter {
|
||||
&[("kind", "branch")],
|
||||
);
|
||||
}
|
||||
for arm in arms {
|
||||
for (arm_index, arm) in arms.iter().enumerate() {
|
||||
let take = match &arm.condition {
|
||||
None => true,
|
||||
Some(cond) => self.eval_expr(module, fun, env, cond)?.truthy(),
|
||||
};
|
||||
if take {
|
||||
if self.capture {
|
||||
self.record_branch_hit(span.line, arm_index);
|
||||
}
|
||||
for s in &arm.body {
|
||||
if let Some(v) = self.exec_stmt(module, fun, env, s)? {
|
||||
return Ok(Some(v));
|
||||
@@ -493,18 +753,38 @@ impl Interpreter {
|
||||
&[("kind", "while")],
|
||||
);
|
||||
}
|
||||
let loop_id = if self.capture {
|
||||
Some(self.begin_view_loop(span.line, None, None))
|
||||
} else {
|
||||
None
|
||||
};
|
||||
let mut guard = 0u32;
|
||||
while self.eval_expr(module, fun, env, condition)?.truthy() {
|
||||
guard += 1;
|
||||
if guard > 1_000_000 {
|
||||
return Err(self.err("while loop exceeded iteration limit"));
|
||||
}
|
||||
if let Some(lid) = loop_id {
|
||||
self.enter_loop_iter(lid, guard - 1, &format!("iter {guard}"));
|
||||
}
|
||||
for s in body {
|
||||
if let Some(v) = self.exec_stmt(module, fun, env, s)? {
|
||||
if self.capture {
|
||||
if let Some(lid) = loop_id {
|
||||
self.end_view_loop(lid);
|
||||
}
|
||||
self.record_loop_hit(span.line, guard, None);
|
||||
}
|
||||
return Ok(Some(v));
|
||||
}
|
||||
}
|
||||
}
|
||||
if self.capture {
|
||||
if let Some(lid) = loop_id {
|
||||
self.end_view_loop(lid);
|
||||
}
|
||||
self.record_loop_hit(span.line, guard, None);
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
Stmt::ForEach {
|
||||
@@ -534,14 +814,56 @@ impl Interpreter {
|
||||
Ok(_) => unreachable!(),
|
||||
Err(m) => return Err(self.err(m)),
|
||||
};
|
||||
let loop_id = if self.capture {
|
||||
Some(self.begin_view_loop(
|
||||
span.line,
|
||||
Some(item.as_str()),
|
||||
Some(collection.as_str()),
|
||||
))
|
||||
} else {
|
||||
None
|
||||
};
|
||||
let mut iterations = 0u32;
|
||||
let mut last_item: Option<String> = None;
|
||||
for val in items {
|
||||
let index = iterations;
|
||||
iterations += 1;
|
||||
let display = val.as_display();
|
||||
last_item = Some(display.clone());
|
||||
if let Some(lid) = loop_id {
|
||||
self.enter_loop_iter(lid, index, &display);
|
||||
self.record_stmt_event(StmtEvent {
|
||||
line: span.line,
|
||||
kind: StmtEventKind::BindRef,
|
||||
name: Some(item.clone()),
|
||||
value_after: Some(format!(
|
||||
"{collection}[{index}]={display}"
|
||||
)),
|
||||
arm_index: None,
|
||||
iter: Some(index),
|
||||
call_id: self.current_call_id(),
|
||||
loop_id: Some(lid),
|
||||
});
|
||||
}
|
||||
env.set(item.clone(), val);
|
||||
for s in body {
|
||||
if let Some(v) = self.exec_stmt(module, fun, env, s)? {
|
||||
if self.capture {
|
||||
if let Some(lid) = loop_id {
|
||||
self.end_view_loop(lid);
|
||||
}
|
||||
self.record_loop_hit(span.line, iterations, last_item.clone());
|
||||
}
|
||||
return Ok(Some(v));
|
||||
}
|
||||
}
|
||||
}
|
||||
if self.capture {
|
||||
if let Some(lid) = loop_id {
|
||||
self.end_view_loop(lid);
|
||||
}
|
||||
self.record_loop_hit(span.line, iterations, last_item);
|
||||
}
|
||||
Ok(None)
|
||||
}
|
||||
}
|
||||
@@ -1399,6 +1721,38 @@ fn cmp_ord(l: &Value, r: &Value, f: impl Fn(std::cmp::Ordering) -> bool) -> Resu
|
||||
}
|
||||
}
|
||||
|
||||
fn brief_trace_val(v: &Value) -> String {
|
||||
let s = v.as_display();
|
||||
if s.chars().count() > 24 {
|
||||
format!("{}…", s.chars().take(24).collect::<String>())
|
||||
} else {
|
||||
s
|
||||
}
|
||||
}
|
||||
|
||||
/// Prefer real result; else last stdout line emitted by the call; else callee name.
|
||||
fn call_event_brief(v: &Value, stdout: &str, stdout_before: usize, callee: &str) -> String {
|
||||
if !matches!(v, Value::None) {
|
||||
return brief_trace_val(v);
|
||||
}
|
||||
if stdout.len() > stdout_before {
|
||||
let delta = &stdout[stdout_before..];
|
||||
let line = delta
|
||||
.trim_end()
|
||||
.lines()
|
||||
.last()
|
||||
.unwrap_or(delta.trim_end());
|
||||
if !line.is_empty() {
|
||||
return if line.chars().count() > 48 {
|
||||
format!("{}…", line.chars().take(48).collect::<String>())
|
||||
} else {
|
||||
line.to_string()
|
||||
};
|
||||
}
|
||||
}
|
||||
callee.to_string()
|
||||
}
|
||||
|
||||
fn stmt_span(stmt: &Stmt) -> Span {
|
||||
match stmt {
|
||||
Stmt::Assign { span, .. }
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
//! L3 Capability derivation from symbols + modules.
|
||||
|
||||
use crate::knowledge::fingerprint::tokenize_ident;
|
||||
use crate::knowledge::ir::{CapabilityInfo, Evidence, ModuleInfo, SymbolInfo};
|
||||
use crate::knowledge::util::slugify;
|
||||
|
||||
pub fn derive_capabilities(
|
||||
symbols: &[SymbolInfo],
|
||||
modules: &[ModuleInfo],
|
||||
) -> Vec<CapabilityInfo> {
|
||||
let mut caps: Vec<CapabilityInfo> = Vec::new();
|
||||
|
||||
for s in symbols {
|
||||
if s.kind == "test" {
|
||||
continue;
|
||||
}
|
||||
let (id, name, desc) = if let Some(ref c) = s.capability {
|
||||
let id = slugify(c);
|
||||
(id.clone(), c.clone(), s.use_when.clone().unwrap_or_else(|| c.clone()))
|
||||
} else {
|
||||
let tokens = tokenize_ident(&s.name);
|
||||
let name = if tokens.is_empty() {
|
||||
s.name.clone()
|
||||
} else {
|
||||
// module.verb_noun style
|
||||
let mod_short = s
|
||||
.module
|
||||
.rsplit('/')
|
||||
.next()
|
||||
.unwrap_or(&s.module)
|
||||
.replace(".mq.md", "");
|
||||
format!("{}.{}", slugify(&mod_short), tokens.join("_"))
|
||||
};
|
||||
let id = slugify(&name);
|
||||
let desc = s
|
||||
.use_when
|
||||
.clone()
|
||||
.or_else(|| {
|
||||
modules
|
||||
.iter()
|
||||
.find(|m| m.id == s.module)
|
||||
.and_then(|m| m.responsibility.clone())
|
||||
})
|
||||
.unwrap_or_else(|| format!("Capability implemented by `{}`", s.name));
|
||||
(id, name, desc)
|
||||
};
|
||||
|
||||
if let Some(existing) = caps.iter_mut().find(|c| c.id == id) {
|
||||
if !existing.implemented_by.contains(&s.id) {
|
||||
existing.implemented_by.push(s.id.clone());
|
||||
}
|
||||
if !existing.modules.contains(&s.module) {
|
||||
existing.modules.push(s.module.clone());
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
caps.push(CapabilityInfo {
|
||||
id,
|
||||
name,
|
||||
description: desc,
|
||||
implemented_by: vec![s.id.clone()],
|
||||
modules: vec![s.module.clone()],
|
||||
status: s.status.clone(),
|
||||
use_when: s.use_when.clone(),
|
||||
do_not_use_when: s.do_not_use_when.clone(),
|
||||
related: s.related.clone(),
|
||||
evidence: Evidence {
|
||||
sources: vec![s.resource.clone()],
|
||||
tests: s.tests.clone(),
|
||||
..Evidence::default()
|
||||
},
|
||||
confidence: s.confidence.clone(),
|
||||
introduced: None,
|
||||
verified: None,
|
||||
last_used: None,
|
||||
last_tested: None,
|
||||
possible_duplicates: Vec::new(),
|
||||
});
|
||||
}
|
||||
|
||||
// related edges are authored; graph builder adds RelatedTo edges
|
||||
caps.sort_by(|a, b| a.id.cmp(&b.id));
|
||||
caps
|
||||
}
|
||||
@@ -0,0 +1,595 @@
|
||||
//! Compile KnowledgeGraph into `.marqdo/` projections.
|
||||
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
|
||||
use anyhow::{Context, Result};
|
||||
use serde_json::json;
|
||||
|
||||
use crate::knowledge::extract::{extract_graph, ExtractOptions};
|
||||
use crate::knowledge::ir::KnowledgeGraph;
|
||||
use crate::knowledge::util::{module_stem, slugify, yaml_escape};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct KnowledgeOptions {
|
||||
pub path: std::path::PathBuf,
|
||||
pub out_dir: std::path::PathBuf,
|
||||
}
|
||||
|
||||
pub fn compile(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
|
||||
let extract_opts = ExtractOptions {
|
||||
path: opts.path.clone(),
|
||||
out_dir: opts.out_dir.clone(),
|
||||
};
|
||||
let graph = extract_graph(&extract_opts)?;
|
||||
write_projections(&opts.out_dir, &graph)?;
|
||||
eprintln!(
|
||||
"marqdo knowledge: {} module(s), {} symbol(s), {} capability(ies), {} knowledge → {}",
|
||||
graph.modules.len(),
|
||||
graph.symbols.len(),
|
||||
graph.capabilities.len(),
|
||||
graph.knowledge.len(),
|
||||
opts.out_dir.display()
|
||||
);
|
||||
Ok(graph)
|
||||
}
|
||||
|
||||
pub fn load_graph(out_dir: &Path) -> Result<KnowledgeGraph> {
|
||||
let graph_path = out_dir.join("graph").join("graph.json");
|
||||
let edges_path = out_dir.join("graph").join("edges.json");
|
||||
if !graph_path.exists() {
|
||||
anyhow::bail!(
|
||||
"no knowledge graph at {} — run `marqdo knowledge` first",
|
||||
graph_path.display()
|
||||
);
|
||||
}
|
||||
// Prefer re-extract for freshness when source path known; for query commands
|
||||
// we rebuild from JSON snapshot fields + re-scan if catalog sibling exists.
|
||||
// Snapshot load: reconstruct minimal IR from written pages + edges.json.
|
||||
let edges_raw = fs::read_to_string(&edges_path).unwrap_or_else(|_| "{\"edges\":[]}".into());
|
||||
let edges_v: serde_json::Value = serde_json::from_str(&edges_raw)?;
|
||||
let graph_raw = fs::read_to_string(&graph_path)?;
|
||||
let graph_v: serde_json::Value = serde_json::from_str(&graph_raw)?;
|
||||
|
||||
// Re-compile from recorded root if present in graph.json
|
||||
if let Some(root) = graph_v
|
||||
.pointer("/repository/root")
|
||||
.and_then(|v| v.as_str())
|
||||
{
|
||||
let root_path = Path::new(root);
|
||||
if root_path.exists() {
|
||||
return extract_graph(&ExtractOptions {
|
||||
path: root_path.to_path_buf(),
|
||||
out_dir: out_dir.to_path_buf(),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback: empty-ish graph with edges only
|
||||
let mut edges = Vec::new();
|
||||
if let Some(arr) = edges_v.get("edges").and_then(|e| e.as_array()) {
|
||||
for e in arr {
|
||||
let kind = match e.get("kind").and_then(|k| k.as_str()).unwrap_or("") {
|
||||
"implements" => crate::knowledge::ir::EdgeKind::Implements,
|
||||
"uses" => crate::knowledge::ir::EdgeKind::Uses,
|
||||
"depends_on" => crate::knowledge::ir::EdgeKind::DependsOn,
|
||||
"tested_by" => crate::knowledge::ir::EdgeKind::TestedBy,
|
||||
"documented_by" => crate::knowledge::ir::EdgeKind::DocumentedBy,
|
||||
"constrained_by" => crate::knowledge::ir::EdgeKind::ConstrainedBy,
|
||||
"decided_by" => crate::knowledge::ir::EdgeKind::DecidedBy,
|
||||
"supersedes" => crate::knowledge::ir::EdgeKind::Supersedes,
|
||||
"conflicts_with" => crate::knowledge::ir::EdgeKind::ConflictsWith,
|
||||
"deprecated_by" => crate::knowledge::ir::EdgeKind::DeprecatedBy,
|
||||
"derived_from" => crate::knowledge::ir::EdgeKind::DerivedFrom,
|
||||
"failed_by" => crate::knowledge::ir::EdgeKind::FailedBy,
|
||||
_ => crate::knowledge::ir::EdgeKind::RelatedTo,
|
||||
};
|
||||
edges.push(crate::knowledge::ir::Edge {
|
||||
from: e.get("from").and_then(|v| v.as_str()).unwrap_or("").into(),
|
||||
to: e.get("to").and_then(|v| v.as_str()).unwrap_or("").into(),
|
||||
kind,
|
||||
note: e.get("note").and_then(|v| v.as_str()).map(|s| s.to_string()),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
Ok(KnowledgeGraph {
|
||||
repository: crate::knowledge::ir::RepositoryInfo {
|
||||
title: graph_v
|
||||
.pointer("/repository/title")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("marqdo-project")
|
||||
.into(),
|
||||
root: graph_v
|
||||
.pointer("/repository/root")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or(".")
|
||||
.into(),
|
||||
languages: vec!["marqdo".into()],
|
||||
module_count: 0,
|
||||
symbol_count: 0,
|
||||
capability_count: 0,
|
||||
knowledge_count: 0,
|
||||
},
|
||||
modules: Vec::new(),
|
||||
symbols: Vec::new(),
|
||||
capabilities: Vec::new(),
|
||||
knowledge: Vec::new(),
|
||||
edges,
|
||||
generated_by: graph_v
|
||||
.pointer("/generated/by")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("marqdo")
|
||||
.into(),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn ensure_compiled(path: &Path, out_dir: &Path) -> Result<KnowledgeGraph> {
|
||||
let graph_path = out_dir.join("graph").join("graph.json");
|
||||
if graph_path.exists() {
|
||||
// Always refresh from source when path given
|
||||
return compile(KnowledgeOptions {
|
||||
path: path.to_path_buf(),
|
||||
out_dir: out_dir.to_path_buf(),
|
||||
});
|
||||
}
|
||||
compile(KnowledgeOptions {
|
||||
path: path.to_path_buf(),
|
||||
out_dir: out_dir.to_path_buf(),
|
||||
})
|
||||
}
|
||||
|
||||
fn write_projections(out_dir: &Path, graph: &KnowledgeGraph) -> Result<()> {
|
||||
let dirs = [
|
||||
"catalog/modules",
|
||||
"catalog/symbols",
|
||||
"catalog/capabilities",
|
||||
"knowledge/facts",
|
||||
"knowledge/decisions",
|
||||
"knowledge/constraints",
|
||||
"knowledge/patterns",
|
||||
"knowledge/failures",
|
||||
"knowledge/migrations",
|
||||
"graph",
|
||||
"agent/policies",
|
||||
"agent/skills",
|
||||
"agent/contexts",
|
||||
"agent/episodes",
|
||||
"tests/reuse",
|
||||
"tests/knowledge",
|
||||
"tests/retrieval",
|
||||
];
|
||||
for d in dirs {
|
||||
fs::create_dir_all(out_dir.join(d))
|
||||
.with_context(|| format!("create {}/{}", out_dir.display(), d))?;
|
||||
}
|
||||
|
||||
// L0 repository
|
||||
fs::write(
|
||||
out_dir.join("catalog/repository.mq.md"),
|
||||
render_repository(graph),
|
||||
)?;
|
||||
|
||||
// L1 modules
|
||||
for m in &graph.modules {
|
||||
let stem = module_stem(&m.resource);
|
||||
fs::write(
|
||||
out_dir.join("catalog/modules").join(format!("{stem}.md")),
|
||||
render_module(m, graph),
|
||||
)?;
|
||||
}
|
||||
|
||||
// L2 symbols
|
||||
for s in &graph.symbols {
|
||||
let stem = slugify(&s.id.replace("::", "__").replace('/', "__"));
|
||||
fs::write(
|
||||
out_dir.join("catalog/symbols").join(format!("{stem}.md")),
|
||||
render_symbol(s),
|
||||
)?;
|
||||
}
|
||||
|
||||
// L3 capabilities
|
||||
for c in &graph.capabilities {
|
||||
let stem = slugify(&c.id);
|
||||
fs::write(
|
||||
out_dir
|
||||
.join("catalog/capabilities")
|
||||
.join(format!("{stem}.md")),
|
||||
render_capability(c),
|
||||
)?;
|
||||
}
|
||||
|
||||
// L4 knowledge
|
||||
for k in &graph.knowledge {
|
||||
let dir = out_dir.join("knowledge").join(k.kind.subdir());
|
||||
let stem = slugify(&k.id.rsplit('/').next().unwrap_or(&k.id));
|
||||
let path = dir.join(format!("{stem}.md"));
|
||||
let body = if let Some(ref src) = k.source_text {
|
||||
// Ensure generated marker without destroying authored content
|
||||
if src.contains("GENERATED by marqdo") {
|
||||
src.clone()
|
||||
} else {
|
||||
format!(
|
||||
"<!-- projected by marqdo knowledge from {} -->\n{src}",
|
||||
k.resource
|
||||
)
|
||||
}
|
||||
} else {
|
||||
render_knowledge(k)
|
||||
};
|
||||
fs::write(&path, body)?;
|
||||
}
|
||||
|
||||
// Graph JSON
|
||||
let graph_json = serde_json::to_string_pretty(&graph.to_graph_json())?;
|
||||
fs::write(out_dir.join("graph/graph.json"), graph_json)?;
|
||||
let edges_json = serde_json::to_string_pretty(&graph.to_edges_json())?;
|
||||
fs::write(out_dir.join("graph/edges.json"), edges_json)?;
|
||||
|
||||
// Search index
|
||||
let index = json!({
|
||||
"type": "Marqdo Knowledge Index",
|
||||
"generated": { "by": graph.generated_by },
|
||||
"entries": graph.index_map(),
|
||||
});
|
||||
fs::write(
|
||||
out_dir.join("graph/index.json"),
|
||||
serde_json::to_string_pretty(&index)?,
|
||||
)?;
|
||||
|
||||
// Root index.mq.md
|
||||
fs::write(out_dir.join("index.mq.md"), render_index_mq(graph))?;
|
||||
|
||||
// Augment root catalog.yaml if present (append engineering summary)
|
||||
write_engineering_summary(out_dir, graph)?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn write_engineering_summary(out_dir: &Path, graph: &KnowledgeGraph) -> Result<()> {
|
||||
let path = out_dir.join("engineering.yaml");
|
||||
let mut out = String::new();
|
||||
out.push_str("# GENERATED by marqdo knowledge — do not edit by hand\n");
|
||||
out.push_str("type: Marqdo Engineering Knowledge\n");
|
||||
out.push_str(&format!("title: {}\n", yaml_escape(&graph.repository.title)));
|
||||
out.push_str("generated:\n");
|
||||
out.push_str(&format!(" by: {}\n", yaml_escape(&graph.generated_by)));
|
||||
out.push_str("layers:\n");
|
||||
out.push_str(&format!(" modules: {}\n", graph.modules.len()));
|
||||
out.push_str(&format!(" symbols: {}\n", graph.symbols.len()));
|
||||
out.push_str(&format!(" capabilities: {}\n", graph.capabilities.len()));
|
||||
out.push_str(&format!(" knowledge: {}\n", graph.knowledge.len()));
|
||||
out.push_str(&format!(" edges: {}\n", graph.edges.len()));
|
||||
out.push_str("capabilities:\n");
|
||||
if graph.capabilities.is_empty() {
|
||||
out.push_str(" []\n");
|
||||
} else {
|
||||
for c in &graph.capabilities {
|
||||
out.push_str(&format!(" - id: {}\n", yaml_escape(&c.id)));
|
||||
out.push_str(&format!(" name: {}\n", yaml_escape(&c.name)));
|
||||
out.push_str(&format!(" status: {}\n", c.status.as_str()));
|
||||
if !c.implemented_by.is_empty() {
|
||||
out.push_str(" implemented_by:\n");
|
||||
for s in &c.implemented_by {
|
||||
out.push_str(&format!(" - {}\n", yaml_escape(s)));
|
||||
}
|
||||
}
|
||||
if !c.possible_duplicates.is_empty() {
|
||||
out.push_str(" possible_duplicates:\n");
|
||||
for s in &c.possible_duplicates {
|
||||
out.push_str(&format!(" - {}\n", yaml_escape(s)));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
out.push_str("knowledge:\n");
|
||||
if graph.knowledge.is_empty() {
|
||||
out.push_str(" []\n");
|
||||
} else {
|
||||
for k in &graph.knowledge {
|
||||
out.push_str(&format!(" - id: {}\n", yaml_escape(&k.id)));
|
||||
out.push_str(&format!(" type: {}\n", k.kind.as_str()));
|
||||
out.push_str(&format!(" title: {}\n", yaml_escape(&k.title)));
|
||||
out.push_str(&format!(" status: {}\n", k.status.as_str()));
|
||||
}
|
||||
}
|
||||
fs::write(path, out)?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn render_repository(graph: &KnowledgeGraph) -> String {
|
||||
let r = &graph.repository;
|
||||
format!(
|
||||
r#"---
|
||||
type: Marqdo Repository
|
||||
title: {title}
|
||||
generated:
|
||||
by: {by}
|
||||
status: stable
|
||||
---
|
||||
|
||||
# {title}
|
||||
|
||||
> GENERATED by Marqdo Engineering Knowledge Compiler. Do not edit by hand.
|
||||
|
||||
## Repository
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Languages | {langs} |
|
||||
| Modules | {modules} |
|
||||
| Symbols | {symbols} |
|
||||
| Capabilities | {caps} |
|
||||
| Knowledge | {know} |
|
||||
| Edges | {edges} |
|
||||
|
||||
## Layers
|
||||
|
||||
- L0 Repository — this page
|
||||
- L1 Modules — `catalog/modules/`
|
||||
- L2 Symbols — `catalog/symbols/`
|
||||
- L3 Capabilities — `catalog/capabilities/`
|
||||
- L4 Engineering Knowledge — `knowledge/`
|
||||
"#,
|
||||
title = r.title,
|
||||
by = graph.generated_by,
|
||||
langs = r.languages.join(", "),
|
||||
modules = r.module_count,
|
||||
symbols = r.symbol_count,
|
||||
caps = r.capability_count,
|
||||
know = r.knowledge_count,
|
||||
edges = graph.edges.len(),
|
||||
)
|
||||
}
|
||||
|
||||
fn render_module(m: &crate::knowledge::ir::ModuleInfo, graph: &KnowledgeGraph) -> String {
|
||||
let mut exports = String::new();
|
||||
if m.exports.is_empty() {
|
||||
exports.push_str("_None_\n");
|
||||
} else {
|
||||
exports.push_str("| Symbol | Kind |\n|--------|------|\n");
|
||||
for e in &m.exports {
|
||||
let kind = graph
|
||||
.symbols
|
||||
.iter()
|
||||
.find(|s| s.module == m.id && s.name == *e)
|
||||
.map(|s| s.kind.as_str())
|
||||
.unwrap_or("fn");
|
||||
exports.push_str(&format!("| `{e}` | {kind} |\n"));
|
||||
}
|
||||
}
|
||||
let resp = m.responsibility.as_deref().unwrap_or("_unspecified_");
|
||||
format!(
|
||||
r#"---
|
||||
type: Marqdo Module
|
||||
title: {title}
|
||||
resource: {resource}
|
||||
status: {status}
|
||||
generated:
|
||||
by: {by}
|
||||
---
|
||||
|
||||
# {title}
|
||||
|
||||
> Auto-generated from `{resource}`. Do not edit by hand.
|
||||
|
||||
## Responsibility
|
||||
|
||||
{resp}
|
||||
|
||||
## Exports
|
||||
|
||||
{exports}
|
||||
"#,
|
||||
title = m.title,
|
||||
resource = m.resource,
|
||||
status = m.status.as_str(),
|
||||
by = graph.generated_by,
|
||||
resp = resp,
|
||||
exports = exports,
|
||||
)
|
||||
}
|
||||
|
||||
fn render_symbol(s: &crate::knowledge::ir::SymbolInfo) -> String {
|
||||
let params = if s.params.is_empty() {
|
||||
"[]".into()
|
||||
} else {
|
||||
s.params
|
||||
.iter()
|
||||
.map(|p| format!(" - {p}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n")
|
||||
};
|
||||
let use_when = s.use_when.as_deref().unwrap_or("_unspecified_");
|
||||
let do_not = s.do_not_use_when.as_deref().unwrap_or("_unspecified_");
|
||||
format!(
|
||||
r#"---
|
||||
type: Function
|
||||
name: {name}
|
||||
module: {module}
|
||||
symbol: {name}
|
||||
resource: {resource}
|
||||
status: {status}
|
||||
visibility: {vis}
|
||||
fingerprint: {fp}
|
||||
capability: {cap}
|
||||
generated:
|
||||
by: marqdo/knowledge
|
||||
---
|
||||
|
||||
# {name}
|
||||
|
||||
## Use when
|
||||
|
||||
{use_when}
|
||||
|
||||
## Do not use when
|
||||
|
||||
{do_not}
|
||||
|
||||
## Signature
|
||||
|
||||
params:
|
||||
{params}
|
||||
|
||||
## Calls
|
||||
|
||||
{calls}
|
||||
|
||||
## Fingerprint
|
||||
|
||||
```
|
||||
{fpt}
|
||||
```
|
||||
"#,
|
||||
name = s.name,
|
||||
module = s.module,
|
||||
resource = s.resource,
|
||||
status = s.status.as_str(),
|
||||
vis = s.visibility,
|
||||
fp = s.fingerprint,
|
||||
cap = s.capability.as_deref().unwrap_or(""),
|
||||
use_when = use_when,
|
||||
do_not = do_not,
|
||||
params = params,
|
||||
calls = if s.calls.is_empty() {
|
||||
"_None_".into()
|
||||
} else {
|
||||
s.calls
|
||||
.iter()
|
||||
.map(|c| format!("- `{c}`"))
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n")
|
||||
},
|
||||
fpt = s.fingerprint_text,
|
||||
)
|
||||
}
|
||||
|
||||
fn render_capability(c: &crate::knowledge::ir::CapabilityInfo) -> String {
|
||||
let use_when = c.use_when.as_deref().unwrap_or(&c.description);
|
||||
let do_not = c.do_not_use_when.as_deref().unwrap_or("_unspecified_");
|
||||
format!(
|
||||
r#"---
|
||||
type: Capability
|
||||
id: {id}
|
||||
name: {name}
|
||||
status: {status}
|
||||
generated:
|
||||
by: marqdo/knowledge
|
||||
---
|
||||
|
||||
# {name}
|
||||
|
||||
{desc}
|
||||
|
||||
## Use when
|
||||
|
||||
{use_when}
|
||||
|
||||
## Do not use when
|
||||
|
||||
{do_not}
|
||||
|
||||
## Implemented by
|
||||
|
||||
{impls}
|
||||
|
||||
## Possible duplicates
|
||||
|
||||
{dups}
|
||||
"#,
|
||||
id = c.id,
|
||||
name = c.name,
|
||||
status = c.status.as_str(),
|
||||
desc = c.description,
|
||||
use_when = use_when,
|
||||
do_not = do_not,
|
||||
impls = if c.implemented_by.is_empty() {
|
||||
"_None_".into()
|
||||
} else {
|
||||
c.implemented_by
|
||||
.iter()
|
||||
.map(|s| format!("- `{s}`"))
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n")
|
||||
},
|
||||
dups = if c.possible_duplicates.is_empty() {
|
||||
"_None_".into()
|
||||
} else {
|
||||
c.possible_duplicates
|
||||
.iter()
|
||||
.map(|s| format!("- `{s}`"))
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n")
|
||||
},
|
||||
)
|
||||
}
|
||||
|
||||
fn render_knowledge(k: &crate::knowledge::ir::KnowledgeItem) -> String {
|
||||
format!(
|
||||
r#"---
|
||||
type: {ty}
|
||||
id: {id}
|
||||
title: {title}
|
||||
status: {status}
|
||||
generated:
|
||||
by: marqdo/knowledge
|
||||
---
|
||||
|
||||
# {title}
|
||||
|
||||
{summary}
|
||||
"#,
|
||||
ty = k.kind.as_str(),
|
||||
id = k.id,
|
||||
title = k.title,
|
||||
status = k.status.as_str(),
|
||||
summary = k.body_summary,
|
||||
)
|
||||
}
|
||||
|
||||
fn render_index_mq(graph: &KnowledgeGraph) -> String {
|
||||
format!(
|
||||
r#"---
|
||||
type: Marqdo Engineering Knowledge
|
||||
title: Engineering Knowledge Index
|
||||
generated:
|
||||
by: {by}
|
||||
---
|
||||
|
||||
# Engineering Knowledge Index
|
||||
|
||||
> GENERATED. Source of truth remains `*.mq.md`. This tree is a Knowledge Projection.
|
||||
|
||||
## Counts
|
||||
|
||||
| Layer | Count |
|
||||
|-------|------:|
|
||||
| Modules | {modules} |
|
||||
| Symbols | {symbols} |
|
||||
| Capabilities | {caps} |
|
||||
| Knowledge | {know} |
|
||||
| Edges | {edges} |
|
||||
|
||||
## Commands
|
||||
|
||||
```
|
||||
marqdo knowledge
|
||||
marqdo find "query"
|
||||
marqdo reuse "task"
|
||||
marqdo duplicate
|
||||
marqdo impact PATH
|
||||
marqdo conflicts
|
||||
marqdo stale
|
||||
marqdo verify
|
||||
```
|
||||
"#,
|
||||
by = graph.generated_by,
|
||||
modules = graph.modules.len(),
|
||||
symbols = graph.symbols.len(),
|
||||
caps = graph.capabilities.len(),
|
||||
know = graph.knowledge.len(),
|
||||
edges = graph.edges.len(),
|
||||
)
|
||||
}
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
//! Duplicate capability / symbol detection via fingerprints.
|
||||
|
||||
use crate::knowledge::fingerprint::symbol_similarity;
|
||||
use crate::knowledge::ir::{CapabilityInfo, Edge, EdgeKind, SymbolInfo};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct DuplicatePair {
|
||||
pub left: String,
|
||||
pub right: String,
|
||||
pub similarity: f64,
|
||||
pub left_resource: String,
|
||||
pub right_resource: String,
|
||||
}
|
||||
|
||||
pub fn find_duplicates(symbols: &[SymbolInfo], threshold: f64) -> Vec<DuplicatePair> {
|
||||
let mut pairs = Vec::new();
|
||||
for i in 0..symbols.len() {
|
||||
if symbols[i].kind == "test" {
|
||||
continue;
|
||||
}
|
||||
for j in (i + 1)..symbols.len() {
|
||||
if symbols[j].kind == "test" {
|
||||
continue;
|
||||
}
|
||||
if symbols[i].module == symbols[j].module && symbols[i].name == symbols[j].name {
|
||||
continue;
|
||||
}
|
||||
let sim = symbol_similarity(&symbols[i], &symbols[j]);
|
||||
if sim >= threshold {
|
||||
pairs.push(DuplicatePair {
|
||||
left: symbols[i].id.clone(),
|
||||
right: symbols[j].id.clone(),
|
||||
similarity: sim,
|
||||
left_resource: symbols[i].resource.clone(),
|
||||
right_resource: symbols[j].resource.clone(),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
pairs.sort_by(|a, b| {
|
||||
b.similarity
|
||||
.partial_cmp(&a.similarity)
|
||||
.unwrap_or(std::cmp::Ordering::Equal)
|
||||
});
|
||||
pairs
|
||||
}
|
||||
|
||||
/// During extract: add conflicts_with-style related edges for near-duplicates.
|
||||
pub fn annotate_duplicates(
|
||||
symbols: &[SymbolInfo],
|
||||
edges: &mut Vec<Edge>,
|
||||
_capabilities: &[CapabilityInfo],
|
||||
) {
|
||||
for pair in find_duplicates(symbols, 0.75) {
|
||||
edges.push(Edge {
|
||||
from: format!("symbol:{}", pair.left),
|
||||
to: format!("symbol:{}", pair.right),
|
||||
kind: EdgeKind::ConflictsWith,
|
||||
note: Some(format!("possible_duplicate:{:.2}", pair.similarity)),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
pub fn apply_duplicate_flags(
|
||||
mut capabilities: Vec<CapabilityInfo>,
|
||||
symbols: &[SymbolInfo],
|
||||
) -> Vec<CapabilityInfo> {
|
||||
let pairs = find_duplicates(symbols, 0.75);
|
||||
for pair in &pairs {
|
||||
for c in &mut capabilities {
|
||||
if c.implemented_by.iter().any(|s| s == &pair.left) {
|
||||
if !c.possible_duplicates.contains(&pair.right) {
|
||||
c.possible_duplicates.push(pair.right.clone());
|
||||
}
|
||||
}
|
||||
if c.implemented_by.iter().any(|s| s == &pair.right) {
|
||||
if !c.possible_duplicates.contains(&pair.left) {
|
||||
c.possible_duplicates.push(pair.left.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
capabilities
|
||||
}
|
||||
|
||||
pub fn format_duplicates_text(pairs: &[DuplicatePair]) -> String {
|
||||
let mut out = String::from("Possible duplicate capabilities\n\n");
|
||||
if pairs.is_empty() {
|
||||
out.push_str("_None above threshold._\n");
|
||||
return out;
|
||||
}
|
||||
for (i, p) in pairs.iter().enumerate() {
|
||||
out.push_str(&format!(
|
||||
"{}. {}::{}\n {}::{}\n similarity: {:.2}\n\n",
|
||||
i + 1,
|
||||
p.left_resource,
|
||||
p.left.rsplit("::").next().unwrap_or(&p.left),
|
||||
p.right_resource,
|
||||
p.right.rsplit("::").next().unwrap_or(&p.right),
|
||||
p.similarity
|
||||
));
|
||||
}
|
||||
out
|
||||
}
|
||||
@@ -0,0 +1,528 @@
|
||||
//! Extract Engineering Knowledge IR from a Marqdo source tree.
|
||||
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use anyhow::{Context, Result};
|
||||
|
||||
use crate::ast::Function;
|
||||
use crate::knowledge::fingerprint::{collect_calls, fingerprint_hash, fingerprint_text, ops_hint};
|
||||
use crate::knowledge::ir::{
|
||||
Confidence, Evidence, KnowledgeGraph, KnowledgeItem, KnowledgeKind, Lifecycle, ModuleInfo,
|
||||
RepositoryInfo, SymbolInfo,
|
||||
};
|
||||
use crate::knowledge::util::{
|
||||
extract_fm_field, extract_fm_list, extract_nested_by, extract_section, first_paragraph,
|
||||
module_stem, slugify,
|
||||
};
|
||||
use crate::lex::{classify_source, LineKind};
|
||||
use crate::parse::parse_source;
|
||||
|
||||
pub struct ExtractOptions {
|
||||
pub path: PathBuf,
|
||||
pub out_dir: PathBuf,
|
||||
}
|
||||
|
||||
pub fn extract_graph(opts: &ExtractOptions) -> Result<KnowledgeGraph> {
|
||||
let root = if opts.path.is_file() {
|
||||
opts.path
|
||||
.parent()
|
||||
.map(|p| p.to_path_buf())
|
||||
.unwrap_or_else(|| PathBuf::from("."))
|
||||
} else {
|
||||
opts.path.clone()
|
||||
};
|
||||
let root = root.canonicalize().unwrap_or(root);
|
||||
let out_canon = opts.out_dir.canonicalize().unwrap_or(opts.out_dir.clone());
|
||||
let version = env!("CARGO_PKG_VERSION");
|
||||
|
||||
let mut files = Vec::new();
|
||||
if opts.path.is_file() {
|
||||
files.push(opts.path.canonicalize().unwrap_or(opts.path.clone()));
|
||||
} else {
|
||||
collect_mq_md(&root, &root, &out_canon, &mut files)?;
|
||||
files.sort();
|
||||
}
|
||||
|
||||
let mut modules = Vec::new();
|
||||
let mut symbols = Vec::new();
|
||||
let mut knowledge = Vec::new();
|
||||
let mut had_err = false;
|
||||
|
||||
for abs in &files {
|
||||
let rel = abs
|
||||
.strip_prefix(&root)
|
||||
.unwrap_or(abs)
|
||||
.to_string_lossy()
|
||||
.replace('\\', "/");
|
||||
if rel.contains("/.marqdo/") || rel.starts_with(".marqdo/") {
|
||||
continue;
|
||||
}
|
||||
match inspect_source(abs, &rel) {
|
||||
Ok((m, syms, ks)) => {
|
||||
modules.push(m);
|
||||
symbols.extend(syms);
|
||||
knowledge.extend(ks);
|
||||
}
|
||||
Err(e) => {
|
||||
eprintln!("knowledge: skip {rel}: {e:#}");
|
||||
had_err = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Also scan authored knowledge markdown (non-.mq.md) under knowledge/ or doc/adr/
|
||||
collect_authored_knowledge(&root, &out_canon, &mut knowledge)?;
|
||||
|
||||
// Wire called_by
|
||||
let mut call_index: std::collections::HashMap<String, Vec<String>> =
|
||||
std::collections::HashMap::new();
|
||||
for s in &symbols {
|
||||
for c in &s.calls {
|
||||
let short = c.rsplit('.').next().unwrap_or(c).to_string();
|
||||
call_index.entry(short).or_default().push(s.id.clone());
|
||||
call_index.entry(c.clone()).or_default().push(s.id.clone());
|
||||
}
|
||||
}
|
||||
for s in &mut symbols {
|
||||
let mut cb = call_index.remove(&s.name).unwrap_or_default();
|
||||
cb.extend(call_index.remove(&s.id).unwrap_or_default());
|
||||
cb.sort();
|
||||
cb.dedup();
|
||||
s.called_by = cb;
|
||||
}
|
||||
|
||||
// Detect tests: paths containing /tests/ or name starting with test_
|
||||
for s in &mut symbols {
|
||||
if s.resource.contains("/tests/") || s.resource.starts_with("tests/") {
|
||||
// module-level test file — mark symbols as tests for same-named exports later
|
||||
}
|
||||
if s.name.starts_with("test_") || s.name.starts_with("测试") {
|
||||
s.kind = "test".into();
|
||||
}
|
||||
}
|
||||
let test_syms: Vec<(String, String)> = symbols
|
||||
.iter()
|
||||
.filter(|s| s.kind == "test" || s.resource.contains("/tests/") || s.resource.starts_with("tests/"))
|
||||
.map(|s| (s.name.clone(), s.id.clone()))
|
||||
.collect();
|
||||
for s in &mut symbols {
|
||||
for (tname, tid) in &test_syms {
|
||||
if tname.contains(&s.name) || s.tests.iter().any(|t| t == tid) {
|
||||
if !s.tests.contains(tid) && tid != &s.id {
|
||||
s.tests.push(tid.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let capabilities = crate::knowledge::capability::derive_capabilities(&symbols, &modules);
|
||||
let mut edges = crate::knowledge::graph::build_edges(&modules, &symbols, &capabilities, &knowledge);
|
||||
crate::knowledge::duplicate::annotate_duplicates(&symbols, &mut edges, &capabilities);
|
||||
|
||||
// Re-derive capability duplicate links after annotate (annotate mutates via returned list)
|
||||
let capabilities =
|
||||
crate::knowledge::duplicate::apply_duplicate_flags(capabilities, &symbols);
|
||||
|
||||
let repository = RepositoryInfo {
|
||||
title: root
|
||||
.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.unwrap_or("marqdo-project")
|
||||
.to_string(),
|
||||
root: root.to_string_lossy().to_string(),
|
||||
languages: vec!["marqdo".into()],
|
||||
module_count: modules.len(),
|
||||
symbol_count: symbols.len(),
|
||||
capability_count: capabilities.len(),
|
||||
knowledge_count: knowledge.len(),
|
||||
};
|
||||
|
||||
if had_err {
|
||||
eprintln!("knowledge: extraction completed with some skipped files");
|
||||
}
|
||||
|
||||
Ok(KnowledgeGraph {
|
||||
repository,
|
||||
modules,
|
||||
symbols,
|
||||
capabilities,
|
||||
knowledge,
|
||||
edges,
|
||||
generated_by: format!("marqdo/{version}"),
|
||||
})
|
||||
}
|
||||
|
||||
fn collect_mq_md(
|
||||
root: &Path,
|
||||
dir: &Path,
|
||||
out_canon: &Path,
|
||||
out: &mut Vec<PathBuf>,
|
||||
) -> Result<()> {
|
||||
for entry in fs::read_dir(dir)? {
|
||||
let entry = entry?;
|
||||
let p = entry.path();
|
||||
if p.is_dir() {
|
||||
let name = p.file_name().and_then(|s| s.to_str()).unwrap_or("");
|
||||
if name == "target"
|
||||
|| name == ".git"
|
||||
|| name == "node_modules"
|
||||
|| name == "docker"
|
||||
|| name == "data"
|
||||
|| name == ".cursor"
|
||||
{
|
||||
continue;
|
||||
}
|
||||
if let Ok(canon) = p.canonicalize() {
|
||||
if canon == *out_canon {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
collect_mq_md(root, &p, out_canon, out)?;
|
||||
} else if p
|
||||
.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.map(|s| s.ends_with(".mq.md"))
|
||||
.unwrap_or(false)
|
||||
{
|
||||
out.push(p);
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn collect_authored_knowledge(
|
||||
root: &Path,
|
||||
out_canon: &Path,
|
||||
out: &mut Vec<KnowledgeItem>,
|
||||
) -> Result<()> {
|
||||
walk_knowledge_md(root, root, out_canon, out)
|
||||
}
|
||||
|
||||
fn walk_knowledge_md(
|
||||
root: &Path,
|
||||
dir: &Path,
|
||||
out_canon: &Path,
|
||||
out: &mut Vec<KnowledgeItem>,
|
||||
) -> Result<()> {
|
||||
for entry in fs::read_dir(dir)? {
|
||||
let entry = entry?;
|
||||
let p = entry.path();
|
||||
if p.is_dir() {
|
||||
let name = p.file_name().and_then(|s| s.to_str()).unwrap_or("");
|
||||
if name == "target"
|
||||
|| name == ".git"
|
||||
|| name == ".marqdo"
|
||||
|| name == "docker"
|
||||
|| name == "data"
|
||||
|| name == ".cursor"
|
||||
{
|
||||
continue;
|
||||
}
|
||||
if let Ok(canon) = p.canonicalize() {
|
||||
if canon == *out_canon {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
walk_knowledge_md(root, &p, out_canon, out)?;
|
||||
continue;
|
||||
}
|
||||
let Some(name) = p.file_name().and_then(|s| s.to_str()) else {
|
||||
continue;
|
||||
};
|
||||
// Authored knowledge pages: .md with engineering type, not .mq.md (those go through inspect)
|
||||
if !name.ends_with(".md") || name.ends_with(".mq.md") {
|
||||
continue;
|
||||
}
|
||||
let source = fs::read_to_string(&p)?;
|
||||
let Some(ty) = extract_fm_field(&source, "type") else {
|
||||
continue;
|
||||
};
|
||||
let kind = KnowledgeKind::parse(&ty);
|
||||
match kind {
|
||||
KnowledgeKind::Decision
|
||||
| KnowledgeKind::Constraint
|
||||
| KnowledgeKind::Failure
|
||||
| KnowledgeKind::AntiPattern
|
||||
| KnowledgeKind::Pattern
|
||||
| KnowledgeKind::Migration
|
||||
| KnowledgeKind::Fact => {}
|
||||
_ => continue,
|
||||
}
|
||||
let rel = p
|
||||
.strip_prefix(root)
|
||||
.unwrap_or(&p)
|
||||
.to_string_lossy()
|
||||
.replace('\\', "/");
|
||||
out.push(knowledge_from_source(&source, &rel, kind));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn knowledge_from_source(source: &str, rel: &str, kind: KnowledgeKind) -> KnowledgeItem {
|
||||
let title = extract_fm_field(source, "title")
|
||||
.or_else(|| {
|
||||
source.lines().find_map(|l| {
|
||||
l.trim()
|
||||
.strip_prefix("# ")
|
||||
.map(|s| s.trim().to_string())
|
||||
})
|
||||
})
|
||||
.unwrap_or_else(|| rel.to_string());
|
||||
let id = extract_fm_field(source, "id").unwrap_or_else(|| {
|
||||
format!(
|
||||
"{}/{}",
|
||||
kind.subdir(),
|
||||
slugify(&title)
|
||||
)
|
||||
});
|
||||
let status = Lifecycle::parse(
|
||||
&extract_fm_field(source, "status").unwrap_or_else(|| "stable".into()),
|
||||
);
|
||||
let applies_to = extract_fm_list(source, "applies_to");
|
||||
let supersedes = extract_fm_list(source, "supersedes");
|
||||
let conflicts_with = extract_fm_list(source, "conflicts_with");
|
||||
let related = extract_fm_list(source, "related");
|
||||
let stale_after = extract_fm_field(source, "stale_after");
|
||||
let summary = first_paragraph(source);
|
||||
let mut evidence = Evidence::default();
|
||||
evidence.sources.push(rel.to_string());
|
||||
KnowledgeItem {
|
||||
id,
|
||||
kind,
|
||||
title,
|
||||
resource: rel.to_string(),
|
||||
status,
|
||||
body_summary: summary,
|
||||
applies_to,
|
||||
supersedes,
|
||||
conflicts_with,
|
||||
related,
|
||||
stale_after,
|
||||
evidence,
|
||||
confidence: Confidence {
|
||||
level: "high".into(),
|
||||
implementation: "authored".into(),
|
||||
tests: "unknown".into(),
|
||||
runtime: "unknown".into(),
|
||||
},
|
||||
source_text: Some(source.to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
fn inspect_source(
|
||||
abs: &Path,
|
||||
rel: &str,
|
||||
) -> Result<(ModuleInfo, Vec<SymbolInfo>, Vec<KnowledgeItem>)> {
|
||||
let source = fs::read_to_string(abs).with_context(|| format!("read {}", abs.display()))?;
|
||||
let imports = extract_frontmatter_imports(&source);
|
||||
let title = extract_fm_field(&source, "title")
|
||||
.unwrap_or_else(|| rel.trim_end_matches(".mq.md").to_string());
|
||||
let verified_by = extract_nested_by(&source, "verified");
|
||||
let sources = extract_fm_list(&source, "sources");
|
||||
let status = Lifecycle::parse(
|
||||
&extract_fm_field(&source, "status").unwrap_or_else(|| "stable".into()),
|
||||
);
|
||||
let responsibility = first_paragraph(&source);
|
||||
let responsibility = if responsibility.is_empty() {
|
||||
None
|
||||
} else {
|
||||
Some(responsibility)
|
||||
};
|
||||
|
||||
let mut knowledge = Vec::new();
|
||||
if let Some(ty) = extract_fm_field(&source, "type") {
|
||||
let kind = KnowledgeKind::parse(&ty);
|
||||
match kind {
|
||||
KnowledgeKind::Decision
|
||||
| KnowledgeKind::Constraint
|
||||
| KnowledgeKind::Failure
|
||||
| KnowledgeKind::AntiPattern
|
||||
| KnowledgeKind::Pattern
|
||||
| KnowledgeKind::Migration
|
||||
| KnowledgeKind::Fact => {
|
||||
knowledge.push(knowledge_from_source(&source, rel, kind));
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
let module_id = rel.trim_end_matches(".mq.md").to_string();
|
||||
let mut symbols = Vec::new();
|
||||
|
||||
match parse_source(&source) {
|
||||
Ok(module) => {
|
||||
for f in &module.functions {
|
||||
push_function_symbols(f, &module_id, rel, &source, &mut symbols);
|
||||
}
|
||||
}
|
||||
Err(_) => {
|
||||
for line in classify_source(&source) {
|
||||
if line.kind != LineKind::Code {
|
||||
continue;
|
||||
}
|
||||
let t = line.text.trim();
|
||||
if let Some(rest) = t.strip_prefix("# ") {
|
||||
if !rest.starts_with('#') {
|
||||
let name = rest
|
||||
.split('=')
|
||||
.next()
|
||||
.unwrap_or(rest)
|
||||
.trim()
|
||||
.to_string();
|
||||
let id = format!("{module_id}::{name}");
|
||||
let fp = fingerprint_text(&name, &[], &[], &[]);
|
||||
symbols.push(SymbolInfo {
|
||||
id,
|
||||
name,
|
||||
module: module_id.clone(),
|
||||
resource: rel.to_string(),
|
||||
kind: "fn".into(),
|
||||
visibility: "public".into(),
|
||||
params: Vec::new(),
|
||||
calls: Vec::new(),
|
||||
called_by: Vec::new(),
|
||||
tests: Vec::new(),
|
||||
fingerprint: fingerprint_hash(&fp),
|
||||
fingerprint_text: fp,
|
||||
use_when: None,
|
||||
do_not_use_when: None,
|
||||
related: Vec::new(),
|
||||
reuse: extract_fm_list(&source, "reuse"),
|
||||
capability: extract_fm_field(&source, "capability"),
|
||||
status: status.clone(),
|
||||
evidence: Evidence {
|
||||
sources: vec![rel.to_string()],
|
||||
..Evidence::default()
|
||||
},
|
||||
confidence: Confidence::default(),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let exports: Vec<String> = symbols.iter().map(|s| s.name.clone()).collect();
|
||||
let module = ModuleInfo {
|
||||
id: module_id,
|
||||
resource: rel.to_string(),
|
||||
title,
|
||||
imports,
|
||||
exports,
|
||||
responsibility,
|
||||
verified_by,
|
||||
sources,
|
||||
status,
|
||||
};
|
||||
Ok((module, symbols, knowledge))
|
||||
}
|
||||
|
||||
fn push_function_symbols(
|
||||
f: &Function,
|
||||
module_id: &str,
|
||||
rel: &str,
|
||||
source: &str,
|
||||
out: &mut Vec<SymbolInfo>,
|
||||
) {
|
||||
let name = f.name.clone();
|
||||
let id = format!("{module_id}::{name}");
|
||||
let params: Vec<String> = f.params.iter().map(|p| p.name.clone()).collect();
|
||||
let calls = collect_calls(f);
|
||||
let ops = ops_hint(f);
|
||||
let fp = fingerprint_text(&name, ¶ms, &calls, &ops);
|
||||
let kind = if f.is_object() {
|
||||
"object".to_string()
|
||||
} else {
|
||||
"fn".to_string()
|
||||
};
|
||||
// Prefer function-local sections if present in source near heading — fall back to file-level
|
||||
let use_when = extract_section(source, "Use when").or_else(|| prose_field(source, "Use when"));
|
||||
let do_not = extract_section(source, "Do not use when")
|
||||
.or_else(|| prose_field(source, "Do not use when"));
|
||||
let related = extract_fm_list(source, "related");
|
||||
let reuse = extract_fm_list(source, "reuse");
|
||||
let capability = extract_fm_field(source, "capability");
|
||||
let status = Lifecycle::parse(
|
||||
&extract_fm_field(source, "status").unwrap_or_else(|| "stable".into()),
|
||||
);
|
||||
|
||||
out.push(SymbolInfo {
|
||||
id,
|
||||
name,
|
||||
module: module_id.to_string(),
|
||||
resource: rel.to_string(),
|
||||
kind,
|
||||
visibility: "public".into(),
|
||||
params,
|
||||
calls,
|
||||
called_by: Vec::new(),
|
||||
tests: Vec::new(),
|
||||
fingerprint: fingerprint_hash(&fp),
|
||||
fingerprint_text: fp,
|
||||
use_when,
|
||||
do_not_use_when: do_not,
|
||||
related,
|
||||
reuse,
|
||||
capability,
|
||||
status,
|
||||
evidence: Evidence {
|
||||
sources: vec![rel.to_string()],
|
||||
..Evidence::default()
|
||||
},
|
||||
confidence: Confidence {
|
||||
level: "high".into(),
|
||||
implementation: "verified".into(),
|
||||
tests: "unknown".into(),
|
||||
runtime: "unknown".into(),
|
||||
},
|
||||
});
|
||||
|
||||
for child in &f.children {
|
||||
push_function_symbols(child, module_id, rel, source, out);
|
||||
}
|
||||
}
|
||||
|
||||
fn prose_field(source: &str, label: &str) -> Option<String> {
|
||||
let prefix = format!("{label}:");
|
||||
for line in source.lines() {
|
||||
let t = line.trim();
|
||||
if let Some(rest) = t.strip_prefix(&prefix) {
|
||||
let v = rest.trim();
|
||||
if !v.is_empty() {
|
||||
return Some(v.to_string());
|
||||
}
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn extract_frontmatter_imports(source: &str) -> Vec<String> {
|
||||
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
|
||||
let mut imports = Vec::new();
|
||||
let lines: Vec<&str> = source.lines().collect();
|
||||
if lines.first().map(|l| l.trim()) != Some("---") {
|
||||
return imports;
|
||||
}
|
||||
for line in lines.iter().skip(1) {
|
||||
let t = line.trim();
|
||||
if t == "---" {
|
||||
break;
|
||||
}
|
||||
if let Ok(Some(crate::parse::ImportLine::File(imp))) =
|
||||
crate::parse::parse_import_line(t)
|
||||
{
|
||||
imports.push(format!("import {}:{}", imp.bind, imp.path));
|
||||
} else if let Ok(Some(crate::parse::ImportLine::Member(u))) =
|
||||
crate::parse::parse_import_line(t)
|
||||
{
|
||||
imports.push(format!("import {}:{}", u.bind, u.path.join(".")));
|
||||
}
|
||||
}
|
||||
imports
|
||||
}
|
||||
|
||||
#[allow(dead_code)]
|
||||
pub fn stem_of(resource: &str) -> String {
|
||||
module_stem(resource)
|
||||
}
|
||||
@@ -0,0 +1,231 @@
|
||||
//! Hybrid knowledge find (lexical + symbol + capability + graph).
|
||||
|
||||
use crate::knowledge::fingerprint::text_similarity;
|
||||
use crate::knowledge::ir::{KnowledgeGraph, KnowledgeKind};
|
||||
use serde_json::{json, Value};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct FindHit {
|
||||
pub id: String,
|
||||
pub kind: String,
|
||||
pub title: String,
|
||||
pub score: f64,
|
||||
pub resource: Option<String>,
|
||||
pub snippet: String,
|
||||
}
|
||||
|
||||
pub fn find(graph: &KnowledgeGraph, query: &str, limit: usize) -> Vec<FindHit> {
|
||||
let q = query.trim();
|
||||
if q.is_empty() {
|
||||
return Vec::new();
|
||||
}
|
||||
let mut hits = Vec::new();
|
||||
|
||||
for c in &graph.capabilities {
|
||||
let material = format!(
|
||||
"{} {} {} {} {}",
|
||||
c.name,
|
||||
c.description,
|
||||
c.use_when.as_deref().unwrap_or(""),
|
||||
c.do_not_use_when.as_deref().unwrap_or(""),
|
||||
c.implemented_by.join(" ")
|
||||
);
|
||||
let mut score = text_similarity(q, &material);
|
||||
if c.name.to_ascii_lowercase().contains(&q.to_ascii_lowercase())
|
||||
|| q.to_ascii_lowercase()
|
||||
.split_whitespace()
|
||||
.any(|t| c.name.to_ascii_lowercase().contains(t))
|
||||
{
|
||||
score = (score + 0.35).min(1.0);
|
||||
}
|
||||
if score > 0.15 {
|
||||
hits.push(FindHit {
|
||||
id: format!("capability:{}", c.id),
|
||||
kind: "Capability".into(),
|
||||
title: c.name.clone(),
|
||||
score,
|
||||
resource: c
|
||||
.implemented_by
|
||||
.first()
|
||||
.and_then(|sid| graph.symbol_by_id(sid))
|
||||
.map(|s| s.resource.clone()),
|
||||
snippet: c.description.clone(),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
for s in &graph.symbols {
|
||||
if s.kind == "test" {
|
||||
continue;
|
||||
}
|
||||
let material = format!(
|
||||
"{} {} {} {} {}",
|
||||
s.name,
|
||||
s.fingerprint_text,
|
||||
s.use_when.as_deref().unwrap_or(""),
|
||||
s.module,
|
||||
s.calls.join(" ")
|
||||
);
|
||||
let mut score = text_similarity(q, &material);
|
||||
if s.name.to_ascii_lowercase().contains(&q.to_ascii_lowercase()) {
|
||||
score = (score + 0.4).min(1.0);
|
||||
}
|
||||
if score > 0.18 {
|
||||
hits.push(FindHit {
|
||||
id: format!("symbol:{}", s.id),
|
||||
kind: "Function".into(),
|
||||
title: s.name.clone(),
|
||||
score,
|
||||
resource: Some(s.resource.clone()),
|
||||
snippet: s.fingerprint_text.clone(),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
for k in &graph.knowledge {
|
||||
let material = format!("{} {} {}", k.title, k.body_summary, k.kind.as_str());
|
||||
let mut score = text_similarity(q, &material);
|
||||
if k.title.to_ascii_lowercase().contains(&q.to_ascii_lowercase()) {
|
||||
score = (score + 0.35).min(1.0);
|
||||
}
|
||||
// Boost engineering knowledge types for governance queries
|
||||
if matches!(
|
||||
k.kind,
|
||||
KnowledgeKind::Constraint
|
||||
| KnowledgeKind::Decision
|
||||
| KnowledgeKind::Failure
|
||||
| KnowledgeKind::AntiPattern
|
||||
) && score > 0.1
|
||||
{
|
||||
score = (score + 0.1).min(1.0);
|
||||
}
|
||||
if score > 0.15 {
|
||||
hits.push(FindHit {
|
||||
id: format!("knowledge:{}", k.id),
|
||||
kind: k.kind.as_str().to_string(),
|
||||
title: k.title.clone(),
|
||||
score,
|
||||
resource: Some(k.resource.clone()),
|
||||
snippet: k.body_summary.clone(),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Graph expansion: boost neighbors of top hits
|
||||
hits.sort_by(|a, b| b.score.partial_cmp(&a.score).unwrap_or(std::cmp::Ordering::Equal));
|
||||
let top_ids: Vec<String> = hits.iter().take(5).map(|h| h.id.clone()).collect();
|
||||
for tid in &top_ids {
|
||||
for e in graph.neighbors(tid, None) {
|
||||
let other = if e.from == *tid { &e.to } else { &e.from };
|
||||
if let Some(h) = hits.iter_mut().find(|h| h.id == *other) {
|
||||
h.score = (h.score + 0.05).min(1.0);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
hits.sort_by(|a, b| b.score.partial_cmp(&a.score).unwrap_or(std::cmp::Ordering::Equal));
|
||||
hits.truncate(limit);
|
||||
hits
|
||||
}
|
||||
|
||||
pub fn format_find_text(query: &str, hits: &[FindHit], graph: &KnowledgeGraph) -> String {
|
||||
let mut out = format!("Engineering First Information\n\nQuery: {query}\n\n");
|
||||
if hits.is_empty() {
|
||||
out.push_str("No matching capabilities, symbols, or knowledge.\n");
|
||||
return out;
|
||||
}
|
||||
|
||||
let caps: Vec<_> = hits.iter().filter(|h| h.kind == "Capability").collect();
|
||||
let impls: Vec<_> = hits.iter().filter(|h| h.kind == "Function").collect();
|
||||
let constraints: Vec<_> = hits.iter().filter(|h| h.kind == "Constraint").collect();
|
||||
let decisions: Vec<_> = hits.iter().filter(|h| h.kind == "Decision").collect();
|
||||
let failures: Vec<_> = hits
|
||||
.iter()
|
||||
.filter(|h| h.kind == "Failure" || h.kind == "AntiPattern")
|
||||
.collect();
|
||||
let related: Vec<_> = hits
|
||||
.iter()
|
||||
.filter(|h| {
|
||||
h.kind != "Capability"
|
||||
&& h.kind != "Function"
|
||||
&& h.kind != "Constraint"
|
||||
&& h.kind != "Decision"
|
||||
&& h.kind != "Failure"
|
||||
&& h.kind != "AntiPattern"
|
||||
})
|
||||
.collect();
|
||||
|
||||
if !caps.is_empty() {
|
||||
out.push_str("Capability\n");
|
||||
for h in &caps {
|
||||
out.push_str(&format!(" {} ({:.2})\n", h.title, h.score));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
if !impls.is_empty() {
|
||||
out.push_str("Implementation\n");
|
||||
for h in &impls {
|
||||
out.push_str(&format!(
|
||||
" {}\n",
|
||||
h.resource.as_deref().unwrap_or(&h.title)
|
||||
));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
if !constraints.is_empty() {
|
||||
out.push_str("Constraints\n");
|
||||
for h in &constraints {
|
||||
out.push_str(&format!(" {}\n", h.title));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
if !decisions.is_empty() {
|
||||
out.push_str("Decisions\n");
|
||||
for h in &decisions {
|
||||
out.push_str(&format!(" {}\n", h.title));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
if !failures.is_empty() {
|
||||
out.push_str("Failures\n");
|
||||
for h in &failures {
|
||||
out.push_str(&format!(" {}\n", h.title));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
if !related.is_empty() {
|
||||
out.push_str("Related\n");
|
||||
for h in &related {
|
||||
out.push_str(&format!(" {} ({})\n", h.title, h.kind));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
|
||||
// Graph-related capabilities for top cap
|
||||
if let Some(top) = caps.first() {
|
||||
let id = top.id.strip_prefix("capability:").unwrap_or(&top.id);
|
||||
if let Some(c) = graph.capability_by_id(id) {
|
||||
if !c.related.is_empty() {
|
||||
out.push_str("Related capabilities\n");
|
||||
for r in &c.related {
|
||||
out.push_str(&format!(" {r}\n"));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
pub fn find_json(query: &str, hits: &[FindHit]) -> Value {
|
||||
json!({
|
||||
"query": query,
|
||||
"hits": hits.iter().map(|h| json!({
|
||||
"id": h.id,
|
||||
"kind": h.kind,
|
||||
"title": h.title,
|
||||
"score": h.score,
|
||||
"resource": h.resource,
|
||||
"snippet": h.snippet,
|
||||
})).collect::<Vec<_>>(),
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,250 @@
|
||||
//! Symbol fingerprints + lexical similarity (char-bigram cosine).
|
||||
|
||||
use std::collections::HashMap;
|
||||
|
||||
use sha2::{Digest, Sha256};
|
||||
|
||||
use crate::ast::{Expr, Function, Stmt};
|
||||
use crate::knowledge::ir::SymbolInfo;
|
||||
|
||||
pub fn char_bigram_tf(text: &str) -> HashMap<String, f64> {
|
||||
let chars: Vec<char> = text.chars().filter(|c| !c.is_whitespace()).collect();
|
||||
let mut m = HashMap::new();
|
||||
if chars.is_empty() {
|
||||
return m;
|
||||
}
|
||||
if chars.len() == 1 {
|
||||
m.insert(chars[0].to_string(), 1.0);
|
||||
return m;
|
||||
}
|
||||
for w in chars.windows(2) {
|
||||
let key: String = w.iter().collect();
|
||||
*m.entry(key).or_insert(0.0) += 1.0;
|
||||
}
|
||||
m
|
||||
}
|
||||
|
||||
pub fn cosine_tf(a: &HashMap<String, f64>, b: &HashMap<String, f64>) -> f64 {
|
||||
let mut na = 0.0;
|
||||
let mut nb = 0.0;
|
||||
for v in a.values() {
|
||||
na += v * v;
|
||||
}
|
||||
for v in b.values() {
|
||||
nb += v * v;
|
||||
}
|
||||
if na == 0.0 || nb == 0.0 {
|
||||
return 0.0;
|
||||
}
|
||||
let mut dot = 0.0;
|
||||
for (k, va) in a {
|
||||
if let Some(vb) = b.get(k) {
|
||||
dot += va * vb;
|
||||
}
|
||||
}
|
||||
dot / (na.sqrt() * nb.sqrt())
|
||||
}
|
||||
|
||||
pub fn text_similarity(a: &str, b: &str) -> f64 {
|
||||
cosine_tf(&char_bigram_tf(a), &char_bigram_tf(b))
|
||||
}
|
||||
|
||||
pub fn tokenize_ident(name: &str) -> Vec<String> {
|
||||
let mut out = Vec::new();
|
||||
let mut cur = String::new();
|
||||
for c in name.chars() {
|
||||
if c == '_' || c == '-' || c == '.' || c == '/' {
|
||||
if !cur.is_empty() {
|
||||
out.push(cur.to_ascii_lowercase());
|
||||
cur.clear();
|
||||
}
|
||||
} else if c.is_uppercase() && !cur.is_empty() && cur.chars().last().is_some_and(|x| x.is_lowercase())
|
||||
{
|
||||
out.push(cur.to_ascii_lowercase());
|
||||
cur.clear();
|
||||
cur.push(c);
|
||||
} else {
|
||||
cur.push(c);
|
||||
}
|
||||
}
|
||||
if !cur.is_empty() {
|
||||
out.push(cur.to_ascii_lowercase());
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn collect_calls_from_expr(expr: &Expr, out: &mut Vec<String>) {
|
||||
match expr {
|
||||
Expr::Call(c) => {
|
||||
let name = if let Some(path) = &c.path {
|
||||
path.join(".")
|
||||
} else if let Some(recv) = &c.receiver {
|
||||
format!("{recv}.{}", c.callee)
|
||||
} else {
|
||||
c.callee.clone()
|
||||
};
|
||||
out.push(name);
|
||||
for a in &c.args {
|
||||
match a {
|
||||
crate::ast::Arg::Positional(e) | crate::ast::Arg::Named { value: e, .. } => {
|
||||
collect_calls_from_expr(e, out);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Expr::Unary { expr, .. } => collect_calls_from_expr(expr, out),
|
||||
Expr::Binary { left, right, .. } => {
|
||||
collect_calls_from_expr(left, out);
|
||||
collect_calls_from_expr(right, out);
|
||||
}
|
||||
Expr::List(xs) => {
|
||||
for e in xs {
|
||||
collect_calls_from_expr(e, out);
|
||||
}
|
||||
}
|
||||
Expr::Map(pairs) => {
|
||||
for (_, e) in pairs {
|
||||
collect_calls_from_expr(e, out);
|
||||
}
|
||||
}
|
||||
Expr::Index { base, .. } => collect_calls_from_expr(base, out),
|
||||
Expr::Interp(parts) => {
|
||||
for p in parts {
|
||||
if let crate::ast::InterpPart::Index { .. } = p {
|
||||
// no call
|
||||
}
|
||||
}
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
fn collect_calls_from_stmts(stmts: &[Stmt], out: &mut Vec<String>) {
|
||||
for s in stmts {
|
||||
match s {
|
||||
Stmt::Assign { value, .. } | Stmt::Return { value, .. } | Stmt::Expr { value, .. } => {
|
||||
collect_calls_from_expr(value, out);
|
||||
}
|
||||
Stmt::Call { call, .. } => {
|
||||
let name = if let Some(path) = &call.path {
|
||||
path.join(".")
|
||||
} else if let Some(recv) = &call.receiver {
|
||||
format!("{recv}.{}", call.callee)
|
||||
} else {
|
||||
call.callee.clone()
|
||||
};
|
||||
out.push(name);
|
||||
for a in &call.args {
|
||||
match a {
|
||||
crate::ast::Arg::Positional(e) | crate::ast::Arg::Named { value: e, .. } => {
|
||||
collect_calls_from_expr(e, out);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Stmt::Branch { arms, .. } => {
|
||||
for arm in arms {
|
||||
if let Some(c) = &arm.condition {
|
||||
collect_calls_from_expr(c, out);
|
||||
}
|
||||
collect_calls_from_stmts(&arm.body, out);
|
||||
}
|
||||
}
|
||||
Stmt::While {
|
||||
condition, body, ..
|
||||
} => {
|
||||
collect_calls_from_expr(condition, out);
|
||||
collect_calls_from_stmts(body, out);
|
||||
}
|
||||
Stmt::ForEach { body, .. } => collect_calls_from_stmts(body, out),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
pub fn collect_calls(f: &Function) -> Vec<String> {
|
||||
let mut out = Vec::new();
|
||||
collect_calls_from_stmts(&f.body, &mut out);
|
||||
for child in &f.children {
|
||||
out.extend(collect_calls(child));
|
||||
}
|
||||
out.sort();
|
||||
out.dedup();
|
||||
out
|
||||
}
|
||||
|
||||
pub fn ops_hint(f: &Function) -> Vec<String> {
|
||||
let mut ops = Vec::new();
|
||||
let name = f.name.to_ascii_lowercase();
|
||||
for verb in [
|
||||
"parse", "merge", "validate", "normalize", "resolve", "load", "save", "read", "write",
|
||||
"encode", "decode", "verify", "auth", "cache", "retry", "serialize", "render", "query",
|
||||
"create", "update", "delete", "check", "format", "convert",
|
||||
] {
|
||||
if name.contains(verb) {
|
||||
ops.push(verb.to_string());
|
||||
}
|
||||
}
|
||||
for c in collect_calls(f) {
|
||||
let low = c.to_ascii_lowercase();
|
||||
for verb in ["parse", "merge", "validate", "json", "http", "hash", "auth"] {
|
||||
if low.contains(verb) && !ops.iter().any(|o| o == verb) {
|
||||
ops.push(verb.to_string());
|
||||
}
|
||||
}
|
||||
}
|
||||
// Body-size / structure hints keep near-duplicates discoverable
|
||||
let body_n = f.body.len();
|
||||
if body_n > 0 {
|
||||
ops.push(format!("stmts:{body_n}"));
|
||||
}
|
||||
if !f.params.is_empty() {
|
||||
ops.push(format!("arity:{}", f.params.len()));
|
||||
}
|
||||
ops
|
||||
}
|
||||
|
||||
pub fn fingerprint_text(name: &str, params: &[String], calls: &[String], ops: &[String]) -> String {
|
||||
let mut parts = Vec::new();
|
||||
parts.push(format!("name:{}", tokenize_ident(name).join("_")));
|
||||
if !params.is_empty() {
|
||||
parts.push(format!("params:{}", params.join(",")));
|
||||
}
|
||||
if !calls.is_empty() {
|
||||
let mut c = calls.to_vec();
|
||||
c.sort();
|
||||
parts.push(format!("calls:{}", c.join(",")));
|
||||
}
|
||||
if !ops.is_empty() {
|
||||
parts.push(format!("ops:{}", ops.join(",")));
|
||||
}
|
||||
parts.join("|")
|
||||
}
|
||||
|
||||
pub fn fingerprint_hash(text: &str) -> String {
|
||||
let mut h = Sha256::new();
|
||||
h.update(text.as_bytes());
|
||||
format!("{:x}", h.finalize())[..16].to_string()
|
||||
}
|
||||
|
||||
pub fn symbol_similarity(a: &SymbolInfo, b: &SymbolInfo) -> f64 {
|
||||
let mut score = text_similarity(&a.fingerprint_text, &b.fingerprint_text);
|
||||
let name_sim = text_similarity(&a.name, &b.name);
|
||||
// Token overlap on snake_case names (resolve_config vs normalize_settings share little;
|
||||
// merge_config vs merge_settings share "merge")
|
||||
let ta = tokenize_ident(&a.name);
|
||||
let tb = tokenize_ident(&b.name);
|
||||
let mut overlap = 0.0;
|
||||
if !ta.is_empty() && !tb.is_empty() {
|
||||
let shared = ta.iter().filter(|t| tb.contains(t)).count() as f64;
|
||||
overlap = shared / (ta.len().max(tb.len()) as f64);
|
||||
}
|
||||
let param_bonus = if !a.params.is_empty() && a.params == b.params {
|
||||
0.25
|
||||
} else if a.params.len() == b.params.len() && !a.params.is_empty() {
|
||||
0.1
|
||||
} else {
|
||||
0.0
|
||||
};
|
||||
score = (score * 0.25) + (name_sim * 0.15) + (overlap * 0.45) + param_bonus;
|
||||
score.min(1.0)
|
||||
}
|
||||
@@ -0,0 +1,170 @@
|
||||
//! Knowledge graph edge construction.
|
||||
|
||||
use crate::knowledge::ir::{
|
||||
CapabilityInfo, Edge, EdgeKind, KnowledgeItem, KnowledgeKind, ModuleInfo, SymbolInfo,
|
||||
};
|
||||
|
||||
pub fn build_edges(
|
||||
modules: &[ModuleInfo],
|
||||
symbols: &[SymbolInfo],
|
||||
capabilities: &[CapabilityInfo],
|
||||
knowledge: &[KnowledgeItem],
|
||||
) -> Vec<Edge> {
|
||||
let mut edges = Vec::new();
|
||||
|
||||
// Module depends_on
|
||||
for m in modules {
|
||||
for imp in &m.imports {
|
||||
let path = imp
|
||||
.split(':')
|
||||
.nth(1)
|
||||
.unwrap_or(imp)
|
||||
.trim()
|
||||
.to_string();
|
||||
if let Some(dep) = modules.iter().find(|o| {
|
||||
o.resource == path
|
||||
|| o.resource.ends_with(&path)
|
||||
|| o.resource.ends_with(&format!("/{path}"))
|
||||
|| o.id == path.trim_end_matches(".mq.md")
|
||||
}) {
|
||||
edges.push(Edge {
|
||||
from: format!("module:{}", m.id),
|
||||
to: format!("module:{}", dep.id),
|
||||
kind: EdgeKind::DependsOn,
|
||||
note: Some(imp.clone()),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Symbol uses (calls)
|
||||
for s in symbols {
|
||||
for c in &s.calls {
|
||||
let short = c.rsplit('.').next().unwrap_or(c);
|
||||
if let Some(target) = symbols.iter().find(|t| t.name == short || t.name == *c || t.id == *c)
|
||||
{
|
||||
edges.push(Edge {
|
||||
from: format!("symbol:{}", s.id),
|
||||
to: format!("symbol:{}", target.id),
|
||||
kind: EdgeKind::Uses,
|
||||
note: None,
|
||||
});
|
||||
}
|
||||
}
|
||||
for t in &s.tests {
|
||||
edges.push(Edge {
|
||||
from: format!("symbol:{}", s.id),
|
||||
to: format!("symbol:{t}"),
|
||||
kind: EdgeKind::TestedBy,
|
||||
note: None,
|
||||
});
|
||||
}
|
||||
for r in &s.related {
|
||||
edges.push(Edge {
|
||||
from: format!("symbol:{}", s.id),
|
||||
to: r.clone(),
|
||||
kind: EdgeKind::RelatedTo,
|
||||
note: None,
|
||||
});
|
||||
}
|
||||
for r in &s.reuse {
|
||||
edges.push(Edge {
|
||||
from: format!("symbol:{}", s.id),
|
||||
to: r.clone(),
|
||||
kind: EdgeKind::DerivedFrom,
|
||||
note: Some("reuse".into()),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Capability implements
|
||||
for c in capabilities {
|
||||
for sid in &c.implemented_by {
|
||||
edges.push(Edge {
|
||||
from: format!("capability:{}", c.id),
|
||||
to: format!("symbol:{sid}"),
|
||||
kind: EdgeKind::Implements,
|
||||
note: None,
|
||||
});
|
||||
}
|
||||
for r in &c.related {
|
||||
edges.push(Edge {
|
||||
from: format!("capability:{}", c.id),
|
||||
to: r.clone(),
|
||||
kind: EdgeKind::RelatedTo,
|
||||
note: None,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Knowledge edges
|
||||
for k in knowledge {
|
||||
let kid = format!("knowledge:{}", k.id);
|
||||
for a in &k.applies_to {
|
||||
let kind = match k.kind {
|
||||
KnowledgeKind::Constraint => EdgeKind::ConstrainedBy,
|
||||
KnowledgeKind::Decision => EdgeKind::DecidedBy,
|
||||
KnowledgeKind::Failure | KnowledgeKind::AntiPattern => EdgeKind::FailedBy,
|
||||
_ => EdgeKind::DocumentedBy,
|
||||
};
|
||||
// Edge direction: subject --constrained_by--> knowledge (from subject to knowledge)
|
||||
// Or capability constrained_by knowledge: from applies_to to knowledge
|
||||
edges.push(Edge {
|
||||
from: normalize_ref(a, capabilities, symbols),
|
||||
to: kid.clone(),
|
||||
kind,
|
||||
note: Some(k.title.clone()),
|
||||
});
|
||||
}
|
||||
for s in &k.supersedes {
|
||||
edges.push(Edge {
|
||||
from: kid.clone(),
|
||||
to: format!("knowledge:{s}"),
|
||||
kind: EdgeKind::Supersedes,
|
||||
note: None,
|
||||
});
|
||||
}
|
||||
for s in &k.conflicts_with {
|
||||
edges.push(Edge {
|
||||
from: kid.clone(),
|
||||
to: format!("knowledge:{s}"),
|
||||
kind: EdgeKind::ConflictsWith,
|
||||
note: None,
|
||||
});
|
||||
}
|
||||
for r in &k.related {
|
||||
edges.push(Edge {
|
||||
from: kid.clone(),
|
||||
to: normalize_ref(r, capabilities, symbols),
|
||||
kind: EdgeKind::RelatedTo,
|
||||
note: None,
|
||||
});
|
||||
}
|
||||
if k.status == crate::knowledge::ir::Lifecycle::Deprecated {
|
||||
// no target
|
||||
}
|
||||
}
|
||||
|
||||
edges.sort_by(|a, b| {
|
||||
(&a.from, a.kind.as_str(), &a.to).cmp(&(&b.from, b.kind.as_str(), &b.to))
|
||||
});
|
||||
edges.dedup_by(|a, b| a.from == b.from && a.to == b.to && a.kind == b.kind);
|
||||
edges
|
||||
}
|
||||
|
||||
fn normalize_ref(r: &str, capabilities: &[CapabilityInfo], symbols: &[SymbolInfo]) -> String {
|
||||
if r.starts_with("capability:")
|
||||
|| r.starts_with("symbol:")
|
||||
|| r.starts_with("module:")
|
||||
|| r.starts_with("knowledge:")
|
||||
{
|
||||
return r.to_string();
|
||||
}
|
||||
if let Some(c) = capabilities.iter().find(|c| c.id == r || c.name == r) {
|
||||
return format!("capability:{}", c.id);
|
||||
}
|
||||
if let Some(s) = symbols.iter().find(|s| s.id == r || s.name == r) {
|
||||
return format!("symbol:{}", s.id);
|
||||
}
|
||||
r.to_string()
|
||||
}
|
||||
@@ -0,0 +1,179 @@
|
||||
//! Knowledge impact analysis for changed paths.
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
use crate::knowledge::ir::{EdgeKind, KnowledgeGraph};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ImpactReport {
|
||||
pub changed: Vec<String>,
|
||||
pub capabilities: Vec<String>,
|
||||
pub decisions: Vec<String>,
|
||||
pub constraints: Vec<String>,
|
||||
pub tests: Vec<String>,
|
||||
pub documentation: Vec<String>,
|
||||
pub stale_knowledge: Vec<String>,
|
||||
pub symbols: Vec<String>,
|
||||
}
|
||||
|
||||
pub fn impact(graph: &KnowledgeGraph, paths: &[String]) -> ImpactReport {
|
||||
let mut report = ImpactReport {
|
||||
changed: paths.to_vec(),
|
||||
capabilities: Vec::new(),
|
||||
decisions: Vec::new(),
|
||||
constraints: Vec::new(),
|
||||
tests: Vec::new(),
|
||||
documentation: Vec::new(),
|
||||
stale_knowledge: Vec::new(),
|
||||
symbols: Vec::new(),
|
||||
};
|
||||
|
||||
for path in paths {
|
||||
let norm = path.replace('\\', "/");
|
||||
for s in &graph.symbols {
|
||||
if s.resource == norm
|
||||
|| s.resource.ends_with(&norm)
|
||||
|| norm.ends_with(&s.resource)
|
||||
{
|
||||
report.symbols.push(s.id.clone());
|
||||
if let Some(ref cap) = s.capability {
|
||||
report.capabilities.push(cap.clone());
|
||||
}
|
||||
for c in &graph.capabilities {
|
||||
if c.implemented_by.iter().any(|id| id == &s.id) {
|
||||
report.capabilities.push(c.name.clone());
|
||||
}
|
||||
}
|
||||
report.tests.extend(s.tests.clone());
|
||||
}
|
||||
}
|
||||
for m in &graph.modules {
|
||||
if m.resource == norm || m.resource.ends_with(&norm) || norm.ends_with(&m.resource)
|
||||
{
|
||||
for s in graph.symbols.iter().filter(|s| s.module == m.id) {
|
||||
report.symbols.push(s.id.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
for k in &graph.knowledge {
|
||||
if k.resource == norm || k.resource.ends_with(&norm) {
|
||||
match k.kind {
|
||||
crate::knowledge::ir::KnowledgeKind::Decision => {
|
||||
report.decisions.push(k.id.clone())
|
||||
}
|
||||
crate::knowledge::ir::KnowledgeKind::Constraint => {
|
||||
report.constraints.push(k.id.clone())
|
||||
}
|
||||
_ => report.documentation.push(k.resource.clone()),
|
||||
}
|
||||
}
|
||||
// applies_to matches changed symbols/modules
|
||||
for a in &k.applies_to {
|
||||
if report.symbols.iter().any(|s| s.contains(a) || a.contains(s))
|
||||
|| report.capabilities.iter().any(|c| c == a || a.contains(c))
|
||||
{
|
||||
report.stale_knowledge.push(k.id.clone());
|
||||
match k.kind {
|
||||
crate::knowledge::ir::KnowledgeKind::Decision => {
|
||||
report.decisions.push(k.id.clone())
|
||||
}
|
||||
crate::knowledge::ir::KnowledgeKind::Constraint => {
|
||||
report.constraints.push(k.id.clone())
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Graph walk: from changed symbols follow edges
|
||||
let seed: Vec<String> = report
|
||||
.symbols
|
||||
.iter()
|
||||
.map(|s| format!("symbol:{s}"))
|
||||
.collect();
|
||||
for sid in &seed {
|
||||
for e in graph.neighbors(sid, None) {
|
||||
let other = if &e.from == sid { &e.to } else { &e.from };
|
||||
if other.starts_with("capability:") {
|
||||
report
|
||||
.capabilities
|
||||
.push(other.trim_start_matches("capability:").to_string());
|
||||
} else if other.starts_with("knowledge:") {
|
||||
report
|
||||
.stale_knowledge
|
||||
.push(other.trim_start_matches("knowledge:").to_string());
|
||||
} else if e.kind == EdgeKind::TestedBy {
|
||||
report.tests.push(other.clone());
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
report.capabilities.sort();
|
||||
report.capabilities.dedup();
|
||||
report.decisions.sort();
|
||||
report.decisions.dedup();
|
||||
report.constraints.sort();
|
||||
report.constraints.dedup();
|
||||
report.tests.sort();
|
||||
report.tests.dedup();
|
||||
report.documentation.sort();
|
||||
report.documentation.dedup();
|
||||
report.stale_knowledge.sort();
|
||||
report.stale_knowledge.dedup();
|
||||
report.symbols.sort();
|
||||
report.symbols.dedup();
|
||||
report
|
||||
}
|
||||
|
||||
pub fn format_impact_text(r: &ImpactReport) -> String {
|
||||
let mut out = String::new();
|
||||
out.push_str("Changed:\n");
|
||||
for c in &r.changed {
|
||||
out.push_str(&format!(" {c}\n"));
|
||||
}
|
||||
out.push_str("\nAffected capabilities:\n");
|
||||
for c in &r.capabilities {
|
||||
out.push_str(&format!(" {c}\n"));
|
||||
}
|
||||
if r.capabilities.is_empty() {
|
||||
out.push_str(" (none)\n");
|
||||
}
|
||||
out.push_str("\nAffected decisions:\n");
|
||||
for d in &r.decisions {
|
||||
out.push_str(&format!(" {d}\n"));
|
||||
}
|
||||
if r.decisions.is_empty() {
|
||||
out.push_str(" (none)\n");
|
||||
}
|
||||
out.push_str("\nAffected constraints:\n");
|
||||
for c in &r.constraints {
|
||||
out.push_str(&format!(" {c}\n"));
|
||||
}
|
||||
out.push_str("\nAffected tests:\n");
|
||||
for t in &r.tests {
|
||||
out.push_str(&format!(" {t}\n"));
|
||||
}
|
||||
out.push_str("\nPotential stale knowledge:\n");
|
||||
for s in &r.stale_knowledge {
|
||||
out.push_str(&format!(" {s}\n"));
|
||||
}
|
||||
if r.stale_knowledge.is_empty() {
|
||||
out.push_str(" (none)\n");
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
pub fn impact_json(r: &ImpactReport) -> Value {
|
||||
json!({
|
||||
"changed": r.changed,
|
||||
"capabilities": r.capabilities,
|
||||
"decisions": r.decisions,
|
||||
"constraints": r.constraints,
|
||||
"tests": r.tests,
|
||||
"documentation": r.documentation,
|
||||
"stale_knowledge": r.stale_knowledge,
|
||||
"symbols": r.symbols,
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,471 @@
|
||||
//! Engineering Knowledge IR (L0–L4) — projections of `.mq.md`, not a second source of truth.
|
||||
|
||||
use serde_json::{json, Value};
|
||||
use std::collections::BTreeMap;
|
||||
|
||||
/// Lifecycle: draft → verified → stable → deprecated → superseded.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum Lifecycle {
|
||||
Draft,
|
||||
Verified,
|
||||
Stable,
|
||||
Deprecated,
|
||||
Superseded,
|
||||
}
|
||||
|
||||
impl Lifecycle {
|
||||
pub fn as_str(&self) -> &'static str {
|
||||
match self {
|
||||
Self::Draft => "draft",
|
||||
Self::Verified => "verified",
|
||||
Self::Stable => "stable",
|
||||
Self::Deprecated => "deprecated",
|
||||
Self::Superseded => "superseded",
|
||||
}
|
||||
}
|
||||
|
||||
pub fn parse(s: &str) -> Self {
|
||||
match s.trim().to_ascii_lowercase().as_str() {
|
||||
"verified" => Self::Verified,
|
||||
"stable" => Self::Stable,
|
||||
"deprecated" => Self::Deprecated,
|
||||
"superseded" => Self::Superseded,
|
||||
_ => Self::Draft,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct Evidence {
|
||||
pub sources: Vec<String>,
|
||||
pub tests: Vec<String>,
|
||||
pub executions: Vec<String>,
|
||||
pub commits: Vec<String>,
|
||||
}
|
||||
|
||||
impl Evidence {
|
||||
pub fn to_json(&self) -> Value {
|
||||
json!({
|
||||
"sources": self.sources,
|
||||
"tests": self.tests,
|
||||
"executions": self.executions,
|
||||
"commits": self.commits,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
/// Graded confidence with explanation (not a bare float).
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Confidence {
|
||||
pub level: String, // high | medium | low
|
||||
pub implementation: String,
|
||||
pub tests: String,
|
||||
pub runtime: String,
|
||||
}
|
||||
|
||||
impl Default for Confidence {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
level: "medium".into(),
|
||||
implementation: "extracted".into(),
|
||||
tests: "unknown".into(),
|
||||
runtime: "unknown".into(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Confidence {
|
||||
pub fn to_json(&self) -> Value {
|
||||
json!({
|
||||
"level": self.level,
|
||||
"evidence": {
|
||||
"implementation": self.implementation,
|
||||
"tests": self.tests,
|
||||
"runtime": self.runtime,
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct RepositoryInfo {
|
||||
pub title: String,
|
||||
pub root: String,
|
||||
pub languages: Vec<String>,
|
||||
pub module_count: usize,
|
||||
pub symbol_count: usize,
|
||||
pub capability_count: usize,
|
||||
pub knowledge_count: usize,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ModuleInfo {
|
||||
pub id: String,
|
||||
pub resource: String,
|
||||
pub title: String,
|
||||
pub imports: Vec<String>,
|
||||
pub exports: Vec<String>,
|
||||
pub responsibility: Option<String>,
|
||||
pub verified_by: Option<String>,
|
||||
pub sources: Vec<String>,
|
||||
pub status: Lifecycle,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct SymbolInfo {
|
||||
pub id: String,
|
||||
pub name: String,
|
||||
pub module: String,
|
||||
pub resource: String,
|
||||
pub kind: String, // fn | object | type
|
||||
pub visibility: String,
|
||||
pub params: Vec<String>,
|
||||
pub calls: Vec<String>,
|
||||
pub called_by: Vec<String>,
|
||||
pub tests: Vec<String>,
|
||||
pub fingerprint: String,
|
||||
pub fingerprint_text: String,
|
||||
pub use_when: Option<String>,
|
||||
pub do_not_use_when: Option<String>,
|
||||
pub related: Vec<String>,
|
||||
pub reuse: Vec<String>,
|
||||
pub capability: Option<String>,
|
||||
pub status: Lifecycle,
|
||||
pub evidence: Evidence,
|
||||
pub confidence: Confidence,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CapabilityInfo {
|
||||
pub id: String,
|
||||
pub name: String,
|
||||
pub description: String,
|
||||
pub implemented_by: Vec<String>,
|
||||
pub modules: Vec<String>,
|
||||
pub status: Lifecycle,
|
||||
pub use_when: Option<String>,
|
||||
pub do_not_use_when: Option<String>,
|
||||
pub related: Vec<String>,
|
||||
pub evidence: Evidence,
|
||||
pub confidence: Confidence,
|
||||
pub introduced: Option<String>,
|
||||
pub verified: Option<String>,
|
||||
pub last_used: Option<String>,
|
||||
pub last_tested: Option<String>,
|
||||
pub possible_duplicates: Vec<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum KnowledgeKind {
|
||||
Fact,
|
||||
Decision,
|
||||
Constraint,
|
||||
Pattern,
|
||||
AntiPattern,
|
||||
Failure,
|
||||
Migration,
|
||||
Function,
|
||||
Capability,
|
||||
Other(String),
|
||||
}
|
||||
|
||||
impl KnowledgeKind {
|
||||
pub fn as_str(&self) -> &str {
|
||||
match self {
|
||||
Self::Fact => "Fact",
|
||||
Self::Decision => "Decision",
|
||||
Self::Constraint => "Constraint",
|
||||
Self::Pattern => "Pattern",
|
||||
Self::AntiPattern => "AntiPattern",
|
||||
Self::Failure => "Failure",
|
||||
Self::Migration => "Migration",
|
||||
Self::Function => "Function",
|
||||
Self::Capability => "Capability",
|
||||
Self::Other(s) => s.as_str(),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn parse(s: &str) -> Self {
|
||||
let t = s.trim();
|
||||
let bare = t.strip_prefix("Marqdo ").unwrap_or(t);
|
||||
match bare {
|
||||
"Fact" => Self::Fact,
|
||||
"Decision" | "ADR" => Self::Decision,
|
||||
"Constraint" => Self::Constraint,
|
||||
"Pattern" => Self::Pattern,
|
||||
"AntiPattern" | "Anti-Pattern" => Self::AntiPattern,
|
||||
"Failure" => Self::Failure,
|
||||
"Migration" => Self::Migration,
|
||||
"Function" => Self::Function,
|
||||
"Capability" => Self::Capability,
|
||||
other => Self::Other(other.to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn subdir(&self) -> &'static str {
|
||||
match self {
|
||||
Self::Fact => "facts",
|
||||
Self::Decision => "decisions",
|
||||
Self::Constraint => "constraints",
|
||||
Self::Pattern | Self::AntiPattern => "patterns",
|
||||
Self::Failure => "failures",
|
||||
Self::Migration => "migrations",
|
||||
Self::Function | Self::Capability | Self::Other(_) => "facts",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct KnowledgeItem {
|
||||
pub id: String,
|
||||
pub kind: KnowledgeKind,
|
||||
pub title: String,
|
||||
pub resource: String,
|
||||
pub status: Lifecycle,
|
||||
pub body_summary: String,
|
||||
pub applies_to: Vec<String>,
|
||||
pub supersedes: Vec<String>,
|
||||
pub conflicts_with: Vec<String>,
|
||||
pub related: Vec<String>,
|
||||
pub stale_after: Option<String>,
|
||||
pub evidence: Evidence,
|
||||
pub confidence: Confidence,
|
||||
/// Raw source text (copied into knowledge/ when authored under src).
|
||||
pub source_text: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
|
||||
pub enum EdgeKind {
|
||||
Implements,
|
||||
Uses,
|
||||
DependsOn,
|
||||
TestedBy,
|
||||
DocumentedBy,
|
||||
ConstrainedBy,
|
||||
DecidedBy,
|
||||
Supersedes,
|
||||
ConflictsWith,
|
||||
DeprecatedBy,
|
||||
DerivedFrom,
|
||||
FailedBy,
|
||||
RelatedTo,
|
||||
}
|
||||
|
||||
impl EdgeKind {
|
||||
pub fn as_str(&self) -> &'static str {
|
||||
match self {
|
||||
Self::Implements => "implements",
|
||||
Self::Uses => "uses",
|
||||
Self::DependsOn => "depends_on",
|
||||
Self::TestedBy => "tested_by",
|
||||
Self::DocumentedBy => "documented_by",
|
||||
Self::ConstrainedBy => "constrained_by",
|
||||
Self::DecidedBy => "decided_by",
|
||||
Self::Supersedes => "supersedes",
|
||||
Self::ConflictsWith => "conflicts_with",
|
||||
Self::DeprecatedBy => "deprecated_by",
|
||||
Self::DerivedFrom => "derived_from",
|
||||
Self::FailedBy => "failed_by",
|
||||
Self::RelatedTo => "related_to",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Edge {
|
||||
pub from: String,
|
||||
pub to: String,
|
||||
pub kind: EdgeKind,
|
||||
pub note: Option<String>,
|
||||
}
|
||||
|
||||
impl Edge {
|
||||
pub fn to_json(&self) -> Value {
|
||||
let mut m = json!({
|
||||
"from": self.from,
|
||||
"to": self.to,
|
||||
"kind": self.kind.as_str(),
|
||||
});
|
||||
if let Some(ref n) = self.note {
|
||||
m["note"] = json!(n);
|
||||
}
|
||||
m
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum ReuseDecision {
|
||||
Reuse,
|
||||
Adapt,
|
||||
Create,
|
||||
}
|
||||
|
||||
impl ReuseDecision {
|
||||
pub fn as_str(&self) -> &'static str {
|
||||
match self {
|
||||
Self::Reuse => "REUSE",
|
||||
Self::Adapt => "ADAPT",
|
||||
Self::Create => "CREATE",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ReuseCandidate {
|
||||
pub id: String,
|
||||
pub kind: String,
|
||||
pub title: String,
|
||||
pub score: f64,
|
||||
pub resource: Option<String>,
|
||||
pub reason: Vec<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ReuseResult {
|
||||
pub decision: ReuseDecision,
|
||||
pub confidence: f64,
|
||||
pub capability: Option<String>,
|
||||
pub symbol: Option<String>,
|
||||
pub source: Option<String>,
|
||||
pub reason: Vec<String>,
|
||||
pub candidates: Vec<ReuseCandidate>,
|
||||
pub constraints: Vec<String>,
|
||||
pub decisions: Vec<String>,
|
||||
pub failures: Vec<String>,
|
||||
pub create_allowed: bool,
|
||||
pub recommended: Vec<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct KnowledgeGraph {
|
||||
pub repository: RepositoryInfo,
|
||||
pub modules: Vec<ModuleInfo>,
|
||||
pub symbols: Vec<SymbolInfo>,
|
||||
pub capabilities: Vec<CapabilityInfo>,
|
||||
pub knowledge: Vec<KnowledgeItem>,
|
||||
pub edges: Vec<Edge>,
|
||||
pub generated_by: String,
|
||||
}
|
||||
|
||||
impl KnowledgeGraph {
|
||||
pub fn symbol_by_id(&self, id: &str) -> Option<&SymbolInfo> {
|
||||
self.symbols.iter().find(|s| s.id == id || s.name == id)
|
||||
}
|
||||
|
||||
pub fn capability_by_id(&self, id: &str) -> Option<&CapabilityInfo> {
|
||||
self.capabilities
|
||||
.iter()
|
||||
.find(|c| c.id == id || c.name == id)
|
||||
}
|
||||
|
||||
pub fn neighbors(&self, id: &str, kind: Option<EdgeKind>) -> Vec<&Edge> {
|
||||
self.edges
|
||||
.iter()
|
||||
.filter(|e| {
|
||||
(e.from == id || e.to == id)
|
||||
&& kind.as_ref().map(|k| &e.kind == k).unwrap_or(true)
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
pub fn to_graph_json(&self) -> Value {
|
||||
let mut nodes = Vec::new();
|
||||
nodes.push(json!({
|
||||
"id": "repo",
|
||||
"kind": "repository",
|
||||
"title": self.repository.title,
|
||||
}));
|
||||
for m in &self.modules {
|
||||
nodes.push(json!({
|
||||
"id": format!("module:{}", m.id),
|
||||
"kind": "module",
|
||||
"title": m.title,
|
||||
"resource": m.resource,
|
||||
}));
|
||||
}
|
||||
for s in &self.symbols {
|
||||
nodes.push(json!({
|
||||
"id": format!("symbol:{}", s.id),
|
||||
"kind": "symbol",
|
||||
"title": s.name,
|
||||
"resource": s.resource,
|
||||
"fingerprint": s.fingerprint,
|
||||
}));
|
||||
}
|
||||
for c in &self.capabilities {
|
||||
nodes.push(json!({
|
||||
"id": format!("capability:{}", c.id),
|
||||
"kind": "capability",
|
||||
"title": c.name,
|
||||
"status": c.status.as_str(),
|
||||
}));
|
||||
}
|
||||
for k in &self.knowledge {
|
||||
nodes.push(json!({
|
||||
"id": format!("knowledge:{}", k.id),
|
||||
"kind": k.kind.as_str(),
|
||||
"title": k.title,
|
||||
"status": k.status.as_str(),
|
||||
}));
|
||||
}
|
||||
json!({
|
||||
"type": "Marqdo Knowledge Graph",
|
||||
"generated": { "by": self.generated_by },
|
||||
"repository": {
|
||||
"title": self.repository.title,
|
||||
"root": self.repository.root,
|
||||
"modules": self.repository.module_count,
|
||||
"symbols": self.repository.symbol_count,
|
||||
"capabilities": self.repository.capability_count,
|
||||
"knowledge": self.repository.knowledge_count,
|
||||
},
|
||||
"nodes": nodes,
|
||||
"edge_count": self.edges.len(),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn to_edges_json(&self) -> Value {
|
||||
json!({
|
||||
"type": "Marqdo Knowledge Edges",
|
||||
"generated": { "by": self.generated_by },
|
||||
"edges": self.edges.iter().map(|e| e.to_json()).collect::<Vec<_>>(),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn index_map(&self) -> BTreeMap<String, Value> {
|
||||
let mut m = BTreeMap::new();
|
||||
for s in &self.symbols {
|
||||
m.insert(
|
||||
format!("symbol:{}", s.id),
|
||||
json!({
|
||||
"name": s.name,
|
||||
"module": s.module,
|
||||
"resource": s.resource,
|
||||
"capability": s.capability,
|
||||
"fingerprint": s.fingerprint_text,
|
||||
}),
|
||||
);
|
||||
}
|
||||
for c in &self.capabilities {
|
||||
m.insert(
|
||||
format!("capability:{}", c.id),
|
||||
json!({
|
||||
"name": c.name,
|
||||
"description": c.description,
|
||||
"implemented_by": c.implemented_by,
|
||||
}),
|
||||
);
|
||||
}
|
||||
for k in &self.knowledge {
|
||||
m.insert(
|
||||
format!("knowledge:{}", k.id),
|
||||
json!({
|
||||
"kind": k.kind.as_str(),
|
||||
"title": k.title,
|
||||
"summary": k.body_summary,
|
||||
}),
|
||||
);
|
||||
}
|
||||
m
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,130 @@
|
||||
//! Knowledge compilation from agent episodes / failure writebacks.
|
||||
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
|
||||
use anyhow::Result;
|
||||
|
||||
use crate::knowledge::util::slugify;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct LearnInput {
|
||||
pub task: String,
|
||||
pub failed_approach: Option<String>,
|
||||
pub failure: Option<String>,
|
||||
pub correct_approach: Option<String>,
|
||||
pub decision_title: Option<String>,
|
||||
pub decision_body: Option<String>,
|
||||
pub constraint_title: Option<String>,
|
||||
pub constraint_body: Option<String>,
|
||||
}
|
||||
|
||||
pub fn learn(out_dir: &Path, input: &LearnInput) -> Result<Vec<std::path::PathBuf>> {
|
||||
let mut written = Vec::new();
|
||||
|
||||
if input.failed_approach.is_some() || input.failure.is_some() {
|
||||
let dir = out_dir.join("knowledge/failures");
|
||||
fs::create_dir_all(&dir)?;
|
||||
let stem = slugify(&format!("fail-{}", &input.task));
|
||||
let path = dir.join(format!("{stem}.md"));
|
||||
let body = format!(
|
||||
r#"---
|
||||
type: Failure
|
||||
task: {task}
|
||||
status: resolved
|
||||
generated:
|
||||
by: marqdo/knowledge-learn
|
||||
---
|
||||
|
||||
# Do not repeat: {task}
|
||||
|
||||
## Failed approach
|
||||
|
||||
{failed}
|
||||
|
||||
## Failure
|
||||
|
||||
{failure}
|
||||
|
||||
## Correct approach
|
||||
|
||||
{correct}
|
||||
|
||||
## Introduced by
|
||||
|
||||
agent episode learn
|
||||
"#,
|
||||
task = input.task,
|
||||
failed = input.failed_approach.as_deref().unwrap_or("_unspecified_"),
|
||||
failure = input.failure.as_deref().unwrap_or("_unspecified_"),
|
||||
correct = input.correct_approach.as_deref().unwrap_or("_unspecified_"),
|
||||
);
|
||||
fs::write(&path, body)?;
|
||||
written.push(path);
|
||||
}
|
||||
|
||||
if let (Some(title), Some(body)) = (&input.decision_title, &input.decision_body) {
|
||||
let dir = out_dir.join("knowledge/decisions");
|
||||
fs::create_dir_all(&dir)?;
|
||||
let stem = slugify(title);
|
||||
let path = dir.join(format!("{stem}.md"));
|
||||
let page = format!(
|
||||
r#"---
|
||||
type: Decision
|
||||
title: {title}
|
||||
status: accepted
|
||||
generated:
|
||||
by: marqdo/knowledge-learn
|
||||
---
|
||||
|
||||
# {title}
|
||||
|
||||
## Decision
|
||||
|
||||
{body}
|
||||
"#,
|
||||
title = title,
|
||||
body = body,
|
||||
);
|
||||
fs::write(&path, page)?;
|
||||
written.push(path);
|
||||
}
|
||||
|
||||
if let (Some(title), Some(body)) = (&input.constraint_title, &input.constraint_body) {
|
||||
let dir = out_dir.join("knowledge/constraints");
|
||||
fs::create_dir_all(&dir)?;
|
||||
let stem = slugify(title);
|
||||
let path = dir.join(format!("{stem}.md"));
|
||||
let page = format!(
|
||||
r#"---
|
||||
type: Constraint
|
||||
title: {title}
|
||||
status: stable
|
||||
generated:
|
||||
by: marqdo/knowledge-learn
|
||||
---
|
||||
|
||||
# {title}
|
||||
|
||||
{body}
|
||||
"#,
|
||||
title = title,
|
||||
body = body,
|
||||
);
|
||||
fs::write(&path, page)?;
|
||||
written.push(path);
|
||||
}
|
||||
|
||||
// Episode receipt
|
||||
let ep = out_dir.join("agent/episodes");
|
||||
fs::create_dir_all(&ep)?;
|
||||
let ep_path = ep.join(format!("{}.json", slugify(&input.task)));
|
||||
let receipt = serde_json::json!({
|
||||
"task": input.task,
|
||||
"learned": written.iter().map(|p| p.display().to_string()).collect::<Vec<_>>(),
|
||||
});
|
||||
fs::write(&ep_path, serde_json::to_string_pretty(&receipt)?)?;
|
||||
written.push(ep_path);
|
||||
|
||||
Ok(written)
|
||||
}
|
||||
@@ -0,0 +1,254 @@
|
||||
//! Lifecycle: stale, conflicts, verify.
|
||||
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
use std::time::SystemTime;
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
use crate::knowledge::ir::{EdgeKind, KnowledgeGraph, Lifecycle};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct StaleItem {
|
||||
pub id: String,
|
||||
pub reason: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ConflictItem {
|
||||
pub left: String,
|
||||
pub right: String,
|
||||
pub note: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct VerifyIssue {
|
||||
pub severity: String, // error | warning
|
||||
pub message: String,
|
||||
}
|
||||
|
||||
pub fn find_stale(graph: &KnowledgeGraph, root: &Path) -> Vec<StaleItem> {
|
||||
let mut out = Vec::new();
|
||||
let now = chrono::Utc::now().date_naive();
|
||||
|
||||
for k in &graph.knowledge {
|
||||
if let Some(ref sa) = k.stale_after {
|
||||
if let Ok(d) = chrono::NaiveDate::parse_from_str(sa, "%Y-%m-%d") {
|
||||
if d < now {
|
||||
out.push(StaleItem {
|
||||
id: k.id.clone(),
|
||||
reason: format!("stale_after {sa} passed"),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
if matches!(k.status, Lifecycle::Deprecated | Lifecycle::Superseded) {
|
||||
out.push(StaleItem {
|
||||
id: k.id.clone(),
|
||||
reason: format!("status={}", k.status.as_str()),
|
||||
});
|
||||
}
|
||||
// Source newer than projection evidence — mtime drift
|
||||
let src = root.join(&k.resource);
|
||||
if src.exists() {
|
||||
if let (Ok(meta), Ok(proj_meta)) = (
|
||||
fs::metadata(&src),
|
||||
fs::metadata(root.join(".marqdo/graph/graph.json"))
|
||||
.or_else(|_| fs::metadata(root.join("graph/graph.json"))),
|
||||
) {
|
||||
if let (Ok(st), Ok(pt)) = (meta.modified(), proj_meta.modified()) {
|
||||
if st > pt {
|
||||
out.push(StaleItem {
|
||||
id: k.id.clone(),
|
||||
reason: "source newer than knowledge graph — recompile".into(),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for c in &graph.capabilities {
|
||||
if matches!(c.status, Lifecycle::Deprecated | Lifecycle::Superseded) {
|
||||
out.push(StaleItem {
|
||||
id: c.id.clone(),
|
||||
reason: format!("capability status={}", c.status.as_str()),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Dedup
|
||||
out.sort_by(|a, b| a.id.cmp(&b.id));
|
||||
out.dedup_by(|a, b| a.id == b.id && a.reason == b.reason);
|
||||
out
|
||||
}
|
||||
|
||||
pub fn find_conflicts(graph: &KnowledgeGraph) -> Vec<ConflictItem> {
|
||||
let mut out = Vec::new();
|
||||
for e in &graph.edges {
|
||||
if e.kind == EdgeKind::ConflictsWith {
|
||||
out.push(ConflictItem {
|
||||
left: e.from.clone(),
|
||||
right: e.to.clone(),
|
||||
note: e.note.clone(),
|
||||
});
|
||||
}
|
||||
}
|
||||
// Knowledge items that claim supersession without edge already covered
|
||||
for k in &graph.knowledge {
|
||||
for c in &k.conflicts_with {
|
||||
out.push(ConflictItem {
|
||||
left: format!("knowledge:{}", k.id),
|
||||
right: format!("knowledge:{c}"),
|
||||
note: Some("authored conflicts_with".into()),
|
||||
});
|
||||
}
|
||||
}
|
||||
out.sort_by(|a, b| (&a.left, &a.right).cmp(&(&b.left, &b.right)));
|
||||
out.dedup_by(|a, b| a.left == b.left && a.right == b.right);
|
||||
out
|
||||
}
|
||||
|
||||
pub fn verify(graph: &KnowledgeGraph) -> Vec<VerifyIssue> {
|
||||
let mut issues = Vec::new();
|
||||
|
||||
// Symbols referenced by capabilities must exist
|
||||
for c in &graph.capabilities {
|
||||
for sid in &c.implemented_by {
|
||||
if graph.symbol_by_id(sid).is_none() {
|
||||
issues.push(VerifyIssue {
|
||||
severity: "error".into(),
|
||||
message: format!(
|
||||
"capability `{}` implements missing symbol `{sid}`",
|
||||
c.id
|
||||
),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Edges must reference known-ish nodes (soft: warn)
|
||||
let mut node_ids = std::collections::HashSet::new();
|
||||
node_ids.insert("repo".into());
|
||||
for m in &graph.modules {
|
||||
node_ids.insert(format!("module:{}", m.id));
|
||||
}
|
||||
for s in &graph.symbols {
|
||||
node_ids.insert(format!("symbol:{}", s.id));
|
||||
}
|
||||
for c in &graph.capabilities {
|
||||
node_ids.insert(format!("capability:{}", c.id));
|
||||
}
|
||||
for k in &graph.knowledge {
|
||||
node_ids.insert(format!("knowledge:{}", k.id));
|
||||
}
|
||||
|
||||
for e in &graph.edges {
|
||||
if !node_ids.contains(&e.from) && !e.from.contains('/') {
|
||||
// allow raw applies_to strings
|
||||
if !e.from.starts_with("knowledge:")
|
||||
&& !e.from.starts_with("symbol:")
|
||||
&& !e.from.starts_with("capability:")
|
||||
&& !e.from.starts_with("module:")
|
||||
{
|
||||
continue;
|
||||
}
|
||||
issues.push(VerifyIssue {
|
||||
severity: "warning".into(),
|
||||
message: format!("edge from unknown node `{}`", e.from),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Duplicate high-similarity without documentation
|
||||
for c in &graph.capabilities {
|
||||
if !c.possible_duplicates.is_empty() {
|
||||
issues.push(VerifyIssue {
|
||||
severity: "warning".into(),
|
||||
message: format!(
|
||||
"capability `{}` has possible_duplicates: {}",
|
||||
c.id,
|
||||
c.possible_duplicates.join(", ")
|
||||
),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Supersedes targets should exist
|
||||
for k in &graph.knowledge {
|
||||
for s in &k.supersedes {
|
||||
if !graph.knowledge.iter().any(|o| o.id == *s || o.id.ends_with(s)) {
|
||||
issues.push(VerifyIssue {
|
||||
severity: "warning".into(),
|
||||
message: format!("knowledge `{}` supersedes unknown `{s}`", k.id),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
issues
|
||||
}
|
||||
|
||||
pub fn format_stale_text(items: &[StaleItem]) -> String {
|
||||
let mut out = String::from("Stale knowledge\n\n");
|
||||
if items.is_empty() {
|
||||
out.push_str("_None._\n");
|
||||
return out;
|
||||
}
|
||||
for i in items {
|
||||
out.push_str(&format!("- {} — {}\n", i.id, i.reason));
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
pub fn format_conflicts_text(items: &[ConflictItem]) -> String {
|
||||
let mut out = String::from("Knowledge conflicts\n\n");
|
||||
if items.is_empty() {
|
||||
out.push_str("_None._\n");
|
||||
return out;
|
||||
}
|
||||
for i in items {
|
||||
out.push_str(&format!(
|
||||
"- {} ↔ {}{}\n",
|
||||
i.left,
|
||||
i.right,
|
||||
i.note
|
||||
.as_ref()
|
||||
.map(|n| format!(" ({n})"))
|
||||
.unwrap_or_default()
|
||||
));
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
pub fn format_verify_text(issues: &[VerifyIssue]) -> String {
|
||||
let mut out = String::from("Knowledge verify\n\n");
|
||||
if issues.is_empty() {
|
||||
out.push_str("OK — code and knowledge projections are consistent.\n");
|
||||
return out;
|
||||
}
|
||||
for i in issues {
|
||||
out.push_str(&format!("[{}] {}\n", i.severity, i.message));
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
pub fn stale_json(items: &[StaleItem]) -> Value {
|
||||
json!({ "stale": items.iter().map(|i| json!({"id": i.id, "reason": i.reason})).collect::<Vec<_>>() })
|
||||
}
|
||||
|
||||
pub fn conflicts_json(items: &[ConflictItem]) -> Value {
|
||||
json!({ "conflicts": items.iter().map(|i| json!({"left": i.left, "right": i.right, "note": i.note})).collect::<Vec<_>>() })
|
||||
}
|
||||
|
||||
pub fn verify_json(issues: &[VerifyIssue]) -> Value {
|
||||
json!({
|
||||
"ok": issues.iter().all(|i| i.severity != "error"),
|
||||
"issues": issues.iter().map(|i| json!({"severity": i.severity, "message": i.message})).collect::<Vec<_>>(),
|
||||
})
|
||||
}
|
||||
|
||||
#[allow(dead_code)]
|
||||
fn _system_time_now() -> SystemTime {
|
||||
SystemTime::now()
|
||||
}
|
||||
@@ -0,0 +1,108 @@
|
||||
//! Reuse ratio / duplication rate metrics.
|
||||
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
|
||||
use anyhow::Result;
|
||||
use serde_json::{json, Value};
|
||||
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct ReuseMetrics {
|
||||
pub generated_functions: u64,
|
||||
pub reused: u64,
|
||||
pub adapted: u64,
|
||||
pub created: u64,
|
||||
pub duplicated: u64,
|
||||
}
|
||||
|
||||
impl ReuseMetrics {
|
||||
pub fn reuse_ratio(&self) -> f64 {
|
||||
if self.generated_functions == 0 {
|
||||
return 0.0;
|
||||
}
|
||||
self.reused as f64 / self.generated_functions as f64
|
||||
}
|
||||
|
||||
pub fn adapt_ratio(&self) -> f64 {
|
||||
if self.generated_functions == 0 {
|
||||
return 0.0;
|
||||
}
|
||||
self.adapted as f64 / self.generated_functions as f64
|
||||
}
|
||||
|
||||
pub fn novel_ratio(&self) -> f64 {
|
||||
if self.generated_functions == 0 {
|
||||
return 0.0;
|
||||
}
|
||||
self.created as f64 / self.generated_functions as f64
|
||||
}
|
||||
|
||||
pub fn duplication_rate(&self) -> f64 {
|
||||
if self.created == 0 {
|
||||
return 0.0;
|
||||
}
|
||||
self.duplicated as f64 / self.created as f64
|
||||
}
|
||||
|
||||
pub fn to_json(&self) -> Value {
|
||||
json!({
|
||||
"generated_functions": self.generated_functions,
|
||||
"reused": self.reused,
|
||||
"adapted": self.adapted,
|
||||
"created": self.created,
|
||||
"duplicated": self.duplicated,
|
||||
"reuse_ratio": self.reuse_ratio(),
|
||||
"adapt_ratio": self.adapt_ratio(),
|
||||
"novel_ratio": self.novel_ratio(),
|
||||
"duplication_rate": self.duplication_rate(),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
pub fn metrics_path(out_dir: &Path) -> std::path::PathBuf {
|
||||
out_dir.join("agent/episodes/reuse_metrics.json")
|
||||
}
|
||||
|
||||
pub fn load_metrics(out_dir: &Path) -> ReuseMetrics {
|
||||
let path = metrics_path(out_dir);
|
||||
let Ok(raw) = fs::read_to_string(path) else {
|
||||
return ReuseMetrics::default();
|
||||
};
|
||||
let Ok(v) = serde_json::from_str::<Value>(&raw) else {
|
||||
return ReuseMetrics::default();
|
||||
};
|
||||
ReuseMetrics {
|
||||
generated_functions: v.get("generated_functions").and_then(|x| x.as_u64()).unwrap_or(0),
|
||||
reused: v.get("reused").and_then(|x| x.as_u64()).unwrap_or(0),
|
||||
adapted: v.get("adapted").and_then(|x| x.as_u64()).unwrap_or(0),
|
||||
created: v.get("created").and_then(|x| x.as_u64()).unwrap_or(0),
|
||||
duplicated: v.get("duplicated").and_then(|x| x.as_u64()).unwrap_or(0),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn save_metrics(out_dir: &Path, m: &ReuseMetrics) -> Result<()> {
|
||||
let path = metrics_path(out_dir);
|
||||
if let Some(p) = path.parent() {
|
||||
fs::create_dir_all(p)?;
|
||||
}
|
||||
fs::write(path, serde_json::to_string_pretty(&m.to_json())?)?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn record_decision(out_dir: &Path, decision: &str, duplicated: bool) -> Result<ReuseMetrics> {
|
||||
let mut m = load_metrics(out_dir);
|
||||
m.generated_functions += 1;
|
||||
match decision.to_ascii_uppercase().as_str() {
|
||||
"REUSE" => m.reused += 1,
|
||||
"ADAPT" => m.adapted += 1,
|
||||
"CREATE" => {
|
||||
m.created += 1;
|
||||
if duplicated {
|
||||
m.duplicated += 1;
|
||||
}
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
save_metrics(out_dir, &m)?;
|
||||
Ok(m)
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
//! Marqdo Engineering Knowledge Compiler (EKC).
|
||||
//!
|
||||
//! Source of truth remains `*.mq.md`. This module projects L0–L4 catalog,
|
||||
//! knowledge graph, reuse preflight, and agent context packs under `.marqdo/`.
|
||||
|
||||
pub mod capability;
|
||||
pub mod compile;
|
||||
pub mod duplicate;
|
||||
pub mod extract;
|
||||
pub mod find;
|
||||
pub mod fingerprint;
|
||||
pub mod graph;
|
||||
pub mod impact;
|
||||
pub mod ir;
|
||||
pub mod learn;
|
||||
pub mod lifecycle;
|
||||
pub mod metrics;
|
||||
pub mod policy;
|
||||
pub mod preflight;
|
||||
pub mod reuse;
|
||||
pub mod util;
|
||||
|
||||
pub use compile::{compile, ensure_compiled, load_graph, KnowledgeOptions};
|
||||
pub use duplicate::{find_duplicates, format_duplicates_text};
|
||||
pub use find::{find, find_json, format_find_text};
|
||||
pub use impact::{format_impact_text, impact, impact_json};
|
||||
pub use ir::{KnowledgeGraph, ReuseDecision, ReuseResult};
|
||||
pub use learn::{learn, LearnInput};
|
||||
pub use lifecycle::{
|
||||
conflicts_json, find_conflicts, find_stale, format_conflicts_text, format_stale_text,
|
||||
format_verify_text, stale_json, verify, verify_json,
|
||||
};
|
||||
pub use metrics::{load_metrics, record_decision, save_metrics, ReuseMetrics};
|
||||
pub use policy::compile_policy;
|
||||
pub use preflight::{format_preflight_yaml, preflight, preflight_json, PreflightResult};
|
||||
pub use reuse::{format_reuse_text, resolve, reuse_json, ReuseBudget};
|
||||
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use anyhow::Result;
|
||||
|
||||
/// Run knowledge compile for CLI / catalog hook.
|
||||
pub fn write_knowledge(opts: KnowledgeOptions) -> Result<KnowledgeGraph> {
|
||||
compile(opts)
|
||||
}
|
||||
|
||||
/// Default out dir helper.
|
||||
pub fn default_out(path: &Path) -> PathBuf {
|
||||
if path.is_file() {
|
||||
path.parent()
|
||||
.unwrap_or(Path::new("."))
|
||||
.join(".marqdo")
|
||||
} else {
|
||||
path.join(".marqdo")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,87 @@
|
||||
//! Policy compilation: reuse resolution → `.marqdo/agent/policies/*.mq.md`.
|
||||
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
|
||||
use anyhow::Result;
|
||||
use sha2::{Digest, Sha256};
|
||||
|
||||
use crate::knowledge::ir::ReuseResult;
|
||||
use crate::knowledge::util::slugify;
|
||||
|
||||
pub fn compile_policy(out_dir: &Path, task: &str, result: &ReuseResult) -> Result<std::path::PathBuf> {
|
||||
let dir = out_dir.join("agent/policies");
|
||||
fs::create_dir_all(&dir)?;
|
||||
let mut h = Sha256::new();
|
||||
h.update(task.as_bytes());
|
||||
let id = format!("{:x}", h.finalize())[..12].to_string();
|
||||
let stem = format!("{}-{}", slugify(&result.decision.as_str().to_ascii_lowercase()), id);
|
||||
let path = dir.join(format!("{stem}.mq.md"));
|
||||
|
||||
let body = format!(
|
||||
r#"---
|
||||
type: Marqdo Policy
|
||||
title: Reuse policy for task
|
||||
decision: {decision}
|
||||
create_allowed: {create_allowed}
|
||||
capability: {capability}
|
||||
generated:
|
||||
by: marqdo/knowledge
|
||||
---
|
||||
|
||||
# Reuse Policy
|
||||
|
||||
## Task
|
||||
|
||||
{task}
|
||||
|
||||
## Decision
|
||||
|
||||
**{decision}**
|
||||
|
||||
## Recommended
|
||||
|
||||
{recommended}
|
||||
|
||||
## Reason
|
||||
|
||||
{reason}
|
||||
|
||||
## Candidates
|
||||
|
||||
{candidates}
|
||||
|
||||
# main
|
||||
|
||||
This policy artifact records Engineering First Information for replay and CI.
|
||||
|
||||
* "policy:{id}"
|
||||
"#,
|
||||
decision = result.decision.as_str(),
|
||||
create_allowed = result.create_allowed,
|
||||
capability = result.capability.as_deref().unwrap_or(""),
|
||||
task = task,
|
||||
recommended = result
|
||||
.recommended
|
||||
.iter()
|
||||
.map(|r| format!("- {r}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n"),
|
||||
reason = result
|
||||
.reason
|
||||
.iter()
|
||||
.map(|r| format!("- {r}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n"),
|
||||
candidates = result
|
||||
.candidates
|
||||
.iter()
|
||||
.take(8)
|
||||
.map(|c| format!("- {} ({:.2}) [{}]", c.title, c.score, c.kind))
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n"),
|
||||
id = id,
|
||||
);
|
||||
fs::write(&path, body)?;
|
||||
Ok(path)
|
||||
}
|
||||
@@ -0,0 +1,301 @@
|
||||
//! Engineering preflight + Context Pack artifacts.
|
||||
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
|
||||
use anyhow::Result;
|
||||
use serde_json::{json, Value};
|
||||
use sha2::{Digest, Sha256};
|
||||
|
||||
use crate::knowledge::ir::KnowledgeGraph;
|
||||
use crate::knowledge::reuse::{resolve, ReuseBudget};
|
||||
use crate::knowledge::util::slugify;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct PreflightResult {
|
||||
pub status: String,
|
||||
pub intent_capability: String,
|
||||
pub existing: Vec<String>,
|
||||
pub constraints: Vec<String>,
|
||||
pub decisions: Vec<String>,
|
||||
pub failures: Vec<String>,
|
||||
pub recommended: Vec<String>,
|
||||
pub create_allowed: bool,
|
||||
pub decision: String,
|
||||
pub context_path: Option<String>,
|
||||
pub pack_markdown: String,
|
||||
}
|
||||
|
||||
pub fn preflight(
|
||||
graph: &KnowledgeGraph,
|
||||
task: &str,
|
||||
budget: &ReuseBudget,
|
||||
out_dir: Option<&Path>,
|
||||
) -> Result<PreflightResult> {
|
||||
let reuse = resolve(graph, task, budget);
|
||||
let intent = reuse
|
||||
.capability
|
||||
.clone()
|
||||
.unwrap_or_else(|| infer_intent(task));
|
||||
|
||||
let existing: Vec<String> = reuse
|
||||
.candidates
|
||||
.iter()
|
||||
.filter(|c| c.kind == "Capability" || c.kind == "Function")
|
||||
.take(8)
|
||||
.map(|c| c.title.clone())
|
||||
.collect();
|
||||
|
||||
let pack = render_context_pack(task, &intent, &reuse, graph);
|
||||
let mut context_path = None;
|
||||
if let Some(out) = out_dir {
|
||||
let contexts = out.join("agent/contexts");
|
||||
fs::create_dir_all(&contexts)?;
|
||||
let id = task_id(task);
|
||||
let path = contexts.join(format!("task-{id}.mq.md"));
|
||||
fs::write(&path, &pack)?;
|
||||
context_path = Some(path.display().to_string());
|
||||
}
|
||||
|
||||
let status = if reuse.create_allowed {
|
||||
"ready_create"
|
||||
} else if reuse.decision == crate::knowledge::ir::ReuseDecision::Reuse
|
||||
|| reuse.decision == crate::knowledge::ir::ReuseDecision::Adapt
|
||||
{
|
||||
"ready"
|
||||
} else {
|
||||
"blocked"
|
||||
};
|
||||
|
||||
Ok(PreflightResult {
|
||||
status: status.into(),
|
||||
intent_capability: intent,
|
||||
existing,
|
||||
constraints: reuse.constraints.clone(),
|
||||
decisions: reuse.decisions.clone(),
|
||||
failures: reuse.failures.clone(),
|
||||
recommended: reuse.recommended.clone(),
|
||||
create_allowed: reuse.create_allowed,
|
||||
decision: reuse.decision.as_str().into(),
|
||||
context_path,
|
||||
pack_markdown: pack,
|
||||
})
|
||||
}
|
||||
|
||||
fn task_id(task: &str) -> String {
|
||||
let mut h = Sha256::new();
|
||||
h.update(task.as_bytes());
|
||||
format!("{:x}", h.finalize())[..12].to_string()
|
||||
}
|
||||
|
||||
fn infer_intent(task: &str) -> String {
|
||||
let tokens: Vec<_> = task
|
||||
.split_whitespace()
|
||||
.filter(|t| t.len() > 2)
|
||||
.take(4)
|
||||
.collect();
|
||||
if tokens.is_empty() {
|
||||
"unknown".into()
|
||||
} else {
|
||||
slugify(&tokens.join(" "))
|
||||
}
|
||||
}
|
||||
|
||||
fn render_context_pack(
|
||||
task: &str,
|
||||
intent: &str,
|
||||
reuse: &crate::knowledge::ir::ReuseResult,
|
||||
graph: &KnowledgeGraph,
|
||||
) -> String {
|
||||
let mut apis = Vec::new();
|
||||
for c in reuse.candidates.iter().take(5) {
|
||||
if let Some(cap) = graph.capability_by_id(
|
||||
c.id.strip_prefix("capability:")
|
||||
.unwrap_or(&c.id),
|
||||
) {
|
||||
for sid in &cap.implemented_by {
|
||||
if let Some(s) = graph.symbol_by_id(sid) {
|
||||
apis.push(format!("{} ({})", s.name, s.resource));
|
||||
}
|
||||
}
|
||||
} else if c.kind == "Function" {
|
||||
apis.push(format!(
|
||||
"{} ({})",
|
||||
c.title,
|
||||
c.resource.as_deref().unwrap_or("?")
|
||||
));
|
||||
}
|
||||
}
|
||||
apis.sort();
|
||||
apis.dedup();
|
||||
|
||||
let mut forbidden = Vec::new();
|
||||
for f in &reuse.failures {
|
||||
forbidden.push(format!("Do not repeat: {f}"));
|
||||
}
|
||||
for c in graph.knowledge.iter().filter(|k| {
|
||||
matches!(
|
||||
k.kind,
|
||||
crate::knowledge::ir::KnowledgeKind::AntiPattern
|
||||
| crate::knowledge::ir::KnowledgeKind::Constraint
|
||||
)
|
||||
}) {
|
||||
if reuse.constraints.iter().any(|x| x.contains(&c.id))
|
||||
|| reuse.failures.iter().any(|x| x.contains(&c.id))
|
||||
{
|
||||
forbidden.push(c.title.clone());
|
||||
}
|
||||
}
|
||||
|
||||
format!(
|
||||
r#"---
|
||||
type: Marqdo Context Pack
|
||||
title: Engineering Context
|
||||
task: {task_esc}
|
||||
intent: {intent}
|
||||
decision: {decision}
|
||||
create_allowed: {create_allowed}
|
||||
generated:
|
||||
by: marqdo/knowledge
|
||||
---
|
||||
|
||||
# Engineering Context
|
||||
|
||||
## Task
|
||||
|
||||
{task}
|
||||
|
||||
## Existing Capabilities
|
||||
|
||||
{existing}
|
||||
|
||||
## Relevant APIs
|
||||
|
||||
{apis}
|
||||
|
||||
## Constraints
|
||||
|
||||
{constraints}
|
||||
|
||||
## Decisions
|
||||
|
||||
{decisions}
|
||||
|
||||
## Known Failures
|
||||
|
||||
{failures}
|
||||
|
||||
## Recommended Reuse
|
||||
|
||||
{recommended}
|
||||
|
||||
## Forbidden
|
||||
|
||||
Do not implement:
|
||||
{forbidden}
|
||||
"#,
|
||||
task_esc = task.replace('\n', " "),
|
||||
intent = intent,
|
||||
decision = reuse.decision.as_str(),
|
||||
create_allowed = reuse.create_allowed,
|
||||
task = task,
|
||||
existing = bullet_list(
|
||||
&reuse
|
||||
.candidates
|
||||
.iter()
|
||||
.filter(|c| c.kind == "Capability" || c.kind == "Function")
|
||||
.take(8)
|
||||
.map(|c| format!("{} ({:.2})", c.title, c.score))
|
||||
.collect::<Vec<_>>()
|
||||
),
|
||||
apis = bullet_list(&apis),
|
||||
constraints = bullet_list(&reuse.constraints),
|
||||
decisions = bullet_list(&reuse.decisions),
|
||||
failures = bullet_list(&reuse.failures),
|
||||
recommended = numbered_list(&reuse.recommended),
|
||||
forbidden = bullet_list(&forbidden),
|
||||
)
|
||||
}
|
||||
|
||||
fn bullet_list(items: &[String]) -> String {
|
||||
if items.is_empty() {
|
||||
"- _none_".into()
|
||||
} else {
|
||||
items.iter().map(|i| format!("- {i}")).collect::<Vec<_>>().join("\n")
|
||||
}
|
||||
}
|
||||
|
||||
fn numbered_list(items: &[String]) -> String {
|
||||
if items.is_empty() {
|
||||
"1. _none_".into()
|
||||
} else {
|
||||
items
|
||||
.iter()
|
||||
.enumerate()
|
||||
.map(|(i, s)| format!("{}. {s}", i + 1))
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n")
|
||||
}
|
||||
}
|
||||
|
||||
pub fn preflight_json(p: &PreflightResult) -> Value {
|
||||
json!({
|
||||
"status": p.status,
|
||||
"intent": { "capability": p.intent_capability },
|
||||
"existing": p.existing,
|
||||
"constraints": p.constraints,
|
||||
"decisions": p.decisions,
|
||||
"failures": p.failures,
|
||||
"recommended": p.recommended,
|
||||
"create_allowed": p.create_allowed,
|
||||
"decision": p.decision,
|
||||
"context_path": p.context_path,
|
||||
})
|
||||
}
|
||||
|
||||
pub fn format_preflight_yaml(p: &PreflightResult) -> String {
|
||||
let mut out = String::new();
|
||||
out.push_str(&format!("status: {}\n\n", p.status));
|
||||
out.push_str("intent:\n");
|
||||
out.push_str(&format!(" capability: {}\n\n", p.intent_capability));
|
||||
out.push_str("existing:\n");
|
||||
for e in &p.existing {
|
||||
out.push_str(&format!(" - {e}\n"));
|
||||
}
|
||||
if p.existing.is_empty() {
|
||||
out.push_str(" []\n");
|
||||
}
|
||||
out.push_str("\nconstraints:\n");
|
||||
for c in &p.constraints {
|
||||
out.push_str(&format!(" - {c}\n"));
|
||||
}
|
||||
if p.constraints.is_empty() {
|
||||
out.push_str(" []\n");
|
||||
}
|
||||
out.push_str("\ndecisions:\n");
|
||||
for d in &p.decisions {
|
||||
out.push_str(&format!(" - {d}\n"));
|
||||
}
|
||||
if p.decisions.is_empty() {
|
||||
out.push_str(" []\n");
|
||||
}
|
||||
out.push_str("\nfailures:\n");
|
||||
for f in &p.failures {
|
||||
out.push_str(&format!(" - {f}\n"));
|
||||
}
|
||||
if p.failures.is_empty() {
|
||||
out.push_str(" []\n");
|
||||
}
|
||||
out.push_str("\nrecommended:\n");
|
||||
for r in &p.recommended {
|
||||
out.push_str(&format!(" - {r}\n"));
|
||||
}
|
||||
if p.recommended.is_empty() {
|
||||
out.push_str(" []\n");
|
||||
}
|
||||
out.push_str(&format!("\ncreate_allowed: {}\n", p.create_allowed));
|
||||
if let Some(ref pth) = p.context_path {
|
||||
out.push_str(&format!("context_pack: {pth}\n"));
|
||||
}
|
||||
out
|
||||
}
|
||||
@@ -0,0 +1,299 @@
|
||||
//! Reuse protocol: REUSE → ADAPT → CREATE with reuse budget.
|
||||
|
||||
use serde_json::{json, Value};
|
||||
|
||||
use crate::knowledge::find::{find, FindHit};
|
||||
use crate::knowledge::ir::{
|
||||
KnowledgeGraph, KnowledgeKind, ReuseCandidate, ReuseDecision, ReuseResult,
|
||||
};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ReuseBudget {
|
||||
pub min_candidates: usize,
|
||||
pub require_preflight: bool,
|
||||
pub require_reason: bool,
|
||||
pub allow_create_after: usize,
|
||||
pub reuse_threshold: f64,
|
||||
pub adapt_threshold: f64,
|
||||
}
|
||||
|
||||
impl Default for ReuseBudget {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
min_candidates: 3,
|
||||
require_preflight: true,
|
||||
require_reason: true,
|
||||
allow_create_after: 2,
|
||||
reuse_threshold: 0.72,
|
||||
adapt_threshold: 0.45,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
pub fn resolve(graph: &KnowledgeGraph, task: &str, budget: &ReuseBudget) -> ReuseResult {
|
||||
let hits = find(graph, task, 20);
|
||||
let mut candidates: Vec<ReuseCandidate> = hits
|
||||
.iter()
|
||||
.filter(|h| h.kind == "Capability" || h.kind == "Function")
|
||||
.map(|h| ReuseCandidate {
|
||||
id: h.id.clone(),
|
||||
kind: h.kind.clone(),
|
||||
title: h.title.clone(),
|
||||
score: h.score,
|
||||
resource: h.resource.clone(),
|
||||
reason: reason_for(h, task),
|
||||
})
|
||||
.collect();
|
||||
|
||||
// Ensure min_candidates from broader search if needed
|
||||
if candidates.len() < budget.min_candidates {
|
||||
for h in &hits {
|
||||
if candidates.iter().any(|c| c.id == h.id) {
|
||||
continue;
|
||||
}
|
||||
candidates.push(ReuseCandidate {
|
||||
id: h.id.clone(),
|
||||
kind: h.kind.clone(),
|
||||
title: h.title.clone(),
|
||||
score: h.score,
|
||||
resource: h.resource.clone(),
|
||||
reason: reason_for(h, task),
|
||||
});
|
||||
if candidates.len() >= budget.min_candidates {
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let constraints: Vec<String> = graph
|
||||
.knowledge
|
||||
.iter()
|
||||
.filter(|k| k.kind == KnowledgeKind::Constraint)
|
||||
.filter(|k| relevant_knowledge(k.title.as_str(), &k.body_summary, task, &hits))
|
||||
.map(|k| format!("{} ({})", k.title, k.id))
|
||||
.collect();
|
||||
|
||||
let decisions: Vec<String> = graph
|
||||
.knowledge
|
||||
.iter()
|
||||
.filter(|k| k.kind == KnowledgeKind::Decision)
|
||||
.filter(|k| relevant_knowledge(k.title.as_str(), &k.body_summary, task, &hits))
|
||||
.map(|k| format!("{} ({})", k.title, k.id))
|
||||
.collect();
|
||||
|
||||
let failures: Vec<String> = graph
|
||||
.knowledge
|
||||
.iter()
|
||||
.filter(|k| {
|
||||
matches!(
|
||||
k.kind,
|
||||
KnowledgeKind::Failure | KnowledgeKind::AntiPattern
|
||||
)
|
||||
})
|
||||
.filter(|k| relevant_knowledge(k.title.as_str(), &k.body_summary, task, &hits))
|
||||
.map(|k| format!("{} ({})", k.title, k.id))
|
||||
.collect();
|
||||
|
||||
let best = candidates.first().cloned();
|
||||
let best_score = best.as_ref().map(|c| c.score).unwrap_or(0.0);
|
||||
let analyzed = candidates.len().min(budget.allow_create_after.max(budget.min_candidates));
|
||||
|
||||
let (decision, create_allowed, reason, recommended) = if best_score >= budget.reuse_threshold {
|
||||
let b = best.as_ref().unwrap();
|
||||
let mut reasons = b.reason.clone();
|
||||
reasons.push("score meets REUSE threshold".into());
|
||||
if !constraints.is_empty() {
|
||||
reasons.push("active constraints favor existing capability".into());
|
||||
}
|
||||
(
|
||||
ReuseDecision::Reuse,
|
||||
false,
|
||||
reasons,
|
||||
vec![format!("REUSE {}", b.title)],
|
||||
)
|
||||
} else if best_score >= budget.adapt_threshold {
|
||||
let b = best.as_ref().unwrap();
|
||||
let mut reasons = b.reason.clone();
|
||||
reasons.push("near match — wrap/compose/extend rather than copy".into());
|
||||
(
|
||||
ReuseDecision::Adapt,
|
||||
false,
|
||||
reasons,
|
||||
vec![format!("ADAPT {}", b.title)],
|
||||
)
|
||||
} else if analyzed >= budget.allow_create_after {
|
||||
let mut reasons = vec![
|
||||
"no existing capability satisfies constraints".into(),
|
||||
format!("analyzed {analyzed} candidates below adapt threshold"),
|
||||
];
|
||||
if budget.require_reason {
|
||||
reasons.push("CREATE allowed only after reuse budget exhausted".into());
|
||||
}
|
||||
(ReuseDecision::Create, true, reasons, vec!["CREATE new capability".into()])
|
||||
} else {
|
||||
(
|
||||
ReuseDecision::Create,
|
||||
false,
|
||||
vec![
|
||||
format!(
|
||||
"insufficient candidates analyzed ({analyzed} < {})",
|
||||
budget.allow_create_after
|
||||
),
|
||||
"continue discovery before CREATE".into(),
|
||||
],
|
||||
vec![],
|
||||
)
|
||||
};
|
||||
|
||||
let capability = best.as_ref().and_then(|c| {
|
||||
if c.kind == "Capability" {
|
||||
Some(c.title.clone())
|
||||
} else {
|
||||
c.id.strip_prefix("capability:").map(|s| s.to_string())
|
||||
}
|
||||
});
|
||||
let symbol = best.as_ref().and_then(|c| {
|
||||
if c.kind == "Function" {
|
||||
Some(c.title.clone())
|
||||
} else if let Some(cap) = capability.as_ref() {
|
||||
graph
|
||||
.capability_by_id(cap)
|
||||
.and_then(|cap| cap.implemented_by.first().cloned())
|
||||
} else {
|
||||
None
|
||||
}
|
||||
});
|
||||
let source = best.as_ref().and_then(|c| c.resource.clone());
|
||||
|
||||
ReuseResult {
|
||||
decision,
|
||||
confidence: best_score,
|
||||
capability,
|
||||
symbol,
|
||||
source,
|
||||
reason,
|
||||
candidates,
|
||||
constraints,
|
||||
decisions,
|
||||
failures,
|
||||
create_allowed,
|
||||
recommended,
|
||||
}
|
||||
}
|
||||
|
||||
fn reason_for(h: &FindHit, task: &str) -> Vec<String> {
|
||||
let mut r = Vec::new();
|
||||
r.push(format!("matched query tokens against {}", h.kind));
|
||||
if h.score >= 0.7 {
|
||||
r.push("same input/output semantics likely".into());
|
||||
}
|
||||
if task.to_ascii_lowercase().split_whitespace().any(|t| {
|
||||
h.title.to_ascii_lowercase().contains(t) && t.len() > 2
|
||||
}) {
|
||||
r.push("title overlaps task terms".into());
|
||||
}
|
||||
r
|
||||
}
|
||||
|
||||
fn relevant_knowledge(title: &str, body: &str, task: &str, hits: &[FindHit]) -> bool {
|
||||
let material = format!("{title} {body}").to_ascii_lowercase();
|
||||
let task_l = task.to_ascii_lowercase();
|
||||
if task_l.split_whitespace().any(|t| t.len() > 3 && material.contains(t)) {
|
||||
return true;
|
||||
}
|
||||
hits.iter().take(5).any(|h| {
|
||||
material.contains(&h.title.to_ascii_lowercase())
|
||||
|| h.snippet
|
||||
.to_ascii_lowercase()
|
||||
.split_whitespace()
|
||||
.any(|t| t.len() > 4 && material.contains(t))
|
||||
})
|
||||
}
|
||||
|
||||
pub fn format_reuse_text(task: &str, result: &ReuseResult) -> String {
|
||||
let mut out = String::from("Engineering First Information\n\n");
|
||||
out.push_str(&format!("Task: {task}\n\n"));
|
||||
out.push_str("Existing capabilities:\n");
|
||||
let caps: Vec<_> = result
|
||||
.candidates
|
||||
.iter()
|
||||
.filter(|c| c.kind == "Capability" || c.kind == "Function")
|
||||
.collect();
|
||||
if caps.is_empty() {
|
||||
out.push_str(" (none)\n");
|
||||
} else {
|
||||
for c in caps.iter().take(8) {
|
||||
out.push_str(&format!(" {:<28} {:.2}\n", c.title, c.score));
|
||||
}
|
||||
}
|
||||
out.push('\n');
|
||||
if !result.constraints.is_empty() {
|
||||
out.push_str("Relevant constraints:\n");
|
||||
for c in &result.constraints {
|
||||
out.push_str(&format!(" {c}\n"));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
if !result.decisions.is_empty() {
|
||||
out.push_str("Relevant decisions:\n");
|
||||
for d in &result.decisions {
|
||||
out.push_str(&format!(" {d}\n"));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
if !result.failures.is_empty() {
|
||||
out.push_str("Known failures:\n");
|
||||
for f in &result.failures {
|
||||
out.push_str(&format!(" {f}\n"));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
out.push_str("Recommended:\n");
|
||||
if result.recommended.is_empty() {
|
||||
out.push_str(&format!(" {}\n", result.decision.as_str()));
|
||||
} else {
|
||||
for r in &result.recommended {
|
||||
out.push_str(&format!(" {r}\n"));
|
||||
}
|
||||
}
|
||||
out.push('\n');
|
||||
out.push_str("New implementation:\n");
|
||||
if result.create_allowed {
|
||||
out.push_str(" ALLOWED (CREATE)\n");
|
||||
} else if result.decision == ReuseDecision::Create {
|
||||
out.push_str(" NOT YET — exhaust reuse budget first\n");
|
||||
} else {
|
||||
out.push_str(" NOT REQUIRED\n");
|
||||
}
|
||||
out.push('\n');
|
||||
out.push_str("Reason:\n");
|
||||
for r in &result.reason {
|
||||
out.push_str(&format!(" - {r}\n"));
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
pub fn reuse_json(task: &str, result: &ReuseResult) -> Value {
|
||||
json!({
|
||||
"task": task,
|
||||
"decision": result.decision.as_str(),
|
||||
"confidence": result.confidence,
|
||||
"capability": result.capability,
|
||||
"symbol": result.symbol,
|
||||
"source": result.source,
|
||||
"reason": result.reason,
|
||||
"create_allowed": result.create_allowed,
|
||||
"recommended": result.recommended,
|
||||
"constraints": result.constraints,
|
||||
"decisions": result.decisions,
|
||||
"failures": result.failures,
|
||||
"candidates": result.candidates.iter().map(|c| json!({
|
||||
"id": c.id,
|
||||
"kind": c.kind,
|
||||
"title": c.title,
|
||||
"score": c.score,
|
||||
"resource": c.resource,
|
||||
"reason": c.reason,
|
||||
})).collect::<Vec<_>>(),
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,197 @@
|
||||
//! Shared frontmatter / prose helpers for knowledge extraction.
|
||||
|
||||
pub fn extract_fm_field(source: &str, key: &str) -> Option<String> {
|
||||
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
|
||||
let lines: Vec<&str> = source.lines().collect();
|
||||
if lines.first().map(|l| l.trim()) != Some("---") {
|
||||
return None;
|
||||
}
|
||||
let prefix = format!("{key}:");
|
||||
for line in lines.iter().skip(1) {
|
||||
let t = line.trim();
|
||||
if t == "---" {
|
||||
break;
|
||||
}
|
||||
if let Some(rest) = t.strip_prefix(&prefix) {
|
||||
return Some(rest.trim().trim_matches('"').to_string());
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
pub fn extract_nested_by(source: &str, block: &str) -> Option<String> {
|
||||
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
|
||||
let lines: Vec<&str> = source.lines().collect();
|
||||
if lines.first().map(|l| l.trim()) != Some("---") {
|
||||
return None;
|
||||
}
|
||||
let mut in_block = false;
|
||||
for line in lines.iter().skip(1) {
|
||||
let t = line.trim_end();
|
||||
if t.trim() == "---" {
|
||||
break;
|
||||
}
|
||||
if t.trim() == format!("{block}:") {
|
||||
in_block = true;
|
||||
continue;
|
||||
}
|
||||
if in_block {
|
||||
let trimmed = t.trim();
|
||||
if trimmed.starts_with("by:") {
|
||||
return Some(
|
||||
trimmed
|
||||
.trim_start_matches("by:")
|
||||
.trim()
|
||||
.trim_matches('"')
|
||||
.to_string(),
|
||||
);
|
||||
}
|
||||
if !trimmed.is_empty() && !line.starts_with(' ') && !line.starts_with('\t') {
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
pub fn extract_fm_list(source: &str, key: &str) -> Vec<String> {
|
||||
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
|
||||
let lines: Vec<&str> = source.lines().collect();
|
||||
if lines.first().map(|l| l.trim()) != Some("---") {
|
||||
return Vec::new();
|
||||
}
|
||||
let mut out = Vec::new();
|
||||
let mut in_list = false;
|
||||
let header = format!("{key}:");
|
||||
for line in lines.iter().skip(1) {
|
||||
let t = line.trim_end();
|
||||
if t.trim() == "---" {
|
||||
break;
|
||||
}
|
||||
if t.trim() == header || t.trim() == format!("{key}: []") {
|
||||
if t.trim().ends_with("[]") {
|
||||
return Vec::new();
|
||||
}
|
||||
in_list = true;
|
||||
continue;
|
||||
}
|
||||
if in_list {
|
||||
let trimmed = t.trim();
|
||||
if let Some(rest) = trimmed.strip_prefix("- ") {
|
||||
out.push(rest.trim().trim_matches('"').to_string());
|
||||
} else if !trimmed.is_empty() && !line.starts_with(' ') && !line.starts_with('\t') {
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
/// Extract section body under `## Heading` until next `##` / `#` / EOF.
|
||||
pub fn extract_section(source: &str, heading: &str) -> Option<String> {
|
||||
let markers = [
|
||||
format!("## {heading}"),
|
||||
format!("## {}", heading.to_ascii_lowercase()),
|
||||
format!("## {}", heading.to_ascii_uppercase()),
|
||||
];
|
||||
let lines: Vec<&str> = source.lines().collect();
|
||||
let mut start = None;
|
||||
for (i, line) in lines.iter().enumerate() {
|
||||
let t = line.trim();
|
||||
if markers.iter().any(|m| t.eq_ignore_ascii_case(m)) {
|
||||
start = Some(i + 1);
|
||||
break;
|
||||
}
|
||||
}
|
||||
let start = start?;
|
||||
let mut body = Vec::new();
|
||||
for line in lines.iter().skip(start) {
|
||||
let t = line.trim();
|
||||
if t.starts_with("## ") || (t.starts_with("# ") && !t.starts_with("## ")) {
|
||||
break;
|
||||
}
|
||||
body.push(*line);
|
||||
}
|
||||
let s = body.join("\n").trim().to_string();
|
||||
if s.is_empty() {
|
||||
None
|
||||
} else {
|
||||
Some(s)
|
||||
}
|
||||
}
|
||||
|
||||
pub fn first_paragraph(source: &str) -> String {
|
||||
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
|
||||
let mut after_fm = source;
|
||||
if let Some(rest) = source.strip_prefix("---") {
|
||||
if let Some(idx) = rest.find("\n---") {
|
||||
after_fm = &rest[idx + 4..];
|
||||
}
|
||||
}
|
||||
let mut paras = Vec::new();
|
||||
let mut cur = String::new();
|
||||
for line in after_fm.lines() {
|
||||
let t = line.trim();
|
||||
if t.starts_with('#') {
|
||||
if !cur.is_empty() {
|
||||
break;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if t.is_empty() {
|
||||
if !cur.is_empty() {
|
||||
paras.push(cur.clone());
|
||||
break;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if !cur.is_empty() {
|
||||
cur.push(' ');
|
||||
}
|
||||
cur.push_str(t);
|
||||
}
|
||||
if paras.is_empty() && !cur.is_empty() {
|
||||
paras.push(cur);
|
||||
}
|
||||
paras.first().cloned().unwrap_or_default()
|
||||
}
|
||||
|
||||
pub fn yaml_escape(s: &str) -> String {
|
||||
if s.is_empty()
|
||||
|| s.contains(':')
|
||||
|| s.contains('#')
|
||||
|| s.contains('"')
|
||||
|| s.contains('\'')
|
||||
|| s.contains('\n')
|
||||
|| s.starts_with(' ')
|
||||
{
|
||||
format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\""))
|
||||
} else {
|
||||
s.to_string()
|
||||
}
|
||||
}
|
||||
|
||||
pub fn module_stem(resource: &str) -> String {
|
||||
resource
|
||||
.replace('/', "__")
|
||||
.replace('\\', "__")
|
||||
.trim_end_matches(".mq.md")
|
||||
.trim_end_matches(".md")
|
||||
.to_string()
|
||||
}
|
||||
|
||||
pub fn slugify(s: &str) -> String {
|
||||
let mut out = String::new();
|
||||
for c in s.chars() {
|
||||
if c.is_ascii_alphanumeric() {
|
||||
out.push(c.to_ascii_lowercase());
|
||||
} else if c == '_' || c == '-' || c == '.' {
|
||||
out.push(c);
|
||||
} else if c.is_whitespace() || c == '/' {
|
||||
if !out.ends_with('-') {
|
||||
out.push('-');
|
||||
}
|
||||
}
|
||||
}
|
||||
out.trim_matches('-').to_string()
|
||||
}
|
||||
+80
-1
@@ -279,7 +279,52 @@ fn breaks_comment_paragraph(trimmed: &str) -> bool {
|
||||
if trimmed.starts_with('#') || trimmed.starts_with('>') {
|
||||
return true;
|
||||
}
|
||||
is_marqdo_star_line(trimmed)
|
||||
if is_marqdo_star_line(trimmed) {
|
||||
return true;
|
||||
}
|
||||
// Branch arms / loops / params must not be swallowed after prose in an arm body.
|
||||
if looks_like_ordered_list_item(trimmed) {
|
||||
return true;
|
||||
}
|
||||
if trimmed.starts_with("- ") || trimmed.starts_with("-\t") || trimmed == "-" {
|
||||
return true;
|
||||
}
|
||||
if trimmed.starts_with('+') {
|
||||
return true;
|
||||
}
|
||||
if is_image_writeback_line(trimmed) {
|
||||
return true;
|
||||
}
|
||||
false
|
||||
}
|
||||
|
||||
/// `` — image writeback surface (see stdlib-writeback).
|
||||
pub fn is_image_writeback_line(trimmed: &str) -> bool {
|
||||
let t = trimmed.trim();
|
||||
let Some(rest) = t.strip_prefix(" else {
|
||||
return false;
|
||||
};
|
||||
let alt = rest[..alt_end].trim();
|
||||
alt.split_whitespace().any(|tok| tok == "marqdo-out")
|
||||
}
|
||||
|
||||
fn looks_like_ordered_list_item(trimmed: &str) -> bool {
|
||||
let mut chars = trimmed.chars();
|
||||
let mut saw_digit = false;
|
||||
while let Some(c) = chars.next() {
|
||||
if c.is_ascii_digit() {
|
||||
saw_digit = true;
|
||||
continue;
|
||||
}
|
||||
if c == '.' && saw_digit {
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
false
|
||||
}
|
||||
|
||||
/// Classify a single logical line (no trailing newline required).
|
||||
@@ -353,6 +398,9 @@ pub fn classify_source(source: &str) -> Vec<ClassifiedLine> {
|
||||
in_writeback = false;
|
||||
}
|
||||
LineKind::Writeback
|
||||
} else if is_image_writeback_line(trimmed) {
|
||||
in_comment_paragraph = false;
|
||||
LineKind::Writeback
|
||||
} else {
|
||||
match base {
|
||||
LineKind::Blank => {
|
||||
@@ -439,6 +487,26 @@ pub fn format_lines_dump(path: &str, lines: &[ClassifiedLine]) -> String {
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn ordered_arm_breaks_prose_paragraph() {
|
||||
let src = "\
|
||||
# main\n\
|
||||
\n\
|
||||
1. `n` > 0\n\
|
||||
此时我们 **打印 内容=\"正\"**\n\
|
||||
2. *\n\
|
||||
否则 **打印 内容=\"非正\"**\n\
|
||||
";
|
||||
let lines = classify_source(src);
|
||||
let l12 = lines.iter().find(|l| l.text.trim() == "2. *").expect("2. *");
|
||||
assert_eq!(
|
||||
l12.kind,
|
||||
LineKind::Code,
|
||||
"else arm must stay Code after prose, got dump:\n{}",
|
||||
format_lines_dump("t", &lines)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn blank_and_comment_and_code() {
|
||||
assert_eq!(classify_line(""), LineKind::Blank);
|
||||
@@ -498,6 +566,17 @@ mod tests {
|
||||
assert_eq!(lines[3].kind, LineKind::Writeback);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn image_writeback_line_classified() {
|
||||
assert!(is_image_writeback_line(""));
|
||||
assert!(is_image_writeback_line(""));
|
||||
assert!(!is_image_writeback_line(""));
|
||||
let src = "# main\n\n**x = 1**\n\n\n> print text=x\n";
|
||||
let lines = classify_source(src);
|
||||
let img = lines.iter().find(|l| l.text.contains("marqdo-out]")).unwrap();
|
||||
assert_eq!(img.kind, LineKind::Writeback, "{:?}", lines);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn paragraph_comment_keeps_backtick_continuation() {
|
||||
let src = "采用了\n`.mq.md`的双层后缀\n\n> print text=ok\n";
|
||||
|
||||
+18
@@ -13,6 +13,8 @@ pub mod bytecode;
|
||||
pub mod capture;
|
||||
#[cfg(feature = "cli")]
|
||||
pub mod catalog;
|
||||
#[cfg(feature = "cli")]
|
||||
pub mod knowledge;
|
||||
pub mod check;
|
||||
pub mod contract;
|
||||
pub mod debug;
|
||||
@@ -205,6 +207,10 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
|
||||
let mut host = HostContext::for_run(Some(path), opts.host_caps(), opts.argv.clone());
|
||||
host.set_entry_source(Some(path), &source);
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
if let Some(root) = &opts.fs_root {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
}
|
||||
let mut interp = Interpreter::new(Some(path), opts.trace_eval)
|
||||
.with_stdin(stdin_lines.clone())
|
||||
.with_host(host);
|
||||
@@ -227,6 +233,10 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
|
||||
let mut host = HostContext::for_run(Some(path), opts.host_caps(), opts.argv.clone());
|
||||
host.set_entry_source(Some(path), &source);
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
if let Some(root) = &opts.fs_root {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
}
|
||||
let mut vm = Vm::new(Some(path))
|
||||
.with_stdin(stdin_lines)
|
||||
.with_trace(opts.trace_eval)
|
||||
@@ -281,6 +291,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
if let Some(root) = &opts.fs_root {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
}
|
||||
if let Some(lim) = opts.sleep_limit_ms {
|
||||
host.sleep_limit_ms = Some(lim);
|
||||
@@ -295,6 +306,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
|
||||
value,
|
||||
plots,
|
||||
bindings: interp.entry_bindings,
|
||||
view_trace: interp.view_trace,
|
||||
})
|
||||
}
|
||||
Backend::Bytecode => {
|
||||
@@ -305,6 +317,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
if let Some(root) = &opts.fs_root {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
}
|
||||
if let Some(lim) = opts.sleep_limit_ms {
|
||||
host.sleep_limit_ms = Some(lim);
|
||||
@@ -319,6 +332,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
|
||||
value,
|
||||
plots,
|
||||
bindings: Default::default(),
|
||||
view_trace: Default::default(),
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -339,6 +353,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
if let Some(root) = &opts.fs_root {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
}
|
||||
if let Some(lim) = opts.sleep_limit_ms {
|
||||
host.sleep_limit_ms = Some(lim);
|
||||
@@ -353,6 +368,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
|
||||
value,
|
||||
plots,
|
||||
bindings: interp.entry_bindings,
|
||||
view_trace: interp.view_trace,
|
||||
})
|
||||
}
|
||||
Backend::Bytecode => {
|
||||
@@ -363,6 +379,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
|
||||
host.entry_metadata = module.metadata.clone();
|
||||
if let Some(root) = &opts.fs_root {
|
||||
host.fs_root = Some(root.clone());
|
||||
host.cwd = root.clone();
|
||||
}
|
||||
if let Some(lim) = opts.sleep_limit_ms {
|
||||
host.sleep_limit_ms = Some(lim);
|
||||
@@ -377,6 +394,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
|
||||
value,
|
||||
plots,
|
||||
bindings: Default::default(),
|
||||
view_trace: Default::default(),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
+431
-5
@@ -8,11 +8,19 @@ use marqdo::catalog::{write_catalog, CatalogOptions};
|
||||
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,
|
||||
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_static, DebugOptions, OutputOptions, ViewOptions};
|
||||
use marqdo::{Backend, RunOptions};
|
||||
|
||||
#[derive(Parser, Debug)]
|
||||
#[command(name = "marqdo", version, about = "Marqdo interpreter — run, view, debug, catalog, and ext")]
|
||||
#[command(name = "marqdo", version, about = "Marqdo interpreter — run, view, debug, catalog, knowledge, and ext")]
|
||||
struct Cli {
|
||||
#[command(subcommand)]
|
||||
command: Commands,
|
||||
@@ -70,6 +78,11 @@ enum Commands {
|
||||
#[arg(long = "bind", value_name = "KEY=VALUE")]
|
||||
binds: Vec<String>,
|
||||
|
||||
/// Filesystem sandbox + process cwd root (default: entry file's directory).
|
||||
/// Also read from env `MARQDO_FS_ROOT`. Use repo root when running `cli/…` entries.
|
||||
#[arg(long = "fs-root", value_name = "DIR")]
|
||||
fs_root: Option<PathBuf>,
|
||||
|
||||
/// Emit diagnostics as JSON on stderr (machine-readable; AI/MLSP 面).
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
@@ -119,13 +132,17 @@ enum Commands {
|
||||
#[arg(long)]
|
||||
no_open: bool,
|
||||
},
|
||||
/// Generate OKF-compatible catalog YAML + module pages
|
||||
/// Generate OKF-compatible catalog YAML + module pages (+ Engineering Knowledge)
|
||||
Catalog {
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
|
||||
/// Skip Engineering Knowledge Compiler after catalog
|
||||
#[arg(long)]
|
||||
no_knowledge: bool,
|
||||
},
|
||||
/// Alias for `catalog`
|
||||
Sync {
|
||||
@@ -134,6 +151,129 @@ enum Commands {
|
||||
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
|
||||
#[arg(long)]
|
||||
no_knowledge: bool,
|
||||
},
|
||||
/// Engineering Knowledge Compiler (L0–L4 catalog / graph / projections)
|
||||
Knowledge {
|
||||
#[command(subcommand)]
|
||||
action: Option<KnowledgeAction>,
|
||||
|
||||
#[arg(value_name = "PATH", global = true)]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo", global = true)]
|
||||
out: PathBuf,
|
||||
|
||||
#[arg(long, global = true)]
|
||||
json: bool,
|
||||
},
|
||||
/// Find engineering capabilities / symbols / knowledge
|
||||
Find {
|
||||
#[arg(value_name = "QUERY")]
|
||||
query: String,
|
||||
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
|
||||
#[arg(long, default_value_t = 20)]
|
||||
limit: usize,
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
},
|
||||
/// Engineering First Information: REUSE / ADAPT / CREATE
|
||||
Reuse {
|
||||
#[arg(value_name = "TASK")]
|
||||
task: String,
|
||||
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
|
||||
/// Also write preflight context pack + policy
|
||||
#[arg(long)]
|
||||
preflight: bool,
|
||||
|
||||
#[arg(long, default_value_t = 3)]
|
||||
min_candidates: usize,
|
||||
|
||||
#[arg(long, default_value_t = 2)]
|
||||
allow_create_after: usize,
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
},
|
||||
/// Knowledge impact of changed paths
|
||||
Impact {
|
||||
#[arg(value_name = "PATH")]
|
||||
paths: Vec<PathBuf>,
|
||||
|
||||
#[arg(long, value_name = "ROOT", default_value = ".")]
|
||||
root: PathBuf,
|
||||
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
},
|
||||
/// Detect knowledge conflicts / possible duplicates edges
|
||||
Conflicts {
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
},
|
||||
/// List stale / deprecated / superseded knowledge
|
||||
Stale {
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
},
|
||||
/// Detect duplicate capabilities via symbol fingerprints
|
||||
Duplicate {
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
|
||||
#[arg(long, default_value_t = 0.75)]
|
||||
threshold: f64,
|
||||
|
||||
/// Exit non-zero when duplicates found (CI gate)
|
||||
#[arg(long)]
|
||||
fail: bool,
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
},
|
||||
/// Verify code ↔ knowledge consistency
|
||||
Verify {
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
|
||||
#[arg(long)]
|
||||
json: bool,
|
||||
},
|
||||
/// Official extension installer (`list` / `add` / `remove`)
|
||||
Ext {
|
||||
@@ -152,6 +292,50 @@ enum Commands {
|
||||
},
|
||||
}
|
||||
|
||||
#[derive(Subcommand, Debug)]
|
||||
enum KnowledgeAction {
|
||||
/// Compile L0–L4 projections (default)
|
||||
Compile,
|
||||
/// Run engineering preflight for a task
|
||||
Preflight {
|
||||
#[arg(value_name = "TASK")]
|
||||
task: String,
|
||||
|
||||
#[arg(long, default_value_t = 3)]
|
||||
min_candidates: usize,
|
||||
|
||||
#[arg(long, default_value_t = 2)]
|
||||
allow_create_after: usize,
|
||||
},
|
||||
/// Record a reuse decision into metrics
|
||||
Record {
|
||||
#[arg(value_name = "DECISION")]
|
||||
decision: String,
|
||||
|
||||
#[arg(long)]
|
||||
duplicated: bool,
|
||||
},
|
||||
/// Learn failure/decision/constraint into knowledge/
|
||||
Learn {
|
||||
#[arg(long)]
|
||||
task: String,
|
||||
#[arg(long)]
|
||||
failed_approach: Option<String>,
|
||||
#[arg(long)]
|
||||
failure: Option<String>,
|
||||
#[arg(long)]
|
||||
correct_approach: Option<String>,
|
||||
#[arg(long)]
|
||||
decision_title: Option<String>,
|
||||
#[arg(long)]
|
||||
decision_body: Option<String>,
|
||||
#[arg(long)]
|
||||
constraint_title: Option<String>,
|
||||
#[arg(long)]
|
||||
constraint_body: Option<String>,
|
||||
},
|
||||
}
|
||||
|
||||
#[derive(Subcommand, Debug)]
|
||||
enum ExtAction {
|
||||
/// List official extensions and install status
|
||||
@@ -233,6 +417,7 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
stdin_file,
|
||||
emit_result,
|
||||
binds,
|
||||
fs_root,
|
||||
json: _,
|
||||
} => {
|
||||
let path = file.unwrap_or_else(|| PathBuf::from("index.mq.md"));
|
||||
@@ -244,11 +429,14 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
for b in &binds {
|
||||
bind_pairs.push(marqdo::binding::parse_bind_kv(b)?);
|
||||
}
|
||||
let env_fs_root = std::env::var_os("MARQDO_FS_ROOT").map(PathBuf::from);
|
||||
let fs_root = fs_root.or(env_fs_root);
|
||||
let mut opts = if dump_all {
|
||||
RunOptions {
|
||||
stdin_lines: stdin_lines.clone(),
|
||||
emit_result: emit_result.clone(),
|
||||
binds: bind_pairs.clone(),
|
||||
fs_root: fs_root.clone(),
|
||||
..RunOptions::dump_all()
|
||||
}
|
||||
} else {
|
||||
@@ -263,6 +451,7 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
stdin_lines,
|
||||
emit_result,
|
||||
binds: bind_pairs,
|
||||
fs_root,
|
||||
..RunOptions::default()
|
||||
}
|
||||
};
|
||||
@@ -354,13 +543,250 @@ fn try_main(cli: Cli) -> Result<i32> {
|
||||
})?;
|
||||
Ok(0)
|
||||
}
|
||||
Commands::Catalog { path, out } | Commands::Sync { path, out } => {
|
||||
Commands::Catalog {
|
||||
path,
|
||||
out,
|
||||
no_knowledge,
|
||||
}
|
||||
| Commands::Sync {
|
||||
path,
|
||||
out,
|
||||
no_knowledge,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
write_catalog(CatalogOptions {
|
||||
path: path.unwrap_or_else(|| PathBuf::from(".")),
|
||||
out_dir: out,
|
||||
path: path.clone(),
|
||||
out_dir: out.clone(),
|
||||
})?;
|
||||
if !no_knowledge {
|
||||
write_knowledge(KnowledgeOptions {
|
||||
path,
|
||||
out_dir: out,
|
||||
})?;
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
Commands::Knowledge {
|
||||
action,
|
||||
path,
|
||||
out,
|
||||
json,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
match action.unwrap_or(KnowledgeAction::Compile) {
|
||||
KnowledgeAction::Compile => {
|
||||
write_knowledge(KnowledgeOptions {
|
||||
path,
|
||||
out_dir: out,
|
||||
})?;
|
||||
Ok(0)
|
||||
}
|
||||
KnowledgeAction::Preflight {
|
||||
task,
|
||||
min_candidates,
|
||||
allow_create_after,
|
||||
} => {
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let budget = ReuseBudget {
|
||||
min_candidates,
|
||||
allow_create_after,
|
||||
..ReuseBudget::default()
|
||||
};
|
||||
let pf = preflight(&graph, &task, &budget, Some(&out))?;
|
||||
let _ = compile_policy(&out, &task, &resolve(&graph, &task, &budget));
|
||||
if json {
|
||||
println!("{}", preflight_json(&pf));
|
||||
} else {
|
||||
print!("{}", format_preflight_yaml(&pf));
|
||||
}
|
||||
Ok(if pf.create_allowed
|
||||
|| pf.decision == "REUSE"
|
||||
|| pf.decision == "ADAPT"
|
||||
{
|
||||
0
|
||||
} else {
|
||||
2
|
||||
})
|
||||
}
|
||||
KnowledgeAction::Record {
|
||||
decision,
|
||||
duplicated,
|
||||
} => {
|
||||
let m = record_decision(&out, &decision, duplicated)?;
|
||||
if json {
|
||||
println!("{}", m.to_json());
|
||||
} else {
|
||||
println!(
|
||||
"reuse_ratio={:.2} adapt_ratio={:.2} novel_ratio={:.2} duplication_rate={:.2}",
|
||||
m.reuse_ratio(),
|
||||
m.adapt_ratio(),
|
||||
m.novel_ratio(),
|
||||
m.duplication_rate()
|
||||
);
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
KnowledgeAction::Learn {
|
||||
task,
|
||||
failed_approach,
|
||||
failure,
|
||||
correct_approach,
|
||||
decision_title,
|
||||
decision_body,
|
||||
constraint_title,
|
||||
constraint_body,
|
||||
} => {
|
||||
let written = learn(
|
||||
&out,
|
||||
&LearnInput {
|
||||
task,
|
||||
failed_approach,
|
||||
failure,
|
||||
correct_approach,
|
||||
decision_title,
|
||||
decision_body,
|
||||
constraint_title,
|
||||
constraint_body,
|
||||
},
|
||||
)?;
|
||||
for p in written {
|
||||
println!("{}", p.display());
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
}
|
||||
}
|
||||
Commands::Find {
|
||||
query,
|
||||
path,
|
||||
out,
|
||||
limit,
|
||||
json,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let hits = find(&graph, &query, limit);
|
||||
if json {
|
||||
println!("{}", find_json(&query, &hits));
|
||||
} else {
|
||||
print!("{}", format_find_text(&query, &hits, &graph));
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
Commands::Reuse {
|
||||
task,
|
||||
path,
|
||||
out,
|
||||
preflight: do_preflight,
|
||||
min_candidates,
|
||||
allow_create_after,
|
||||
json,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let budget = ReuseBudget {
|
||||
min_candidates,
|
||||
allow_create_after,
|
||||
..ReuseBudget::default()
|
||||
};
|
||||
let result = resolve(&graph, &task, &budget);
|
||||
let _ = compile_policy(&out, &task, &result);
|
||||
if do_preflight {
|
||||
let _ = preflight(&graph, &task, &budget, Some(&out))?;
|
||||
}
|
||||
if json {
|
||||
println!("{}", reuse_json(&task, &result));
|
||||
} else {
|
||||
print!("{}", format_reuse_text(&task, &result));
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
Commands::Impact {
|
||||
paths,
|
||||
root,
|
||||
out,
|
||||
json,
|
||||
} => {
|
||||
let graph = ensure_compiled(&root, &out)?;
|
||||
let path_strs: Vec<String> = paths
|
||||
.iter()
|
||||
.map(|p| p.to_string_lossy().replace('\\', "/"))
|
||||
.collect();
|
||||
let report = impact(&graph, &path_strs);
|
||||
if json {
|
||||
println!("{}", impact_json(&report));
|
||||
} else {
|
||||
print!("{}", format_impact_text(&report));
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
Commands::Conflicts { path, out, json } => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let items = find_conflicts(&graph);
|
||||
if json {
|
||||
println!("{}", conflicts_json(&items));
|
||||
} else {
|
||||
print!("{}", format_conflicts_text(&items));
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
Commands::Stale { path, out, json } => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let items = find_stale(&graph, &path);
|
||||
if json {
|
||||
println!("{}", stale_json(&items));
|
||||
} else {
|
||||
print!("{}", format_stale_text(&items));
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
Commands::Duplicate {
|
||||
path,
|
||||
out,
|
||||
threshold,
|
||||
fail,
|
||||
json,
|
||||
} => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let pairs = find_duplicates(&graph.symbols, threshold);
|
||||
if json {
|
||||
println!(
|
||||
"{}",
|
||||
serde_json::json!({
|
||||
"threshold": threshold,
|
||||
"duplicates": pairs.iter().map(|p| serde_json::json!({
|
||||
"left": p.left,
|
||||
"right": p.right,
|
||||
"similarity": p.similarity,
|
||||
"left_resource": p.left_resource,
|
||||
"right_resource": p.right_resource,
|
||||
})).collect::<Vec<_>>(),
|
||||
})
|
||||
);
|
||||
} else {
|
||||
print!("{}", format_duplicates_text(&pairs));
|
||||
}
|
||||
if fail && !pairs.is_empty() {
|
||||
Ok(1)
|
||||
} else {
|
||||
Ok(0)
|
||||
}
|
||||
}
|
||||
Commands::Verify { path, out, json } => {
|
||||
let path = path.unwrap_or_else(|| PathBuf::from("."));
|
||||
let graph = ensure_compiled(&path, &out)?;
|
||||
let issues = verify(&graph);
|
||||
if json {
|
||||
println!("{}", verify_json(&issues));
|
||||
} else {
|
||||
print!("{}", format_verify_text(&issues));
|
||||
}
|
||||
let errors = issues.iter().filter(|i| i.severity == "error").count();
|
||||
Ok(if errors > 0 { 1 } else { 0 })
|
||||
}
|
||||
Commands::Ext { action } => {
|
||||
match action {
|
||||
ExtAction::List => list_ext()?,
|
||||
|
||||
+411
-30
@@ -358,6 +358,13 @@ impl<'a> Cursor<'a> {
|
||||
continue;
|
||||
}
|
||||
|
||||
if self.peek_is_formula_fence() {
|
||||
if let Some(stmt) = self.try_parse_meta_formula_assign()? {
|
||||
fun.body.push(stmt);
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
if is_ordered_branch(trimmed) {
|
||||
fun.body.push(self.parse_branch()?);
|
||||
continue;
|
||||
@@ -405,9 +412,10 @@ impl<'a> Cursor<'a> {
|
||||
}
|
||||
|
||||
if trimmed.starts_with("$$") {
|
||||
// Standalone meta formulas are handled before parse_simple_stmt.
|
||||
bail!(
|
||||
"{span}: formula fence must follow an empty assignment (`name` =); \
|
||||
`$$:name` binding was removed"
|
||||
"{span}: formula fence must follow an empty assignment (`name` =) \
|
||||
or include `% marqdo: var=name` inside the block"
|
||||
);
|
||||
}
|
||||
|
||||
@@ -503,7 +511,7 @@ impl<'a> Cursor<'a> {
|
||||
if crate::aliases::is_reserved_keyword(&name) {
|
||||
bail!("{span}: `{name}` is a reserved keyword");
|
||||
}
|
||||
let (value, end_line) = self.resolve_assign_rhs(&rhs, span, true)?;
|
||||
let (value, end_line) = self.resolve_assign_rhs(&name, &rhs, span, true)?;
|
||||
return Ok(Stmt::Assign {
|
||||
name,
|
||||
value,
|
||||
@@ -544,7 +552,7 @@ impl<'a> Cursor<'a> {
|
||||
if crate::aliases::is_reserved_keyword(&name) {
|
||||
bail!("{span}: `{name}` is a reserved keyword");
|
||||
}
|
||||
let (value, end_line) = self.resolve_assign_rhs(&rhs, span, true)?;
|
||||
let (value, end_line) = self.resolve_assign_rhs(&name, &rhs, span, true)?;
|
||||
Ok(Stmt::Assign {
|
||||
name,
|
||||
value,
|
||||
@@ -570,7 +578,7 @@ impl<'a> Cursor<'a> {
|
||||
return Ok(None);
|
||||
}
|
||||
let rhs = after[1..].trim().to_string();
|
||||
let (value, end_line) = self.resolve_assign_rhs(&rhs, span, false)?;
|
||||
let (value, end_line) = self.resolve_assign_rhs(&name, &rhs, span, false)?;
|
||||
Ok(Some(Stmt::Assign {
|
||||
name,
|
||||
value,
|
||||
@@ -584,6 +592,7 @@ impl<'a> Cursor<'a> {
|
||||
/// `prefer_var`: italic RHS uses variable-preferring expression syntax.
|
||||
fn resolve_assign_rhs(
|
||||
&mut self,
|
||||
assign_name: &str,
|
||||
rhs: &str,
|
||||
span: Span,
|
||||
prefer_var: bool,
|
||||
@@ -592,7 +601,9 @@ impl<'a> Cursor<'a> {
|
||||
if rhs.is_empty() {
|
||||
self.skip_blanks();
|
||||
if self.peek_is_formula_fence() {
|
||||
return self.consume_formula_fence(span);
|
||||
let (expr, end_line, meta_var) = self.consume_formula_fence(span)?;
|
||||
check_formula_meta_var(assign_name, meta_var.as_deref(), span)?;
|
||||
return Ok((expr, end_line));
|
||||
}
|
||||
if self.peek_is_code_fence() {
|
||||
return self.consume_code_fence(span);
|
||||
@@ -698,7 +709,8 @@ impl<'a> Cursor<'a> {
|
||||
))
|
||||
}
|
||||
|
||||
fn consume_formula_fence(&mut self, span: Span) -> Result<(Expr, u32)> {
|
||||
/// Consume `$$…$$`. Returns `(expr, end_line, optional var from % marqdo: var=)`.
|
||||
fn consume_formula_fence(&mut self, span: Span) -> Result<(Expr, u32, Option<String>)> {
|
||||
let open = self
|
||||
.bump()
|
||||
.ok_or_else(|| anyhow::anyhow!("{span}: expected `$$` formula fence"))?;
|
||||
@@ -707,7 +719,7 @@ impl<'a> Cursor<'a> {
|
||||
if trimmed.starts_with("$$:") || trimmed.starts_with("$$ name=") {
|
||||
bail!(
|
||||
"{open_line}:1: `$$:name` / `$$ name=` binding was removed; \
|
||||
use `name` = then a `$$…$$` fence"
|
||||
use `% marqdo: var=name` inside `$$…$$` or `name` = then a fence"
|
||||
);
|
||||
}
|
||||
// Single-line: $$body$$
|
||||
@@ -716,15 +728,21 @@ impl<'a> Cursor<'a> {
|
||||
if body.is_empty() {
|
||||
bail!("{open_line}:1: empty formula");
|
||||
}
|
||||
let (meta_var, tex) = strip_formula_marqdo_meta(body)
|
||||
.map_err(|e| anyhow::anyhow!("{open_line}:1: {e}"))?;
|
||||
if tex.is_empty() {
|
||||
bail!("{open_line}:1: empty formula");
|
||||
}
|
||||
return Ok((
|
||||
formula_fence_to_expr(body)
|
||||
formula_fence_to_expr(&tex)
|
||||
.map_err(|e| anyhow::anyhow!("{open_line}:1: formula: {e}"))?,
|
||||
open_line,
|
||||
meta_var,
|
||||
));
|
||||
}
|
||||
if trimmed != "$$" {
|
||||
bail!(
|
||||
"{open_line}:1: expected `$$` fence opener after empty assignment, got: {trimmed}"
|
||||
"{open_line}:1: expected `$$` fence opener, got: {trimmed}"
|
||||
);
|
||||
}
|
||||
let mut body_lines: Vec<String> = Vec::new();
|
||||
@@ -743,13 +761,45 @@ impl<'a> Cursor<'a> {
|
||||
if !closed {
|
||||
bail!("{open_line}:1: unclosed formula fence `$$`");
|
||||
}
|
||||
let text = body_lines.join("\n").trim().to_string();
|
||||
if text.is_empty() {
|
||||
let raw = body_lines.join("\n");
|
||||
let (meta_var, tex) = strip_formula_marqdo_meta(&raw)
|
||||
.map_err(|e| anyhow::anyhow!("{open_line}:1: {e}"))?;
|
||||
if tex.is_empty() {
|
||||
bail!("{open_line}:1: empty formula");
|
||||
}
|
||||
let expr = formula_fence_to_expr(&text)
|
||||
let expr = formula_fence_to_expr(&tex)
|
||||
.map_err(|e| anyhow::anyhow!("{open_line}:1: formula: {e}"))?;
|
||||
Ok((expr, end_line))
|
||||
Ok((expr, end_line, meta_var))
|
||||
}
|
||||
|
||||
/// Standalone `$$` with `% marqdo: var=` → Assign (no empty RHS required).
|
||||
fn try_parse_meta_formula_assign(&mut self) -> Result<Option<Stmt>> {
|
||||
if !self.peek_is_formula_fence() {
|
||||
return Ok(None);
|
||||
}
|
||||
let Some(l) = self.peek() else {
|
||||
return Ok(None);
|
||||
};
|
||||
let span = Span {
|
||||
line: l.line_no,
|
||||
col: 1,
|
||||
};
|
||||
let (value, end_line, meta_var) = self.consume_formula_fence(span)?;
|
||||
let Some(name) = meta_var else {
|
||||
bail!(
|
||||
"{span}: formula fence must follow an empty assignment (`name` =) \
|
||||
or include `% marqdo: var=name` inside the block"
|
||||
);
|
||||
};
|
||||
if crate::aliases::is_reserved_keyword(&name) {
|
||||
bail!("{span}: `{name}` is a reserved keyword");
|
||||
}
|
||||
Ok(Some(Stmt::Assign {
|
||||
name,
|
||||
value,
|
||||
span,
|
||||
end_line,
|
||||
}))
|
||||
}
|
||||
|
||||
/// GFM table after empty RHS:
|
||||
@@ -878,11 +928,7 @@ impl<'a> Cursor<'a> {
|
||||
let cond_src = strip_ordered(trimmed).unwrap();
|
||||
self.bump();
|
||||
|
||||
let condition = if cond_src == "*" || cond_src.is_empty() {
|
||||
None
|
||||
} else {
|
||||
Some(parse_expr_str(cond_src)?)
|
||||
};
|
||||
let condition = parse_branch_condition(cond_src)?;
|
||||
|
||||
let body = self.parse_indented_body(base_indent)?;
|
||||
arms.push(BranchArm { condition, body });
|
||||
@@ -904,8 +950,10 @@ impl<'a> Cursor<'a> {
|
||||
let trimmed = line.text.trim();
|
||||
let rest = trimmed.strip_prefix('-').unwrap().trim();
|
||||
|
||||
// foreach: [item](collection)
|
||||
if let Some((item, coll)) = parse_foreach_header(rest) {
|
||||
// foreach: [item](collection) or narrative sugar
|
||||
if let Some((item, coll)) = parse_foreach_header(rest)
|
||||
.or_else(|| parse_foreach_narrative(rest))
|
||||
{
|
||||
let body = self.parse_indented_body(base_indent)?;
|
||||
return Ok(Stmt::ForEach {
|
||||
item,
|
||||
@@ -931,7 +979,7 @@ impl<'a> Cursor<'a> {
|
||||
let Some(l) = self.peek() else { break };
|
||||
let ind = indent_of(&l.text);
|
||||
if ind <= parent_indent {
|
||||
// Same-indent `+`/`-` ends body (next arm / sibling).
|
||||
// Same-indent `2.` / `-` ends body (next arm / sibling).
|
||||
break;
|
||||
}
|
||||
let trimmed = l.text.trim();
|
||||
@@ -951,6 +999,39 @@ impl<'a> Cursor<'a> {
|
||||
body.push(self.parse_loop_or_err()?);
|
||||
continue;
|
||||
}
|
||||
// Same prose rights as function body (fixes arm/loop narrative escape).
|
||||
if self.peek_is_prose() {
|
||||
let line = self.bump().unwrap();
|
||||
let span = Span {
|
||||
line: line.line_no,
|
||||
col: 1,
|
||||
};
|
||||
let bits = scan_prose_line(line.text.trim_end_matches(['\r', '\n']));
|
||||
let mut end_arm = false;
|
||||
for bit in bits {
|
||||
match bit {
|
||||
ProseBit::Decl { .. } => {}
|
||||
ProseBit::BoldCode { inner, .. } => {
|
||||
body.push(self.stmt_from_bold_inner(&inner, span.clone())?);
|
||||
}
|
||||
ProseBit::ItalicReturn { inner, .. } => {
|
||||
body.push(stmt_from_italic_return(&inner, span.clone())?);
|
||||
end_arm = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
if end_arm {
|
||||
break;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if self.peek_is_formula_fence() {
|
||||
if let Some(stmt) = self.try_parse_meta_formula_assign()? {
|
||||
body.push(stmt);
|
||||
continue;
|
||||
}
|
||||
}
|
||||
let stmt = self.parse_simple_stmt()?;
|
||||
let end_arm = matches!(stmt, Stmt::Return { .. });
|
||||
body.push(stmt);
|
||||
@@ -998,26 +1079,101 @@ fn is_bare_assign_ident(s: &str) -> bool {
|
||||
true
|
||||
}
|
||||
|
||||
/// Same-line `$$body$$` → Formula or numeric matrix List; otherwise None.
|
||||
/// Same-line `$$body$$` or `$body$` → Formula; otherwise None.
|
||||
fn try_parse_inline_formula(rhs: &str) -> Result<Option<Expr>> {
|
||||
let rhs = rhs.trim();
|
||||
if !rhs.starts_with("$$") {
|
||||
return Ok(None);
|
||||
}
|
||||
if rhs.starts_with("$$:") || rhs.starts_with("$$ name=") {
|
||||
bail!(
|
||||
"`$$:name` / `$$ name=` binding was removed; use `name` = then a `$$…$$` fence"
|
||||
"`$$:name` / `$$ name=` binding was removed; use `% marqdo: var=name` \
|
||||
inside `$$…$$` or `name` = then a fence"
|
||||
);
|
||||
}
|
||||
if rhs.ends_with("$$") && rhs.len() > 4 {
|
||||
let body = rhs[2..rhs.len() - 2].trim();
|
||||
if rhs.starts_with("$$") {
|
||||
if rhs.ends_with("$$") && rhs.len() > 4 {
|
||||
let body = rhs[2..rhs.len() - 2].trim();
|
||||
if body.is_empty() {
|
||||
bail!("empty formula");
|
||||
}
|
||||
let (_meta, tex) = strip_formula_marqdo_meta(body)
|
||||
.map_err(|e| anyhow::anyhow!("{e}"))?;
|
||||
if tex.is_empty() {
|
||||
bail!("empty formula");
|
||||
}
|
||||
let expr = formula_fence_to_expr(&tex).map_err(|e| anyhow::anyhow!("formula: {e}"))?;
|
||||
return Ok(Some(expr));
|
||||
}
|
||||
bail!("incomplete inline formula (expected `$$…$$` on one line)");
|
||||
}
|
||||
// Traditional inline: $…$ (not $$)
|
||||
if rhs.starts_with('$') && rhs.ends_with('$') && rhs.len() > 2 && !rhs.starts_with("$$") {
|
||||
let body = rhs[1..rhs.len() - 1].trim();
|
||||
if body.is_empty() {
|
||||
bail!("empty formula");
|
||||
}
|
||||
if body.contains('%') && body.to_lowercase().contains("marqdo:") {
|
||||
bail!(
|
||||
"inline `$…$` must not use `% marqdo:` (breaks Markdown/TeX); \
|
||||
bind with `name` = $…$ or use a `$$` block with `% marqdo: var=`"
|
||||
);
|
||||
}
|
||||
let expr = formula_fence_to_expr(body).map_err(|e| anyhow::anyhow!("formula: {e}"))?;
|
||||
return Ok(Some(expr));
|
||||
}
|
||||
bail!("incomplete inline formula (expected `$$…$$` on one line)");
|
||||
Ok(None)
|
||||
}
|
||||
|
||||
/// Strip `% marqdo: var=name` directive lines from formula fence body.
|
||||
/// Returns `(optional var name, remaining TeX)`.
|
||||
fn strip_formula_marqdo_meta(body: &str) -> Result<(Option<String>, String), String> {
|
||||
let mut meta_var: Option<String> = None;
|
||||
let mut out: Vec<&str> = Vec::new();
|
||||
for line in body.lines() {
|
||||
let t = line.trim();
|
||||
if let Some(rest) = t.strip_prefix('%') {
|
||||
let rest = rest.trim_start();
|
||||
if rest.to_ascii_lowercase().starts_with("marqdo:") {
|
||||
let after = rest["marqdo:".len()..].trim_start();
|
||||
let mut got_var = false;
|
||||
for part in after.split_whitespace() {
|
||||
if let Some(v) = part.strip_prefix("var=") {
|
||||
if v.is_empty() {
|
||||
return Err("% marqdo: var= requires a name".into());
|
||||
}
|
||||
if !is_bare_assign_ident(v) {
|
||||
return Err(format!("invalid marqdo var name `{v}`"));
|
||||
}
|
||||
if meta_var.as_deref() == Some(v) || meta_var.is_none() {
|
||||
meta_var = Some(v.to_string());
|
||||
} else {
|
||||
return Err(format!(
|
||||
"conflicting % marqdo: var= ({} vs {v})",
|
||||
meta_var.as_deref().unwrap_or("")
|
||||
));
|
||||
}
|
||||
got_var = true;
|
||||
} else {
|
||||
return Err(format!("unknown marqdo key `{part}` (only var= is supported)"));
|
||||
}
|
||||
}
|
||||
if !got_var {
|
||||
return Err("% marqdo: requires var=<name>".into());
|
||||
}
|
||||
continue; // strip directive line
|
||||
}
|
||||
}
|
||||
out.push(line);
|
||||
}
|
||||
Ok((meta_var, out.join("\n").trim().to_string()))
|
||||
}
|
||||
|
||||
fn check_formula_meta_var(assign_name: &str, meta: Option<&str>, span: Span) -> Result<()> {
|
||||
match meta {
|
||||
None => Ok(()),
|
||||
Some(v) if v == assign_name => Ok(()),
|
||||
Some(v) => bail!(
|
||||
"{span}: formula `% marqdo: var={v}` conflicts with assignment `{assign_name}`"
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
fn formula_fence_to_expr(body: &str) -> Result<Expr, String> {
|
||||
@@ -1112,6 +1268,148 @@ fn parse_foreach_header(rest: &str) -> Option<(String, String)> {
|
||||
Some((item, coll))
|
||||
}
|
||||
|
||||
/// Narrative foreach sugar (recommended remains `- [item](coll)`).
|
||||
/// - ZH: `对`xs`的每一项`项`` optional `遍历`
|
||||
/// - EN: `for each `item` in `xs``
|
||||
fn parse_foreach_narrative(rest: &str) -> Option<(String, String)> {
|
||||
let rest = rest.trim();
|
||||
if let Some(after) = rest.strip_prefix('对') {
|
||||
let (coll, after) = take_backtick_token(after.trim_start())?;
|
||||
let after = after.trim_start().strip_prefix("的每一项")?;
|
||||
let (item, after) = take_backtick_token(after.trim_start())?;
|
||||
let after = after
|
||||
.trim()
|
||||
.trim_end_matches('。')
|
||||
.trim();
|
||||
let after = after.strip_prefix("遍历").unwrap_or(after).trim();
|
||||
if after.is_empty() {
|
||||
return Some((item, coll));
|
||||
}
|
||||
return None;
|
||||
}
|
||||
let lower = rest.to_ascii_lowercase();
|
||||
let Some(idx) = lower.find("for each ") else {
|
||||
return None;
|
||||
};
|
||||
if idx != 0 {
|
||||
return None;
|
||||
}
|
||||
let after = rest["for each ".len()..].trim_start();
|
||||
let (item, after) = take_backtick_token(after)?;
|
||||
let after = after.trim_start();
|
||||
let after_l = after.to_ascii_lowercase();
|
||||
if !after_l.starts_with("in ") && !after_l.starts_with("in\t") {
|
||||
// require ` in `
|
||||
let Some(in_at) = after_l.find("in ") else {
|
||||
return None;
|
||||
};
|
||||
if in_at != 0 {
|
||||
return None;
|
||||
}
|
||||
}
|
||||
let after = after["in ".len()..].trim_start();
|
||||
let (coll, after) = take_backtick_token(after)?;
|
||||
if after.trim().is_empty() {
|
||||
return Some((item, coll));
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn take_backtick_token(s: &str) -> Option<(String, &str)> {
|
||||
let s = s.trim_start();
|
||||
if !s.starts_with('`') {
|
||||
return None;
|
||||
}
|
||||
let end = s[1..].find('`')?;
|
||||
let name = s[1..1 + end].to_string();
|
||||
if name.is_empty() {
|
||||
return None;
|
||||
}
|
||||
Some((name, &s[1 + end + 1..]))
|
||||
}
|
||||
|
||||
/// Branch arm condition: expr, bold code, narrative (当`n`大于 0 时), or else `*`.
|
||||
fn parse_branch_condition(cond_src: &str) -> Result<Option<Expr>> {
|
||||
let t = cond_src.trim();
|
||||
if t.is_empty() || t == "*" {
|
||||
return Ok(None);
|
||||
}
|
||||
// "否则 *" / "else *"
|
||||
if let Some(before) = t.strip_suffix('*') {
|
||||
let before = before.trim();
|
||||
if before.is_empty()
|
||||
|| before == "否则"
|
||||
|| before == "其它"
|
||||
|| before == "其他"
|
||||
|| before.eq_ignore_ascii_case("else")
|
||||
|| before.eq_ignore_ascii_case("otherwise")
|
||||
{
|
||||
return Ok(None);
|
||||
}
|
||||
}
|
||||
if let Ok(e) = parse_expr_str(t) {
|
||||
return Ok(Some(e));
|
||||
}
|
||||
if let Some(inner) = extract_first_bold_inner(t) {
|
||||
if let Ok(e) = parse_expr_str(inner.trim()) {
|
||||
return Ok(Some(e));
|
||||
}
|
||||
}
|
||||
if let Some(e) = try_narrative_condition(t) {
|
||||
return Ok(Some(e));
|
||||
}
|
||||
bail!(
|
||||
"branch condition: cannot parse `{t}` \
|
||||
(use an expression, **`n` > 0**, or 当`n`大于 0 时)"
|
||||
)
|
||||
}
|
||||
|
||||
fn extract_first_bold_inner(s: &str) -> Option<&str> {
|
||||
let start = s.find("**")?;
|
||||
let rest = &s[start + 2..];
|
||||
let end = rest.find("**")?;
|
||||
Some(&rest[..end])
|
||||
}
|
||||
|
||||
fn try_narrative_condition(s: &str) -> Option<Expr> {
|
||||
let mut s = s.trim();
|
||||
for p in ["当且仅当", "当", "若", "如果"] {
|
||||
if let Some(r) = s.strip_prefix(p) {
|
||||
s = r.trim_start();
|
||||
break;
|
||||
}
|
||||
}
|
||||
let lower = s.to_ascii_lowercase();
|
||||
if let Some(r) = lower.strip_prefix("when ") {
|
||||
let _ = r;
|
||||
s = s[5..].trim_start();
|
||||
} else if let Some(r) = lower.strip_prefix("if ") {
|
||||
let _ = r;
|
||||
s = s[3..].trim_start();
|
||||
}
|
||||
for suf in ["的话", "时", "则"] {
|
||||
if let Some(r) = s.strip_suffix(suf) {
|
||||
s = r.trim_end();
|
||||
}
|
||||
}
|
||||
let mut mapped = s.to_string();
|
||||
let replacements = [
|
||||
("大于等于", ">="),
|
||||
("小于等于", "<="),
|
||||
("不等于", "!="),
|
||||
("等于", "=="),
|
||||
("大于", ">"),
|
||||
("小于", "<"),
|
||||
];
|
||||
for (zh, op) in replacements {
|
||||
if mapped.contains(zh) {
|
||||
mapped = mapped.replace(zh, op);
|
||||
break;
|
||||
}
|
||||
}
|
||||
parse_expr_str(mapped.trim()).ok()
|
||||
}
|
||||
|
||||
fn parse_heading(trimmed: &str) -> Option<(u8, &str)> {
|
||||
if !trimmed.starts_with('#') {
|
||||
return None;
|
||||
@@ -1882,6 +2180,89 @@ mod tests {
|
||||
use super::*;
|
||||
use crate::ast::Stmt;
|
||||
|
||||
#[test]
|
||||
fn parse_formula_meta_var_standalone() {
|
||||
let src = "# main\n\n$$\n% marqdo: var=f\nx^2 - 2\n$$\n";
|
||||
let m = parse_source(src).unwrap();
|
||||
match &m.functions[0].body[0] {
|
||||
Stmt::Assign { name, value, .. } => {
|
||||
assert_eq!(name, "f");
|
||||
assert!(matches!(value, Expr::Formula(_)));
|
||||
}
|
||||
other => panic!("expected formula assign, got {other:?}"),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_formula_meta_conflicts_with_assign() {
|
||||
let src = "# main\n\n`f` =\n$$\n% marqdo: var=g\nx\n$$\n";
|
||||
let err = parse_source(src).unwrap_err().to_string();
|
||||
assert!(
|
||||
err.contains("conflicts") || err.contains("var=g"),
|
||||
"{err}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_foreach_narrative_zh_en() {
|
||||
let src = "# main\n\n- 对`xs`的每一项`项`\n > print text=`项`\n\n- for each `item` in `ys`\n > print text=`item`\n";
|
||||
let m = parse_source(src).unwrap();
|
||||
match &m.functions[0].body[0] {
|
||||
Stmt::ForEach { item, collection, .. } => {
|
||||
assert_eq!(item, "项");
|
||||
assert_eq!(collection, "xs");
|
||||
}
|
||||
other => panic!("zh foreach: {other:?}"),
|
||||
}
|
||||
match &m.functions[0].body[1] {
|
||||
Stmt::ForEach { item, collection, .. } => {
|
||||
assert_eq!(item, "item");
|
||||
assert_eq!(collection, "ys");
|
||||
}
|
||||
other => panic!("en foreach: {other:?}"),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn branch_arm_prose_stays_inside_arm() {
|
||||
let src = include_str!("../../tests/markup-v03/branch-arm-prose.mq.md");
|
||||
let m = parse_source(src).unwrap();
|
||||
let main = &m.functions[0];
|
||||
let branches: Vec<_> = main
|
||||
.body
|
||||
.iter()
|
||||
.filter(|s| matches!(s, Stmt::Branch { .. }))
|
||||
.collect();
|
||||
assert_eq!(
|
||||
branches.len(),
|
||||
1,
|
||||
"expected one Branch, body={:?}",
|
||||
main.body
|
||||
);
|
||||
match &main.body[1] {
|
||||
Stmt::Branch { arms, .. } => {
|
||||
assert_eq!(arms.len(), 2, "arms={arms:?}");
|
||||
assert!(
|
||||
!arms[0].body.is_empty(),
|
||||
"then arm must contain prose stmts: {:?}",
|
||||
arms[0].body
|
||||
);
|
||||
assert!(
|
||||
!arms[1].body.is_empty(),
|
||||
"else arm must contain prose stmts: {:?}",
|
||||
arms[1].body
|
||||
);
|
||||
}
|
||||
other => panic!("expected Branch as body[1] after assign, got {other:?}"),
|
||||
}
|
||||
// No Call/Assign print siblings after the branch
|
||||
assert!(
|
||||
!main.body.iter().skip(2).any(|s| matches!(s, Stmt::Call { .. } | Stmt::Assign { .. })),
|
||||
"prose escaped branch: {:?}",
|
||||
main.body
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parse_hello() {
|
||||
let src = include_str!("../../tests/structure/hello.mq.md");
|
||||
|
||||
+1155
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
+671
-4
@@ -330,6 +330,236 @@ section.block > h2 {
|
||||
background: transparent;
|
||||
padding-left: calc(1.1rem - 2px);
|
||||
}
|
||||
/* Document surface (Browse Structure) */
|
||||
.document-surface {
|
||||
padding: 0.5rem 1rem 1.25rem;
|
||||
color: var(--ink);
|
||||
line-height: 1.55;
|
||||
}
|
||||
.doc-imports { margin: 0 0 0.85rem; }
|
||||
.doc-fun {
|
||||
margin: 1.1rem 0 0.65rem;
|
||||
padding-bottom: 0.35rem;
|
||||
border-bottom: 1px solid var(--line);
|
||||
}
|
||||
.doc-fun-title {
|
||||
margin: 0;
|
||||
font-size: 1.15rem;
|
||||
font-weight: 650;
|
||||
letter-spacing: -0.01em;
|
||||
}
|
||||
.doc-fun-bar {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
align-items: center;
|
||||
gap: 0.5rem 1rem;
|
||||
}
|
||||
.call-picker-label {
|
||||
font-size: 0.78rem;
|
||||
color: var(--muted);
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.35rem;
|
||||
}
|
||||
.call-picker, .loop-picker {
|
||||
font-size: 0.78rem;
|
||||
padding: 0.2rem 0.4rem;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 8px;
|
||||
background: var(--surface);
|
||||
color: var(--ink);
|
||||
}
|
||||
.loop-picker-label {
|
||||
font-size: 0.78rem;
|
||||
color: var(--muted);
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.35rem;
|
||||
}
|
||||
li.doc-list-meta {
|
||||
list-style: none;
|
||||
margin: 0.25rem 0 0.5rem;
|
||||
margin-left: -1.25rem;
|
||||
}
|
||||
.doc-block { position: relative; margin: 0.55rem 0 0.85rem; }
|
||||
.doc-block > .annot-leaders {
|
||||
position: absolute;
|
||||
inset: 0;
|
||||
pointer-events: none;
|
||||
overflow: visible;
|
||||
z-index: 1; /* below .annot-chips */
|
||||
}
|
||||
.doc-block > .annot-leaders svg {
|
||||
position: absolute;
|
||||
left: 0;
|
||||
top: 0;
|
||||
overflow: visible;
|
||||
}
|
||||
.doc-block.is-keyed > .annot-leaders { display: none; }
|
||||
.doc-block.doc-exec[style*="--doc-indent"] {
|
||||
margin-left: calc(var(--doc-indent, 1) * 1.5rem);
|
||||
}
|
||||
.doc-prose { color: var(--ink); }
|
||||
.doc-prose > :first-child { margin-top: 0; }
|
||||
.doc-prose > :last-child { margin-bottom: 0; }
|
||||
.doc-line { margin: 0.15rem 0; }
|
||||
.doc-prose-line { white-space: pre-wrap; }
|
||||
.doc-stmt, .doc-call, .doc-cond {
|
||||
font-family: var(--mono);
|
||||
font-size: 0.92em;
|
||||
}
|
||||
.mq-call-gt { color: var(--muted); margin-right: 0.25rem; }
|
||||
.mq-else { font-family: var(--mono); color: var(--muted); font-style: italic; }
|
||||
.doc-table-wrap { overflow-x: auto; }
|
||||
.doc-table {
|
||||
border-collapse: collapse;
|
||||
width: auto;
|
||||
min-width: 12rem;
|
||||
font-size: 0.92rem;
|
||||
margin: 0.35rem 0;
|
||||
}
|
||||
.doc-table th, .doc-table td {
|
||||
border: 1px solid var(--line);
|
||||
padding: 0.35rem 0.7rem;
|
||||
text-align: left;
|
||||
}
|
||||
.doc-table th {
|
||||
background: var(--fill);
|
||||
font-weight: 600;
|
||||
}
|
||||
ul.doc-loop, ol.doc-branch {
|
||||
margin: 0.5rem 0 0.75rem;
|
||||
padding-left: calc(var(--doc-indent, 1) * 1.5rem + 1.25rem);
|
||||
}
|
||||
.doc-list-item { margin: 0.45rem 0; }
|
||||
.doc-list-head { font-family: var(--mono); font-size: 0.92em; }
|
||||
.doc-list-body {
|
||||
margin: 0.35rem 0 0.2rem;
|
||||
padding-left: 1.5rem;
|
||||
border-left: 2px solid var(--line);
|
||||
}
|
||||
.doc-list-item.arm-taken {
|
||||
border-left: 3px solid #bf5af2;
|
||||
padding-left: 0.55rem;
|
||||
margin-left: -0.15rem;
|
||||
}
|
||||
.doc-list-item.arm-taken > .doc-list-head { font-weight: 600; }
|
||||
.doc-list-item.arm-miss { opacity: 0.45; }
|
||||
.doc-code {
|
||||
font-family: var(--mono);
|
||||
font-size: 0.9em;
|
||||
white-space: pre-wrap;
|
||||
}
|
||||
.mq-anchor {
|
||||
background: transparent;
|
||||
color: inherit;
|
||||
padding: 0 0.05em;
|
||||
border-radius: 0;
|
||||
border-bottom: 2px solid var(--line-strong);
|
||||
font-style: normal;
|
||||
font-weight: inherit;
|
||||
cursor: default;
|
||||
}
|
||||
.mq-anchor.mq-decl {
|
||||
border-bottom-color: #5ac8fa;
|
||||
font-family: var(--mono);
|
||||
font-size: 0.95em;
|
||||
}
|
||||
.mq-anchor.mq-code {
|
||||
border-bottom-color: #ff9f0a;
|
||||
font-family: var(--mono);
|
||||
font-size: 0.95em;
|
||||
font-weight: 600;
|
||||
}
|
||||
.mq-anchor.mq-return {
|
||||
border-bottom-color: #30d158;
|
||||
font-family: var(--mono);
|
||||
font-size: 0.95em;
|
||||
font-style: italic;
|
||||
}
|
||||
.mq-anchor.is-focus { background: rgba(0,0,0,0.04); }
|
||||
.annot-band {
|
||||
position: relative;
|
||||
margin: 0.55rem 0 0.15rem;
|
||||
min-height: 1.6rem;
|
||||
padding-top: 1.15rem; /* room for mid→mid leaders (rail + stub) */
|
||||
z-index: 1;
|
||||
}
|
||||
/* Band-local leaders kept for keyed fallback; geometry uses .doc-block > .annot-leaders */
|
||||
.annot-band > .annot-leaders { display: none; }
|
||||
.annot-leader {
|
||||
fill: none;
|
||||
stroke-width: 1.5;
|
||||
stroke-linecap: round;
|
||||
stroke-linejoin: round;
|
||||
pointer-events: none;
|
||||
}
|
||||
.annot-chips {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 0.45rem 0.7rem;
|
||||
position: relative;
|
||||
z-index: 3; /* chips above leaders */
|
||||
}
|
||||
.annot-chip {
|
||||
display: inline-flex;
|
||||
align-items: baseline;
|
||||
gap: 0.35rem;
|
||||
max-width: 100%;
|
||||
margin: 0;
|
||||
padding: 0.22rem 0.5rem;
|
||||
border: 1px solid var(--line);
|
||||
border-left-width: 3px;
|
||||
border-radius: 8px;
|
||||
background: var(--fill);
|
||||
color: var(--ink);
|
||||
font-family: var(--mono);
|
||||
font-size: 0.72rem;
|
||||
cursor: pointer;
|
||||
text-align: left;
|
||||
}
|
||||
/* Author `display:inline-flex` must not defeat frame filtering. */
|
||||
.annot-chip[hidden],
|
||||
.annot-chip.is-frame-hidden {
|
||||
display: none !important;
|
||||
}
|
||||
.annot-chip:hover,
|
||||
.annot-chip.is-focus { background: #fff; }
|
||||
.annot-chip.annot-bind { border-left-color: #5ac8fa; }
|
||||
.annot-chip.annot-return { border-left-color: #30d158; }
|
||||
.annot-chip.annot-call,
|
||||
.annot-chip.annot-expr,
|
||||
.annot-chip.annot-code { border-left-color: #ff9f0a; }
|
||||
.annot-chip.annot-branch { border-left-color: #bf5af2; }
|
||||
.annot-chip.annot-loop { border-left-color: #64d2ff; }
|
||||
.annot-chip.annot-writeback { border-left-color: #8e8e93; }
|
||||
.annot-chip.annot-chip-overflow { display: none !important; }
|
||||
.annot-band.is-expanded .annot-chip.annot-chip-overflow:not([hidden]):not(.is-frame-hidden) {
|
||||
display: inline-flex !important;
|
||||
}
|
||||
.annot-label { color: var(--muted); font-weight: 600; }
|
||||
.annot-value { color: var(--ink); word-break: break-word; }
|
||||
.annot-more {
|
||||
border: 1px dashed var(--line);
|
||||
border-radius: 8px;
|
||||
background: transparent;
|
||||
color: var(--muted);
|
||||
font-size: 0.72rem;
|
||||
padding: 0.22rem 0.45rem;
|
||||
cursor: pointer;
|
||||
}
|
||||
.annot-band.is-keyed .annot-chip::before,
|
||||
.doc-block.is-keyed .annot-chip::before {
|
||||
content: attr(data-annot-key) " ";
|
||||
color: var(--muted);
|
||||
}
|
||||
@media (max-width: 640px) {
|
||||
.annot-band { padding-top: 0.25rem; }
|
||||
.doc-block > .annot-leaders { display: none; }
|
||||
}
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
.doc-block > .annot-leaders { display: none; }
|
||||
}
|
||||
.badge {
|
||||
display: inline-block;
|
||||
font-family: var(--mono);
|
||||
@@ -365,6 +595,15 @@ section.block > h2 {
|
||||
font-size: 0.65em;
|
||||
opacity: 0.7;
|
||||
}
|
||||
.chip .chip-val {
|
||||
font-weight: 500;
|
||||
opacity: 0.78;
|
||||
font-family: var(--mono);
|
||||
font-size: 0.92em;
|
||||
}
|
||||
.chip .chip-val:empty {
|
||||
display: none;
|
||||
}
|
||||
.nested {
|
||||
margin: 0.45rem 0 0.15rem 0.15rem;
|
||||
padding-left: 0.85rem;
|
||||
@@ -735,6 +974,9 @@ section.block > h2 {
|
||||
border-left: 3px solid #2563eb;
|
||||
background: #f8fafc;
|
||||
}
|
||||
.output-card.output-card-image {
|
||||
border-left-color: #0d9488;
|
||||
}
|
||||
.output-card .wb-badges {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
@@ -750,6 +992,58 @@ section.block > h2 {
|
||||
white-space: pre-wrap;
|
||||
color: #0f172a;
|
||||
}
|
||||
.wb-figure {
|
||||
margin: 0.5rem 0 0;
|
||||
padding: 0;
|
||||
}
|
||||
.wb-image {
|
||||
display: block;
|
||||
max-width: 100%;
|
||||
height: auto;
|
||||
border-radius: 6px;
|
||||
border: 1px solid var(--line);
|
||||
background: #fff;
|
||||
}
|
||||
.wb-image-url {
|
||||
margin: 0.35rem 0 0;
|
||||
font: 0.75rem/1.35 var(--mono);
|
||||
color: var(--muted);
|
||||
word-break: break-all;
|
||||
}
|
||||
.doc-writeback {
|
||||
margin: 0.35rem 0;
|
||||
padding: 0.4rem 0.55rem;
|
||||
border-radius: 8px;
|
||||
border: 1px dashed #94a3b8;
|
||||
background: #f1f5f9;
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 0.4rem 0.65rem;
|
||||
align-items: baseline;
|
||||
}
|
||||
.doc-writeback[data-wb-kind="image"] {
|
||||
border-color: #0d9488;
|
||||
background: #f0fdfa;
|
||||
}
|
||||
.wb-source-badge {
|
||||
font: 0.68rem/1.2 var(--sans);
|
||||
letter-spacing: 0.04em;
|
||||
text-transform: uppercase;
|
||||
color: #334155;
|
||||
background: #e2e8f0;
|
||||
padding: 0.12rem 0.4rem;
|
||||
border-radius: 4px;
|
||||
}
|
||||
.doc-writeback[data-wb-kind="image"] .wb-source-badge {
|
||||
background: #ccfbf1;
|
||||
color: #115e59;
|
||||
}
|
||||
.wb-source-text {
|
||||
font: 0.82rem/1.4 var(--mono);
|
||||
color: #0f172a;
|
||||
white-space: pre-wrap;
|
||||
word-break: break-all;
|
||||
}
|
||||
.wb-outline {
|
||||
margin-top: 0.75rem;
|
||||
padding-top: 0.75rem;
|
||||
@@ -1048,6 +1342,16 @@ section.block > h2 {
|
||||
align-items: center;
|
||||
gap: 0.4rem;
|
||||
}
|
||||
.code-foot {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
align-items: center;
|
||||
gap: 0.45rem 0.65rem;
|
||||
padding: 0.5rem 0.85rem;
|
||||
border-top: 1px solid var(--line);
|
||||
background: #fafafa;
|
||||
}
|
||||
.code-foot .code-actions { margin-left: auto; }
|
||||
.code-cmd {
|
||||
min-width: 9rem;
|
||||
max-width: 16rem;
|
||||
@@ -1084,6 +1388,7 @@ section.block > h2 {
|
||||
background: #1e1e1e;
|
||||
color: #d4d4d4;
|
||||
font: 0.82rem/1.45 var(--mono);
|
||||
min-height: 2.4rem;
|
||||
}
|
||||
.code-body code {
|
||||
font: inherit;
|
||||
@@ -1287,17 +1592,23 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
function initForeignCards() {{
|
||||
var live = !!window.MARQDO_VIEW_LIVE;
|
||||
document.querySelectorAll(".code-card").forEach(function (card) {{
|
||||
var foot = card.querySelector(".code-foot");
|
||||
var btn = card.querySelector(".code-run");
|
||||
var cmd = card.querySelector(".code-cmd");
|
||||
var out = card.querySelector(".code-out");
|
||||
var body = card.querySelector(".code-body code");
|
||||
if (!btn || !out || !body) return;
|
||||
// Narrative ```text``` cards have no Run chrome — leave as-is.
|
||||
if (!btn) return;
|
||||
if (!live) {{
|
||||
btn.disabled = true;
|
||||
btn.title = "Run is available in live marqdo view";
|
||||
if (cmd) cmd.disabled = true;
|
||||
// Static: hide fake Run (view-static-interactive D5 / view-prose-annot-gaps P4).
|
||||
if (foot) foot.hidden = true;
|
||||
else {{
|
||||
btn.hidden = true;
|
||||
if (cmd) cmd.hidden = true;
|
||||
}}
|
||||
return;
|
||||
}}
|
||||
if (!out || !body) return;
|
||||
btn.addEventListener("click", function () {{
|
||||
btn.disabled = true;
|
||||
out.hidden = false;
|
||||
@@ -1740,6 +2051,19 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
initVarsPanel();
|
||||
}}
|
||||
}}
|
||||
if (typeof ev.structure_html === "string" && ev.structure_html) {{
|
||||
var structEl = document.getElementById("structure");
|
||||
if (structEl) {{
|
||||
structEl.innerHTML = ev.structure_html;
|
||||
initAnnotLeaders();
|
||||
initCallPickers();
|
||||
initLoopPickers();
|
||||
}}
|
||||
}}
|
||||
if (typeof ev.trace_json === "string" && ev.trace_json) {{
|
||||
var tr = document.getElementById("mq-view-trace");
|
||||
if (tr) tr.textContent = ev.trace_json;
|
||||
}}
|
||||
}}
|
||||
}}
|
||||
}}
|
||||
@@ -1938,18 +2262,352 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
renderMath(panel);
|
||||
}}
|
||||
|
||||
function readViewTrace() {{
|
||||
var el = document.getElementById("mq-view-trace");
|
||||
if (!el) return null;
|
||||
try {{ return JSON.parse(el.textContent || "{{}}"); }} catch (e) {{ return null; }}
|
||||
}}
|
||||
|
||||
function parseArgsBrief(brief) {{
|
||||
var out = {{}};
|
||||
if (!brief) return out;
|
||||
String(brief).split(", ").forEach(function (part) {{
|
||||
var i = part.indexOf("=");
|
||||
if (i <= 0) return;
|
||||
out[part.slice(0, i)] = part.slice(i + 1);
|
||||
}});
|
||||
return out;
|
||||
}}
|
||||
|
||||
function applyParamChipValues(fnName, callId, trace) {{
|
||||
if (!trace || !Array.isArray(trace.calls)) return;
|
||||
var brief = "";
|
||||
for (var i = 0; i < trace.calls.length; i++) {{
|
||||
var c = trace.calls[i];
|
||||
if (String(c.call_id) === String(callId) && String(c.fn || "") === String(fnName)) {{
|
||||
brief = c.args_brief || "";
|
||||
break;
|
||||
}}
|
||||
}}
|
||||
var args = parseArgsBrief(brief);
|
||||
document.querySelectorAll('.chip[data-fn="' + fnName + '"][data-param-name]').forEach(function (chip) {{
|
||||
var name = chip.getAttribute("data-param-name") || "";
|
||||
var slot = chip.querySelector(".chip-val");
|
||||
if (!slot) return;
|
||||
var v = args[name];
|
||||
slot.textContent = v ? ("=" + v) : "";
|
||||
}});
|
||||
}}
|
||||
|
||||
var MAX_VISIBLE_ANNOTS = 4;
|
||||
|
||||
function setFrameHidden(el, hide) {{
|
||||
el.hidden = !!hide;
|
||||
if (hide) el.classList.add("is-frame-hidden");
|
||||
else el.classList.remove("is-frame-hidden");
|
||||
}}
|
||||
|
||||
/** After frame filter: overflow only among chips visible in the selected frame. */
|
||||
function recomputeAnnotOverflow(scope) {{
|
||||
var root = scope || document.getElementById("structure") || document;
|
||||
root.querySelectorAll("[data-annot-band]").forEach(function (band) {{
|
||||
band.classList.remove("is-expanded");
|
||||
var chips = band.querySelectorAll(".annot-chip");
|
||||
var visible = [];
|
||||
chips.forEach(function (chip) {{
|
||||
chip.classList.remove("annot-chip-overflow");
|
||||
if (chip.hidden || chip.classList.contains("is-frame-hidden")) return;
|
||||
visible.push(chip);
|
||||
}});
|
||||
var overflow = 0;
|
||||
visible.forEach(function (chip, i) {{
|
||||
if (i >= MAX_VISIBLE_ANNOTS) {{
|
||||
chip.classList.add("annot-chip-overflow");
|
||||
overflow++;
|
||||
}}
|
||||
}});
|
||||
var more = band.querySelector("[data-annot-more]");
|
||||
if (more) {{
|
||||
if (overflow > 0) {{
|
||||
more.hidden = false;
|
||||
more.textContent = "+" + overflow;
|
||||
}} else {{
|
||||
more.hidden = true;
|
||||
}}
|
||||
}}
|
||||
}});
|
||||
}}
|
||||
|
||||
/** Source structure always stays visible; only chips + arm classes follow the frame. */
|
||||
function initCallPickers() {{
|
||||
document.querySelectorAll(".call-picker").forEach(function (sel) {{
|
||||
function apply() {{
|
||||
var callId = String(sel.value || "");
|
||||
var fnName = String(sel.getAttribute("data-fn") || "");
|
||||
var allowed = {{}};
|
||||
Array.prototype.forEach.call(sel.options, function (o) {{
|
||||
allowed[String(o.value)] = true;
|
||||
}});
|
||||
var root = document.getElementById("structure") || document;
|
||||
// Only touch chips whose call_id belongs to this function's calls.
|
||||
root.querySelectorAll(".annot-chip[data-call-id]").forEach(function (chip) {{
|
||||
var cid = String(chip.getAttribute("data-call-id") || "");
|
||||
if (!allowed[cid]) return;
|
||||
setFrameHidden(chip, cid !== callId);
|
||||
}});
|
||||
var trace = readViewTrace();
|
||||
applyParamChipValues(fnName, callId, trace);
|
||||
if (trace && Array.isArray(trace.events)) {{
|
||||
var takenByLine = {{}};
|
||||
trace.events.forEach(function (ev) {{
|
||||
if (ev.kind === "branch" && String(ev.call_id) === callId && ev.arm_index != null) {{
|
||||
takenByLine[ev.line] = ev.arm_index;
|
||||
}}
|
||||
}});
|
||||
root.querySelectorAll("ol.doc-branch").forEach(function (ol) {{
|
||||
var line = parseInt(ol.getAttribute("data-line") || "0", 10);
|
||||
var taken = takenByLine[line];
|
||||
if (taken === undefined) return;
|
||||
ol.querySelectorAll(":scope > li.doc-list-item[data-arm-index]").forEach(function (li) {{
|
||||
var idx = parseInt(li.getAttribute("data-arm-index") || "-1", 10);
|
||||
li.classList.remove("arm-taken", "arm-miss");
|
||||
if (idx === taken) li.classList.add("arm-taken");
|
||||
else li.classList.add("arm-miss");
|
||||
}});
|
||||
}});
|
||||
}}
|
||||
recomputeAnnotOverflow(root);
|
||||
initAnnotLeaders();
|
||||
}}
|
||||
if (sel.dataset.bound !== "1") {{
|
||||
sel.dataset.bound = "1";
|
||||
sel.addEventListener("change", apply);
|
||||
}}
|
||||
apply();
|
||||
}});
|
||||
}}
|
||||
|
||||
function initLoopPickers() {{
|
||||
document.querySelectorAll(".loop-picker").forEach(function (sel) {{
|
||||
function apply() {{
|
||||
var iter = String(sel.value || "");
|
||||
var loopId = String(sel.getAttribute("data-loop-id") || "");
|
||||
var ul = sel.closest("ul.doc-loop");
|
||||
var scope = ul || document.getElementById("structure");
|
||||
if (!scope) return;
|
||||
// Only the selected iteration's chips; structure source stays visible.
|
||||
scope.querySelectorAll(".annot-chip").forEach(function (chip) {{
|
||||
var lid = chip.getAttribute("data-loop-id");
|
||||
var chipIter = chip.getAttribute("data-iter");
|
||||
if (loopId && lid && String(lid) !== loopId) return;
|
||||
if (chipIter == null) {{
|
||||
// No data-iter: leave alone (foreach uses BindRef chips; while may have one summary).
|
||||
return;
|
||||
}}
|
||||
// Chips with data-iter but no loop-id still filter by iter inside this ul.
|
||||
if (lid && loopId && String(lid) !== loopId) return;
|
||||
setFrameHidden(chip, String(chipIter) !== iter);
|
||||
}});
|
||||
recomputeAnnotOverflow(scope);
|
||||
initAnnotLeaders();
|
||||
}}
|
||||
if (sel.dataset.bound !== "1") {{
|
||||
sel.dataset.bound = "1";
|
||||
sel.addEventListener("change", apply);
|
||||
}}
|
||||
apply();
|
||||
}});
|
||||
}}
|
||||
|
||||
function ensureBlockLeaders(block) {{
|
||||
var leaders = block.querySelector(":scope > .annot-leaders");
|
||||
if (!leaders) {{
|
||||
leaders = document.createElement("div");
|
||||
leaders.className = "annot-leaders";
|
||||
leaders.setAttribute("aria-hidden", "true");
|
||||
block.insertBefore(leaders, block.firstChild);
|
||||
}}
|
||||
return leaders;
|
||||
}}
|
||||
|
||||
function leaderColor(kind) {{
|
||||
if (kind === "bind") return "#5ac8fa";
|
||||
if (kind === "return") return "#30d158";
|
||||
if (kind === "call" || kind === "expr" || kind === "code") return "#ff9f0a";
|
||||
if (kind === "branch") return "#bf5af2";
|
||||
if (kind === "loop") return "#64d2ff";
|
||||
return "#8e8e93";
|
||||
}}
|
||||
|
||||
function initAnnotLeaders() {{
|
||||
var bands = document.querySelectorAll("[data-annot-band]");
|
||||
if (!bands.length) return;
|
||||
var reduce = window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
|
||||
var narrow = window.matchMedia && window.matchMedia("(max-width: 640px)").matches;
|
||||
|
||||
function layoutBand(band) {{
|
||||
var block = band.closest(".doc-block");
|
||||
if (!block) return;
|
||||
var leaders = ensureBlockLeaders(block);
|
||||
leaders.innerHTML = "";
|
||||
var chipsEl = band.querySelector(".annot-chips");
|
||||
var chips = Array.prototype.slice.call(
|
||||
band.querySelectorAll(".annot-chip:not(.annot-chip-overflow):not([hidden]):not(.is-frame-hidden)")
|
||||
);
|
||||
// Pair chips with anchors; reorder DOM left→right under underlines so
|
||||
// L-leaders do not cross (crowded reverse order looked like missing lines).
|
||||
var items = [];
|
||||
chips.forEach(function (chip) {{
|
||||
var id = chip.getAttribute("data-annot-id") || "";
|
||||
var kind = chip.getAttribute("data-annot-kind") || "";
|
||||
var anchor = id
|
||||
? (block.querySelector('.mq-anchor[data-annot-id="' + id + '"]')
|
||||
|| document.querySelector('.mq-anchor[data-annot-id="' + id + '"]'))
|
||||
: null;
|
||||
// Fallback: match mark kind on this block (frame chips may share a span).
|
||||
if (!anchor) {{
|
||||
var cls = kind === "bind" ? "mq-decl"
|
||||
: kind === "return" ? "mq-return"
|
||||
: (kind === "call" || kind === "expr" || kind === "code") ? "mq-code"
|
||||
: "";
|
||||
if (cls) anchor = block.querySelector(".mq-anchor." + cls);
|
||||
}}
|
||||
if (!anchor) return;
|
||||
if (id) anchor.setAttribute("data-annot-id", id);
|
||||
items.push({{
|
||||
chip: chip,
|
||||
anchor: anchor,
|
||||
kind: kind,
|
||||
x: anchor.getBoundingClientRect().left
|
||||
}});
|
||||
}});
|
||||
items.sort(function (a, b) {{ return a.x - b.x; }});
|
||||
if (chipsEl && items.length) {{
|
||||
items.forEach(function (it) {{ chipsEl.appendChild(it.chip); }});
|
||||
var more = band.querySelector("[data-annot-more]");
|
||||
if (more) chipsEl.appendChild(more);
|
||||
}}
|
||||
if (reduce || narrow || items.length > MAX_VISIBLE_ANNOTS) {{
|
||||
block.classList.add("is-keyed");
|
||||
band.classList.add("is-keyed");
|
||||
items.forEach(function (it, i) {{
|
||||
it.chip.setAttribute("data-annot-key", String(i + 1));
|
||||
}});
|
||||
return;
|
||||
}}
|
||||
block.classList.remove("is-keyed");
|
||||
band.classList.remove("is-keyed");
|
||||
// Mid-bottom of mark → mid-top of chip: vertical, horizontal rail, short stub.
|
||||
var blockRect = block.getBoundingClientRect();
|
||||
var bw = Math.max(1, block.offsetWidth);
|
||||
var bh = Math.max(1, block.offsetHeight);
|
||||
var svgNS = "http://www.w3.org/2000/svg";
|
||||
var svg = document.createElementNS(svgNS, "svg");
|
||||
svg.setAttribute("width", String(bw));
|
||||
svg.setAttribute("height", String(bh));
|
||||
svg.setAttribute("viewBox", "0 0 " + bw + " " + bh);
|
||||
svg.setAttribute("aria-hidden", "true");
|
||||
items.forEach(function (it) {{
|
||||
var a = it.anchor.getBoundingClientRect();
|
||||
var c = it.chip.getBoundingClientRect();
|
||||
var x0 = a.left + a.width / 2 - blockRect.left;
|
||||
var y0 = a.bottom - blockRect.top + 1;
|
||||
var x1 = c.left + c.width / 2 - blockRect.left;
|
||||
var y1 = c.top - blockRect.top;
|
||||
if (y1 < y0 + 8) {{
|
||||
y1 = y0 + 12;
|
||||
}}
|
||||
// Short stub into chip top-center; rail sits above that.
|
||||
var stub = Math.min(10, Math.max(6, (y1 - y0) * 0.28));
|
||||
var yRail = y1 - stub;
|
||||
if (yRail < y0 + 4) {{
|
||||
yRail = (y0 + y1) / 2;
|
||||
}}
|
||||
var path = document.createElementNS(svgNS, "path");
|
||||
path.setAttribute("class", "annot-leader annot-" + it.kind);
|
||||
path.setAttribute("stroke", leaderColor(it.kind));
|
||||
// Orthogonal: down from mark mid → across → short down to chip mid.
|
||||
path.setAttribute(
|
||||
"d",
|
||||
"M " + x0.toFixed(1) + " " + y0.toFixed(1) +
|
||||
" L " + x0.toFixed(1) + " " + yRail.toFixed(1) +
|
||||
" L " + x1.toFixed(1) + " " + yRail.toFixed(1) +
|
||||
" L " + x1.toFixed(1) + " " + y1.toFixed(1)
|
||||
);
|
||||
svg.appendChild(path);
|
||||
}});
|
||||
leaders.appendChild(svg);
|
||||
}}
|
||||
|
||||
function layoutAll() {{
|
||||
bands.forEach(layoutBand);
|
||||
}}
|
||||
layoutAll();
|
||||
// Second pass after fonts/layout settle (first paint often has zero chip width).
|
||||
requestAnimationFrame(function () {{ layoutAll(); }});
|
||||
if (document.documentElement.dataset.annotLeadersRo === "1") return;
|
||||
document.documentElement.dataset.annotLeadersRo = "1";
|
||||
if (typeof ResizeObserver !== "undefined") {{
|
||||
var ro = new ResizeObserver(function () {{ layoutAll(); }});
|
||||
bands.forEach(function (b) {{
|
||||
ro.observe(b);
|
||||
var blk = b.closest(".doc-block");
|
||||
if (blk) ro.observe(blk);
|
||||
}});
|
||||
var surface = document.querySelector(".document-surface");
|
||||
if (surface) ro.observe(surface);
|
||||
}}
|
||||
window.addEventListener("resize", layoutAll);
|
||||
|
||||
document.querySelectorAll("[data-annot-more]").forEach(function (btn) {{
|
||||
if (btn.dataset.bound === "1") return;
|
||||
btn.dataset.bound = "1";
|
||||
btn.addEventListener("click", function () {{
|
||||
var band = btn.closest("[data-annot-band]");
|
||||
if (!band) return;
|
||||
band.classList.add("is-expanded");
|
||||
btn.hidden = true;
|
||||
layoutAll();
|
||||
}});
|
||||
}});
|
||||
document.querySelectorAll(".annot-chip").forEach(function (chip) {{
|
||||
if (chip.dataset.focusBound === "1") return;
|
||||
chip.dataset.focusBound = "1";
|
||||
chip.addEventListener("mouseenter", function () {{
|
||||
var id = chip.getAttribute("data-annot-id");
|
||||
if (!id) return;
|
||||
var a = document.querySelector('.mq-anchor[data-annot-id="' + id + '"]');
|
||||
if (a) a.classList.add("is-focus");
|
||||
chip.classList.add("is-focus");
|
||||
}});
|
||||
chip.addEventListener("mouseleave", function () {{
|
||||
var id = chip.getAttribute("data-annot-id");
|
||||
if (!id) return;
|
||||
var a = document.querySelector('.mq-anchor[data-annot-id="' + id + '"]');
|
||||
if (a) a.classList.remove("is-focus");
|
||||
chip.classList.remove("is-focus");
|
||||
}});
|
||||
}});
|
||||
}}
|
||||
|
||||
if (document.readyState === "loading") {{
|
||||
document.addEventListener("DOMContentLoaded", function () {{
|
||||
initForeignCards();
|
||||
initOutlineSearch();
|
||||
initStreamPanel();
|
||||
initVarsPanel();
|
||||
initAnnotLeaders();
|
||||
initCallPickers();
|
||||
initLoopPickers();
|
||||
}});
|
||||
}} else {{
|
||||
initForeignCards();
|
||||
initOutlineSearch();
|
||||
initStreamPanel();
|
||||
initVarsPanel();
|
||||
initAnnotLeaders();
|
||||
initCallPickers();
|
||||
initLoopPickers();
|
||||
}}
|
||||
|
||||
function initOutlineSearch() {{
|
||||
@@ -2293,6 +2951,9 @@ pub fn page_file(files: &[PathBuf], rel: &str, vm: &FileViewModel, links: &LinkM
|
||||
.to_string(),
|
||||
_ => String::new(),
|
||||
};
|
||||
let trace_safe = vm
|
||||
.trace_json
|
||||
.replace("</", "<\\/");
|
||||
let main = format!(
|
||||
r#"
|
||||
<script>
|
||||
@@ -2300,6 +2961,7 @@ window.MARQDO_VIEW_LIVE = {live};
|
||||
window.MARQDO_FILE_PATH = {path_js};
|
||||
window.MARQDO_AUTO_STREAM = {auto_stream};
|
||||
</script>
|
||||
<script type="application/json" id="mq-view-trace">{trace}</script>
|
||||
<h1 class="page">{title}<span class="status-pill {status}">{status_label}</span></h1>
|
||||
<p class="meta">{rel}</p>
|
||||
<section class="block">
|
||||
@@ -2322,6 +2984,11 @@ window.MARQDO_AUTO_STREAM = {auto_stream};
|
||||
live = live_flag,
|
||||
path_js = escape_js_string(rel),
|
||||
auto_stream = if vm.auto_stream { "true" } else { "false" },
|
||||
trace = if trace_safe.is_empty() {
|
||||
"{}"
|
||||
} else {
|
||||
trace_safe.as_str()
|
||||
},
|
||||
title = escape(title),
|
||||
status = status,
|
||||
status_label = status_label,
|
||||
|
||||
+57
-13
@@ -1,8 +1,10 @@
|
||||
//! `marqdo view` — local HTML browser for `.mq.md` structure + output.
|
||||
//! `marqdo debug` — separate debugger host (tree-walk breakpoints).
|
||||
|
||||
mod annot;
|
||||
mod debug_api;
|
||||
mod debug_page;
|
||||
mod document;
|
||||
mod html;
|
||||
mod output;
|
||||
mod render;
|
||||
@@ -23,9 +25,10 @@ use tiny_http::{Header, Method, Request, Response, Server, StatusCode};
|
||||
use crate::input_feed::{effective_stdin, extract_frontmatter_stdin, split_stdin_text};
|
||||
use crate::view::debug_page::{build_debug_model, page_debug};
|
||||
use crate::view::html::{escape, page_file, page_index, LinkMode};
|
||||
use crate::view::annot::{build_view_annots, view_execution_report_json};
|
||||
use crate::view::render::{
|
||||
collect_input_prompts, render_bindings_html, render_module_structure, render_right_rail,
|
||||
uses_stream_panel, FileViewModel,
|
||||
collect_input_prompts, render_bindings_html, render_module_structure,
|
||||
render_module_structure_with_annots, render_right_rail, uses_stream_panel, FileViewModel,
|
||||
};
|
||||
use crate::{run_file_capture, RunOptions};
|
||||
|
||||
@@ -212,6 +215,24 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
|
||||
let json = files_json(&root.files);
|
||||
respond_json(request, json)
|
||||
}
|
||||
"/api/view-trace" => {
|
||||
let rel = query_param(query, "path").unwrap_or_default();
|
||||
if rel.is_empty() {
|
||||
return respond_json_status(
|
||||
request,
|
||||
StatusCode(400),
|
||||
serde_json::json!({ "ok": false, "error": "missing path" }).to_string(),
|
||||
);
|
||||
}
|
||||
let resolved = resolve_rel(root, &rel)?;
|
||||
let vm = build_file_view(root, &resolved, &rel, &[], true)?;
|
||||
let body = if vm.trace_json.is_empty() {
|
||||
serde_json::json!({ "version": 1, "path": rel, "ok": vm.ok, "calls": [], "events": [], "bindings_final": {} }).to_string()
|
||||
} else {
|
||||
vm.trace_json
|
||||
};
|
||||
respond_json(request, body)
|
||||
}
|
||||
"/api/events" => api_events(request),
|
||||
_ => {
|
||||
let resp = Response::from_string("not found").with_status_code(StatusCode(404));
|
||||
@@ -345,6 +366,7 @@ pub(crate) fn build_file_view(
|
||||
opts.sleep_limit_ms = if live { Some(30_000) } else { Some(0) };
|
||||
// Optional: sandbox to the whole view tree so sibling folders are reachable.
|
||||
opts.fs_root = Some(root.root.clone());
|
||||
let mut captured: Option<crate::capture::RunCapture> = None;
|
||||
let (stdout, stderr, ok, plots, mut bindings_html) = if awaiting_input || auto_stream {
|
||||
(
|
||||
String::new(),
|
||||
@@ -355,13 +377,13 @@ pub(crate) fn build_file_view(
|
||||
)
|
||||
} else {
|
||||
match run_file_capture(abs, &opts) {
|
||||
Ok(cap) => (
|
||||
cap.stdout,
|
||||
String::new(),
|
||||
true,
|
||||
cap.plots.into_iter().map(|p| p.svg).collect(),
|
||||
render_bindings_html(&cap.bindings),
|
||||
),
|
||||
Ok(cap) => {
|
||||
let stdout = cap.stdout.clone();
|
||||
let plots = cap.plots.iter().map(|p| p.svg.clone()).collect();
|
||||
let bindings_html = render_bindings_html(&cap.bindings);
|
||||
captured = Some(cap);
|
||||
(stdout, String::new(), true, plots, bindings_html)
|
||||
}
|
||||
Err(e) => (
|
||||
String::new(),
|
||||
tidy_user_error(&format!("{e:#}"), abs, rel),
|
||||
@@ -375,10 +397,14 @@ pub(crate) fn build_file_view(
|
||||
if !awaiting_input && !auto_stream {
|
||||
if let Ok(next) = fs::read_to_string(abs) {
|
||||
source = next;
|
||||
if let Ok(module) = crate::parse::parse_source(&source) {
|
||||
structure = render_module_structure(&module, &source);
|
||||
module_opt = Some(module);
|
||||
}
|
||||
}
|
||||
if let Ok(module) = crate::parse::parse_source(&source) {
|
||||
let annots = match &captured {
|
||||
Some(cap) => build_view_annots(&module, &source, cap),
|
||||
None => Vec::new(),
|
||||
};
|
||||
structure = render_module_structure_with_annots(&module, &source, &annots);
|
||||
module_opt = Some(module);
|
||||
}
|
||||
}
|
||||
let wb = crate::view::render::render_writeback_outline(&source);
|
||||
@@ -392,6 +418,10 @@ pub(crate) fn build_file_view(
|
||||
}
|
||||
}
|
||||
};
|
||||
let trace_json = match &captured {
|
||||
Some(cap) => view_execution_report_json(rel, ok, cap),
|
||||
None => String::new(),
|
||||
};
|
||||
Ok(FileViewModel {
|
||||
rel_path: rel.to_string(),
|
||||
source,
|
||||
@@ -407,6 +437,7 @@ pub(crate) fn build_file_view(
|
||||
show_stream,
|
||||
plots,
|
||||
bindings_html: std::mem::take(&mut bindings_html),
|
||||
trace_json,
|
||||
})
|
||||
}
|
||||
|
||||
@@ -641,6 +672,17 @@ fn api_run(root: &ViewRoot, mut request: Request) -> Result<()> {
|
||||
// Keep the terminal frame small — tokens already streamed via bus.
|
||||
let preview: String = cap.stdout.chars().take(500).collect();
|
||||
let bindings_html = render_bindings_html(&cap.bindings);
|
||||
let source_now = fs::read_to_string(&abs).unwrap_or(source);
|
||||
let (structure_html, trace_json) = match crate::parse::parse_source(&source_now) {
|
||||
Ok(module) => {
|
||||
let annots = build_view_annots(&module, &source_now, &cap);
|
||||
(
|
||||
render_module_structure_with_annots(&module, &source_now, &annots),
|
||||
view_execution_report_json(&rel_clone, true, &cap),
|
||||
)
|
||||
}
|
||||
Err(_) => (String::new(), String::new()),
|
||||
};
|
||||
let done = serde_json::json!({
|
||||
"type": "done",
|
||||
"run_id": run_id,
|
||||
@@ -648,6 +690,8 @@ fn api_run(root: &ViewRoot, mut request: Request) -> Result<()> {
|
||||
"ok": true,
|
||||
"result": preview,
|
||||
"bindings_html": bindings_html,
|
||||
"structure_html": structure_html,
|
||||
"trace_json": trace_json,
|
||||
});
|
||||
crate::host::event_bus::EventBus::global().publish_json(&done.to_string());
|
||||
}
|
||||
|
||||
+7
-1
@@ -32,11 +32,17 @@ pub fn write_static(opts: OutputOptions) -> Result<()> {
|
||||
vm.ok = true;
|
||||
vm.plots.clear();
|
||||
vm.bindings_html = String::from(r#"<p class="vars-skipped">skipped</p>"#);
|
||||
// Rebuild outline so Variables shows skipped.
|
||||
vm.trace_json.clear();
|
||||
// Rebuild outline + Structure without run annotations.
|
||||
if let Ok(module) = crate::parse::parse_source(&vm.source) {
|
||||
let wb = crate::view::render::render_writeback_outline(&vm.source);
|
||||
vm.outline_html =
|
||||
crate::view::render::render_right_rail(&module, &vm.bindings_html, &wb);
|
||||
vm.structure_html = crate::view::render::render_module_structure_with_annots(
|
||||
&module,
|
||||
&vm.source,
|
||||
&[],
|
||||
);
|
||||
}
|
||||
}
|
||||
let links = LinkMode::Static {
|
||||
|
||||
+185
-17
@@ -45,6 +45,8 @@ pub struct FileViewModel {
|
||||
pub plots: Vec<String>,
|
||||
/// HTML for Variables panel (entry bindings after run).
|
||||
pub bindings_html: String,
|
||||
/// ViewExecutionReport JSON for AI / call-picker (empty if no run).
|
||||
pub trace_json: String,
|
||||
}
|
||||
|
||||
/// Collect prompt strings from every `input` / `输入` call in the module (pre-order).
|
||||
@@ -187,14 +189,36 @@ fn prompt_expr_text(expr: &Expr) -> String {
|
||||
}
|
||||
}
|
||||
|
||||
/// Browse Structure without run annotations (empty callouts).
|
||||
pub fn render_module_structure(module: &Module, source: &str) -> String {
|
||||
render_module_structure_mode(module, source, StructureMode::Browse)
|
||||
}
|
||||
|
||||
/// Browse Structure: document surface with optional result annotations.
|
||||
pub fn render_module_structure_with_annots(
|
||||
module: &Module,
|
||||
source: &str,
|
||||
annots: &[crate::view::annot::ViewAnnot],
|
||||
) -> String {
|
||||
crate::view::document::render_module_document(module, source, annots)
|
||||
}
|
||||
|
||||
pub fn render_module_structure_mode(
|
||||
module: &Module,
|
||||
source: &str,
|
||||
mode: StructureMode,
|
||||
) -> String {
|
||||
match mode {
|
||||
StructureMode::Browse => render_module_structure_with_annots(module, source, &[]),
|
||||
StructureMode::Debug => render_module_structure_cards(module, source, mode),
|
||||
}
|
||||
}
|
||||
|
||||
/// Legacy AST-card Structure (debug + tests that need card markup).
|
||||
pub fn render_module_structure_cards(
|
||||
module: &Module,
|
||||
source: &str,
|
||||
mode: StructureMode,
|
||||
) -> String {
|
||||
let lines = classify_source(source);
|
||||
let writebacks = writeback::writeback_map(source);
|
||||
@@ -905,7 +929,7 @@ fn emit_comments(lines: &[ClassifiedLine], from_line: u32, before_line: u32) ->
|
||||
}
|
||||
|
||||
/// Render narrative comments as Markdown (links, emphasis, code, lists, …).
|
||||
fn comment_markdown_to_html(md: &str) -> String {
|
||||
pub(crate) fn comment_markdown_to_html(md: &str) -> String {
|
||||
let mut opts = Options::empty();
|
||||
opts.insert(Options::ENABLE_STRIKETHROUGH);
|
||||
opts.insert(Options::ENABLE_TABLES);
|
||||
@@ -947,10 +971,11 @@ fn render_fun(
|
||||
("chip", "explicit + param")
|
||||
};
|
||||
s.push_str(&format!(
|
||||
"<span class=\"{cls}\" title=\"{title}\">{name}</span>",
|
||||
"<span class=\"{cls}\" data-param-name=\"{name}\" data-fn=\"{fn}\" title=\"{title}\">{name}<span class=\"chip-val\"></span></span>",
|
||||
cls = cls,
|
||||
title = title,
|
||||
name = escape(&p.name),
|
||||
fn = escape(&fun.name),
|
||||
));
|
||||
}
|
||||
s.push_str("</div>");
|
||||
@@ -1045,17 +1070,89 @@ fn stmt_end_line(stmt: &Stmt) -> u32 {
|
||||
|
||||
fn output_card(line: u32, writebacks: &HashMap<u32, String>) -> String {
|
||||
match writebacks.get(&line) {
|
||||
Some(body) => {
|
||||
let badges = writeback_badges(body);
|
||||
format!(
|
||||
r#"<div class="card output-card" id="wb-{line}"><div class="wb-badges">{badges}</div><pre class="output-body">{}</pre></div>"#,
|
||||
escape(body)
|
||||
)
|
||||
}
|
||||
Some(body) => render_output_card(line, body),
|
||||
None => String::new(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Live view + static site: text `<pre>` and/or `<img>` for image writebacks.
|
||||
pub fn render_output_card(line: u32, combined: &str) -> String {
|
||||
if combined.trim().is_empty() {
|
||||
return String::new();
|
||||
}
|
||||
let badges = writeback_badges(combined);
|
||||
let mut body_html = String::new();
|
||||
let mut buf_text = String::new();
|
||||
let flush_text = |buf: &mut String, out: &mut String| {
|
||||
if buf.is_empty() {
|
||||
return;
|
||||
}
|
||||
out.push_str(&format!(
|
||||
r#"<pre class="output-body">{}</pre>"#,
|
||||
escape(buf.trim_end())
|
||||
));
|
||||
buf.clear();
|
||||
};
|
||||
for line_s in combined.lines() {
|
||||
let t = line_s.trim();
|
||||
if let Some(url) = extract_md_image_url(t) {
|
||||
flush_text(&mut buf_text, &mut body_html);
|
||||
body_html.push_str(&format!(
|
||||
r#"<figure class="wb-figure"><img class="wb-image" src="{src}" alt="writeback"/><figcaption class="wb-image-url">{cap}</figcaption></figure>"#,
|
||||
src = escape(&url),
|
||||
cap = escape(&url),
|
||||
));
|
||||
} else {
|
||||
if !buf_text.is_empty() {
|
||||
buf_text.push('\n');
|
||||
}
|
||||
buf_text.push_str(line_s);
|
||||
}
|
||||
}
|
||||
flush_text(&mut buf_text, &mut body_html);
|
||||
let has_img = body_html.contains("wb-image");
|
||||
format!(
|
||||
r#"<div class="card output-card{img_cls}" id="wb-{line}" data-wb="1"><div class="wb-badges">{badges}</div>{body}</div>"#,
|
||||
line = line,
|
||||
img_cls = if has_img { " output-card-image" } else { "" },
|
||||
badges = badges,
|
||||
body = body_html,
|
||||
)
|
||||
}
|
||||
|
||||
fn extract_md_image_url(line: &str) -> Option<String> {
|
||||
let t = line.trim();
|
||||
let rest = t.strip_prefix("?;
|
||||
let after = &rest[alt_end + 2..];
|
||||
let url_end = after.rfind(')')?;
|
||||
let url = after[..url_end].trim();
|
||||
if url.is_empty() {
|
||||
None
|
||||
} else {
|
||||
Some(url.to_string())
|
||||
}
|
||||
}
|
||||
|
||||
/// Document-surface marker for a writeback source line (comment or image).
|
||||
pub fn render_writeback_source_line(line_no: u32, text: &str) -> String {
|
||||
let trimmed = text.trim();
|
||||
let is_image = trimmed.starts_with("![") && trimmed.contains("marqdo-out");
|
||||
let kind = if is_image { "image" } else { "comment" };
|
||||
let label = if is_image {
|
||||
"writeback · image"
|
||||
} else {
|
||||
"writeback"
|
||||
};
|
||||
format!(
|
||||
r#"<div class="doc-block doc-writeback" data-line="{line}" data-wb-kind="{kind}"><span class="wb-source-badge">{label}</span><code class="wb-source-text">{text}</code></div>"#,
|
||||
line = line_no,
|
||||
kind = kind,
|
||||
label = label,
|
||||
text = escape(trimmed),
|
||||
)
|
||||
}
|
||||
|
||||
fn writeback_badges(body: &str) -> String {
|
||||
let mut keys = Vec::new();
|
||||
for line in body.lines() {
|
||||
@@ -1162,12 +1259,14 @@ fn render_stmt(
|
||||
<span class="badge">code</span>
|
||||
<code class="expr">`{name}` =</code>
|
||||
<span class="code-lang">{lang}</span>
|
||||
</div>
|
||||
<pre class="code-body"><code class="language-{lang}">{src}</code></pre>
|
||||
<div class="code-foot">
|
||||
<div class="code-actions">
|
||||
<input type="text" class="code-cmd" placeholder="{placeholder}" spellcheck="false" autocomplete="off"/>
|
||||
<button type="button" class="code-run">Run</button>
|
||||
</div>
|
||||
</div>
|
||||
<pre class="code-body"><code class="language-{lang}">{src}</code></pre>
|
||||
<pre class="code-out" hidden></pre>
|
||||
</div>"#,
|
||||
lang = lang,
|
||||
@@ -1412,6 +1511,49 @@ fn expr_prec(expr: &Expr, parent_prec: u8) -> String {
|
||||
}
|
||||
|
||||
/// Best-effort ASCII formula → TeX for KaTeX in view Structure.
|
||||
pub(crate) fn formula_ascii_to_tex_pub(ascii: &str) -> String {
|
||||
formula_ascii_to_tex(ascii)
|
||||
}
|
||||
|
||||
/// Formula assign card for document surface embedding (single visual layer).
|
||||
pub(crate) fn render_formula_assign_card(name: &str, tex: &str) -> String {
|
||||
format!(
|
||||
r#"<div class="card formula-card" data-formula-name="{name}">
|
||||
<div class="formula-head"><span class="badge">formula</span> <span class="formula-name">{name}</span></div>
|
||||
<div class="math-block">$${tex}$$</div>
|
||||
</div>"#,
|
||||
name = escape(name),
|
||||
tex = escape(tex),
|
||||
)
|
||||
}
|
||||
|
||||
/// Foreign code assign card for document surface embedding (single visual layer).
|
||||
/// Head → body → foot(actions) so the source is never collapsed under the Run row.
|
||||
pub(crate) fn render_code_assign_card(name: &str, lang: &str, source: &str) -> String {
|
||||
let placeholder = escape(&crate::foreign::default_cmd_display(lang));
|
||||
format!(
|
||||
r#"<div class="card code-card" data-lang="{lang}" data-code-name="{name}">
|
||||
<div class="code-head">
|
||||
<span class="badge">code</span>
|
||||
<span class="code-name">{name}</span>
|
||||
<span class="code-lang">{lang}</span>
|
||||
</div>
|
||||
<pre class="code-body"><code class="language-{lang}">{src}</code></pre>
|
||||
<div class="code-foot">
|
||||
<div class="code-actions">
|
||||
<input type="text" class="code-cmd" placeholder="{placeholder}" spellcheck="false" autocomplete="off"/>
|
||||
<button type="button" class="code-run">Run</button>
|
||||
</div>
|
||||
</div>
|
||||
<pre class="code-out" hidden></pre>
|
||||
</div>"#,
|
||||
lang = escape(lang),
|
||||
name = escape(name),
|
||||
placeholder = placeholder,
|
||||
src = escape(source),
|
||||
)
|
||||
}
|
||||
|
||||
fn formula_ascii_to_tex(ascii: &str) -> String {
|
||||
let mut out = String::new();
|
||||
let chars: Vec<char> = ascii.chars().collect();
|
||||
@@ -1525,7 +1667,7 @@ mod tests {
|
||||
let src = include_str!("../../tests/structure/nested-call.mq.md");
|
||||
let module = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_structure(&module, src);
|
||||
assert!(html.contains("comment-card"));
|
||||
assert!(html.contains("doc-prose") || html.contains("打印一句问候"), "{html}");
|
||||
assert!(html.contains("print"));
|
||||
assert!(!html.contains("Binary {"));
|
||||
assert!(!html.contains("Literal(Int"));
|
||||
@@ -1536,9 +1678,9 @@ mod tests {
|
||||
let src = "段首说明\n续行仍属同段\n\n下一段\n\n# main\n\n> print text=x\n";
|
||||
let module = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_structure(&module, src);
|
||||
let cards = html.matches("comment-card").count();
|
||||
assert_eq!(cards, 2, "blank line should split comment paragraphs: {html}");
|
||||
assert!(html.contains("段首说明 续行仍属同段") || html.contains("段首说明</p>"));
|
||||
let blocks = html.matches("doc-prose").count();
|
||||
assert!(blocks >= 2, "blank line should split comment paragraphs: {html}");
|
||||
assert!(html.contains("段首说明 续行仍属同段") || html.contains("段首说明</p>") || html.contains("段首说明"));
|
||||
assert!(html.contains("下一段"));
|
||||
}
|
||||
|
||||
@@ -1575,11 +1717,10 @@ mod tests {
|
||||
let src = "---\ntitle: t\nimport text:lib/text.mq.md\n---\n\n# main\n\n> print text=hi\n";
|
||||
let local = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_structure(&local, src);
|
||||
assert!(html.contains("badge\">import"), "{html}");
|
||||
assert!(html.contains("doc-imports") || html.contains("lib/text.mq.md"), "{html}");
|
||||
assert!(html.contains("lib/text.mq.md"), "{html}");
|
||||
assert!(html.contains("main"), "{html}");
|
||||
assert!(!html.contains("trim"), "{html}");
|
||||
assert!(html.contains("class=\"stmt\""), "{html}");
|
||||
assert!(html.contains("data-line="), "{html}");
|
||||
assert_eq!(local.functions.len(), 1);
|
||||
assert_eq!(local.functions[0].name, "main");
|
||||
@@ -1624,9 +1765,21 @@ mod tests {
|
||||
let browse = render_module_structure_mode(&module, src, StructureMode::Browse);
|
||||
let debug = render_module_structure_mode(&module, src, StructureMode::Debug);
|
||||
assert!(browse.contains("id=\"fn-"), "{browse}");
|
||||
assert!(browse.contains("document-surface"), "{browse}");
|
||||
assert!(!browse.contains("bp-gutter"), "{browse}");
|
||||
assert!(debug.contains("bp-gutter"), "{debug}");
|
||||
assert!(debug.contains("id=\"stmt-"), "{debug}");
|
||||
assert!(debug.contains("card"), "{debug}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn browse_preserves_prose_unified_line() {
|
||||
let src = include_str!("../../tests/markup-v03/inc-prose.mq.md");
|
||||
let module = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_structure(&module, src);
|
||||
assert!(html.contains("对于输入变量"), "{html}");
|
||||
assert!(html.contains("mq-anchor"), "{html}");
|
||||
assert!(!html.contains("badge\">bind"), "{html}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -1663,6 +1816,20 @@ mod tests {
|
||||
assert!(html.contains(">xs<") || html.contains("vars-name\">xs"), "{html}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn output_card_renders_image_writeback() {
|
||||
let html = render_output_card(3, "[ok]\n");
|
||||
assert!(html.contains("output-card-image"), "{html}");
|
||||
assert!(html.contains(r#"src="plots/a.svg""#), "{html}");
|
||||
assert!(html.contains("wb-ok") || html.contains(">ok<"), "{html}");
|
||||
let text = render_output_card(1, "plain-42");
|
||||
assert!(text.contains("output-body"), "{text}");
|
||||
assert!(!text.contains("wb-image"), "{text}");
|
||||
let src = render_writeback_source_line(4, "");
|
||||
assert!(src.contains(r#"data-wb-kind="image""#), "{src}");
|
||||
assert!(src.contains("writeback · image"), "{src}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structure_marks_inferred_params() {
|
||||
let src = include_str!("../../tests/markup-v03/inc-prose.mq.md");
|
||||
@@ -1675,7 +1842,8 @@ mod tests {
|
||||
assert!(add.params.iter().any(|p| p.name == "n" && p.inferred));
|
||||
let html = render_module_structure(&module, src);
|
||||
assert!(
|
||||
html.contains("chip inferred") && html.contains(">n<"),
|
||||
html.contains("chip inferred")
|
||||
&& (html.contains(">n<") || html.contains(r#"data-param-name="n""#)),
|
||||
"expected inferred chip for n: {html}"
|
||||
);
|
||||
let outline = render_function_outline(&module);
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
type: Decision
|
||||
id: ADR-022
|
||||
title: Cache is not persistence
|
||||
status: accepted
|
||||
applies_to:
|
||||
- config.resolve
|
||||
---
|
||||
|
||||
# Cache is not persistence
|
||||
|
||||
## Decision
|
||||
|
||||
Redis is only used for ephemeral cache.
|
||||
|
||||
## Reason
|
||||
|
||||
The application must remain correct when Redis is unavailable.
|
||||
|
||||
## Consequence
|
||||
|
||||
Do not introduce Redis as the source of truth.
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
type: AntiPattern
|
||||
id: AP-001
|
||||
title: Do not parse JWT manually
|
||||
status: stable
|
||||
---
|
||||
|
||||
# Do not parse JWT manually
|
||||
|
||||
Never decode JWT directly in application code.
|
||||
|
||||
Use the shared auth capability instead.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
type: Constraint
|
||||
id: C-014
|
||||
title: Centralized config resolution
|
||||
status: stable
|
||||
applies_to:
|
||||
- config.resolve
|
||||
---
|
||||
|
||||
# Database and config access
|
||||
|
||||
All configuration resolution must go through `resolve_config`.
|
||||
|
||||
Direct ad-hoc config parsing in handlers is prohibited.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Resolve configuration
|
||||
capability: config.resolve
|
||||
status: stable
|
||||
---
|
||||
|
||||
Config resolution capability for Engineering Knowledge demos.
|
||||
|
||||
Use when: The caller needs the final normalized configuration.
|
||||
|
||||
Do not use when: Only raw configuration should be inspected.
|
||||
|
||||
# config
|
||||
|
||||
## resolve_config
|
||||
+ `path`
|
||||
|
||||
`defaults` =
|
||||
|
||||
| host | port |
|
||||
|------|------|
|
||||
| localhost | 8080 |
|
||||
|
||||
* defaults
|
||||
|
||||
## merge_config
|
||||
+ `base`
|
||||
+ `overlay`
|
||||
|
||||
Merge overlay keys onto base configuration map.
|
||||
|
||||
* overlay
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
type: Failure
|
||||
id: F-019
|
||||
title: Do not cache authorization by user only
|
||||
task: add_cache_layer
|
||||
status: resolved
|
||||
applies_to:
|
||||
- config.resolve
|
||||
---
|
||||
|
||||
# Do not cache authorization result
|
||||
|
||||
## Failed approach
|
||||
|
||||
Caching permission checks by user only.
|
||||
|
||||
## Failure
|
||||
|
||||
Permissions changed during role update.
|
||||
|
||||
## Correct approach
|
||||
|
||||
Cache by user_id, resource_id, and permission_version.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Normalize settings (near-duplicate)
|
||||
status: stable
|
||||
---
|
||||
|
||||
Near-duplicate of resolve_config for duplicate detection demos.
|
||||
|
||||
Use when: Caller wants normalized settings map.
|
||||
|
||||
# settings
|
||||
|
||||
## normalize_settings
|
||||
+ `path`
|
||||
|
||||
Normalize settings from a path with host/port defaults.
|
||||
|
||||
`defaults` =
|
||||
|
||||
| host | port |
|
||||
|------|------|
|
||||
| localhost | 8080 |
|
||||
|
||||
* defaults
|
||||
|
||||
## merge_settings
|
||||
+ `base`
|
||||
+ `overlay`
|
||||
|
||||
Merge overlay onto base settings — semantically close to merge_config.
|
||||
|
||||
* overlay
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: eng preflight offline
|
||||
import plugin:lib/plugin.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
Offline Engineering Knowledge gate against `tests/engineering/.marqdo`
|
||||
(seed with `marqdo knowledge tests/engineering -o tests/engineering/.marqdo`).
|
||||
|
||||
# main
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
**out = "skip"**
|
||||
*out*
|
||||
|
||||
**pf = > agent_eng_preflight task="resolve configuration" marqdo_dir="tests/engineering/.marqdo"**
|
||||
**status = > json.get value=`pf` key="status"**
|
||||
**dec = > json.get value=`pf` key="decision"**
|
||||
**out = "eng-preflight-unexpected"**
|
||||
1. `status` == "missing_knowledge"
|
||||
**out = "eng-preflight-skip-no-graph"**
|
||||
2. `dec` == "REUSE"
|
||||
**out = "eng-preflight-ok"**
|
||||
3. `dec` == "ADAPT"
|
||||
**out = "eng-preflight-ok"**
|
||||
4. *
|
||||
**out = "eng-preflight-unexpected"**
|
||||
|
||||
*out*
|
||||
+192
@@ -1167,6 +1167,7 @@ fn catalog_writes_yaml() {
|
||||
"tests",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
"--no-knowledge",
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
let yaml = std::fs::read_to_string(dir.join("catalog.yaml")).unwrap();
|
||||
@@ -1189,6 +1190,166 @@ fn catalog_writes_yaml() {
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn knowledge_compile_engineering_fixture() {
|
||||
let dir = tempfile_dir("mq-ekc");
|
||||
let (code, _, stderr) = run(&[
|
||||
"knowledge",
|
||||
"tests/engineering",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
assert!(dir.join("catalog/repository.mq.md").exists());
|
||||
assert!(dir.join("graph/graph.json").exists());
|
||||
assert!(dir.join("graph/edges.json").exists());
|
||||
assert!(dir.join("engineering.yaml").exists());
|
||||
assert!(dir.join("index.mq.md").exists());
|
||||
let eng = std::fs::read_to_string(dir.join("engineering.yaml")).unwrap();
|
||||
assert!(eng.contains("type: Marqdo Engineering Knowledge"), "{eng}");
|
||||
assert!(eng.contains("capabilities:"), "{eng}");
|
||||
assert!(
|
||||
dir.join("knowledge/decisions").exists()
|
||||
|| dir.join("knowledge/constraints").exists(),
|
||||
"L4 knowledge dirs"
|
||||
);
|
||||
let caps: Vec<_> = std::fs::read_dir(dir.join("catalog/capabilities"))
|
||||
.unwrap()
|
||||
.flatten()
|
||||
.collect();
|
||||
assert!(!caps.is_empty(), "expected capability pages");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn knowledge_reuse_prefers_existing_capability() {
|
||||
let dir = tempfile_dir("mq-reuse");
|
||||
let (code, stdout, stderr) = run(&[
|
||||
"reuse",
|
||||
"resolve configuration",
|
||||
"tests/engineering",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
"--json",
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
assert!(
|
||||
stdout.contains("\"decision\":\"REUSE\"") || stdout.contains("\"decision\": \"REUSE\""),
|
||||
"expected REUSE: {stdout}"
|
||||
);
|
||||
assert!(stdout.contains("create_allowed"), "{stdout}");
|
||||
assert!(
|
||||
stdout.contains("false") || stdout.contains("\"create_allowed\":false"),
|
||||
"create should not be required: {stdout}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn knowledge_find_surfaces_negative_knowledge() {
|
||||
let dir = tempfile_dir("mq-find");
|
||||
let (code, stdout, stderr) = run(&[
|
||||
"find",
|
||||
"JWT",
|
||||
"tests/engineering",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
"--json",
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
assert!(
|
||||
stdout.contains("AntiPattern") || stdout.contains("JWT") || stdout.contains("parse"),
|
||||
"expected JWT anti-pattern hit: {stdout}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn knowledge_duplicate_detects_merge_pair() {
|
||||
let dir = tempfile_dir("mq-dup");
|
||||
let (code, stdout, stderr) = run(&[
|
||||
"duplicate",
|
||||
"tests/engineering",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
"--threshold",
|
||||
"0.75",
|
||||
"--json",
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
assert!(
|
||||
stdout.contains("merge_config") && stdout.contains("merge_settings"),
|
||||
"expected merge_* duplicate pair: {stdout}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn knowledge_verify_and_conflicts_and_stale() {
|
||||
let dir = tempfile_dir("mq-verify");
|
||||
for cmd in ["verify", "conflicts", "stale"] {
|
||||
let (code, stdout, stderr) = run(&[
|
||||
cmd,
|
||||
"tests/engineering",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
"--json",
|
||||
]);
|
||||
assert_eq!(code, 0, "{cmd}: {stderr}");
|
||||
assert!(!stdout.is_empty(), "{cmd} empty stdout");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn knowledge_impact_lists_capabilities() {
|
||||
let dir = tempfile_dir("mq-impact");
|
||||
let (code, stdout, stderr) = run(&[
|
||||
"impact",
|
||||
"config_resolve.mq.md",
|
||||
"--root",
|
||||
"tests/engineering",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
"--json",
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
assert!(
|
||||
stdout.contains("config.resolve") || stdout.contains("capabilities"),
|
||||
"{stdout}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn knowledge_preflight_writes_context_pack() {
|
||||
let dir = tempfile_dir("mq-pf");
|
||||
let (code, stdout, stderr) = run(&[
|
||||
"knowledge",
|
||||
"tests/engineering",
|
||||
"preflight",
|
||||
"resolve configuration",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
"--json",
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}\n{stdout}");
|
||||
assert!(stdout.contains("create_allowed"), "{stdout}");
|
||||
let ctx = dir.join("agent/contexts");
|
||||
assert!(ctx.exists(), "contexts dir missing");
|
||||
let packs: Vec<_> = std::fs::read_dir(&ctx).unwrap().flatten().collect();
|
||||
assert!(!packs.is_empty(), "expected context pack");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn catalog_hooks_knowledge_by_default() {
|
||||
let dir = tempfile_dir("mq-cat-ekc");
|
||||
let (code, _, stderr) = run(&[
|
||||
"catalog",
|
||||
"tests/engineering",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
assert!(dir.join("catalog.yaml").exists());
|
||||
assert!(dir.join("engineering.yaml").exists());
|
||||
assert!(dir.join("graph/graph.json").exists());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_mq_md_never_calls_host() {
|
||||
// Hard rule: ext/**/*.mq.md must not invoke host_* (use lib/* or plugin names).
|
||||
@@ -1243,6 +1404,7 @@ fn catalog_includes_agent_kb_concepts() {
|
||||
"tests/ext",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
"--no-knowledge",
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
let yaml = std::fs::read_to_string(dir.join("catalog.yaml")).unwrap();
|
||||
@@ -3203,3 +3365,33 @@ fn markup_v03_decl_ident_only() {
|
||||
fn markup_v03_bold_expr() {
|
||||
assert_out_v03("tests/markup-v03/bold-expr.mq.md", "42");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_formula_meta_var() {
|
||||
assert_out_v03("tests/markup-v03/formula-meta-var.mq.md", "x^2 - 2");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_inline_dollar_formula() {
|
||||
assert_out_v03("tests/markup-v03/inline-dollar-formula.mq.md", "x + 1");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_branch_arm_prose() {
|
||||
assert_out_v03("tests/markup-v03/branch-arm-prose.mq.md", "正");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_branch_cond_narrative() {
|
||||
assert_out_v03("tests/markup-v03/branch-cond-narrative.mq.md", "正");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_foreach_narrative() {
|
||||
assert_out_v03("tests/markup-v03/foreach-narrative.mq.md", "a\nb\n1\n2");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn markup_v03_foreach_nested_link() {
|
||||
assert_out_v03("tests/markup-v03/foreach-nested-link.mq.md", "x\ny");
|
||||
}
|
||||
@@ -17,6 +17,8 @@
|
||||
|
||||
代码即文档叙述面(G1–G4):`module-hr` / `soft-emphasis` / `float-discount` / `dynamic-footnote` —— 设计见 [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md)。
|
||||
|
||||
块公式 meta / 控制流叙述:`formula-meta-var` / `inline-dollar-formula` / `branch-arm-prose` / `branch-cond-narrative` / `foreach-narrative` / `foreach-nested-link` —— 见 [fence-meta-and-control-prose.md](../../doc/design/fence-meta-and-control-prose.md)。
|
||||
|
||||
```bash
|
||||
cargo test --test gold markup_v03
|
||||
marqdo run tests/markup-v03/inc-prose.mq.md
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: v0.3 分支臂内叙述
|
||||
description: 臂内 prose 不得逃逸;n>0 时仅 then
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**n = 1**
|
||||
|
||||
1. `n` > 0
|
||||
此时`n`为正,我们 **打印 内容="正"**
|
||||
2. *
|
||||
否则 **打印 内容="非正"**
|
||||
|
||||
*None*
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: v0.3 条件行夹叙述
|
||||
description: 当`n`大于 0 时 / 否则 *
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**n = 1**
|
||||
|
||||
1. 当`n`大于 0 时
|
||||
我们 **打印 内容="正"**
|
||||
2. 否则 *
|
||||
我们 **打印 内容="非正"**
|
||||
|
||||
*None*
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: v0.3 循环头叙述糖
|
||||
description: 对`xs`的每一项`项` / for each `item` in `ys`
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`xs` =
|
||||
|
||||
| v |
|
||||
|---|
|
||||
| a |
|
||||
| b |
|
||||
|
||||
- 对`xs`的每一项`项`
|
||||
**打印 内容=`项`**
|
||||
|
||||
`ys` =
|
||||
|
||||
| v |
|
||||
|---|
|
||||
| 1 |
|
||||
| 2 |
|
||||
|
||||
- for each `item` in `ys`
|
||||
**print text=`item`**
|
||||
|
||||
*None*
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: v0.3 推荐循环头嵌套
|
||||
description: `- [o](外层)` 内再 `- [i](内层)`
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`外层` =
|
||||
|
||||
| a |
|
||||
|---|
|
||||
| x |
|
||||
| y |
|
||||
|
||||
`内层` =
|
||||
|
||||
| b |
|
||||
|---|
|
||||
| 1 |
|
||||
|
||||
- [o](外层)
|
||||
- [i](内层)
|
||||
**print text=`o`**
|
||||
|
||||
*None*
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: v0.3 块公式 % marqdo: var=
|
||||
description: 无空 RHS;块内 TeX 注释绑定 formula
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
**print text=`f`**
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: v0.3 行内 $ 传统绑定
|
||||
description: `g` = $x+1$ → formula(无 % marqdo)
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`g` = $x + 1$
|
||||
|
||||
**print text=`g`**
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: View 文档面演示(叙述 · 分支 · 循环)
|
||||
description: 给 marqdo view Browse 用的稍长样例:散文保真、变量高亮、分支命中与循环次数标注
|
||||
markup: v0.3
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
本页演示 **view 文档面**:叙述文字保留,可执行标记高亮,跑完后把变量值、分支命中与循环次数引出到段落下方。
|
||||
|
||||
先准备一份小测验的原始分数表`分数表`:
|
||||
|
||||
`分数表` =
|
||||
|
||||
| 分 |
|
||||
|----|
|
||||
| 92 |
|
||||
| 67 |
|
||||
| 45 |
|
||||
| 88 |
|
||||
|
||||
我们用累加器`总分`和计数器`人数`从零开始,遍历每一行分数:
|
||||
|
||||
**总分 = 0**
|
||||
**人数 = 0**
|
||||
|
||||
- [分](分数表)
|
||||
**总分 = 总分 + 分**
|
||||
**人数 = 人数 + 1**
|
||||
> print text=录入分数 `分`
|
||||
|
||||
遍历结束后计算平均分`均分`(人数不为零时):
|
||||
|
||||
**均分 = 总分 / 人数**
|
||||
|
||||
接着按均分给出等级文案`等级`——这是一条三路分支:
|
||||
|
||||
1. `均分` >= 85
|
||||
**等级 = "优秀"**
|
||||
2. `均分` >= 60
|
||||
**等级 = "及格"**
|
||||
3. *
|
||||
**等级 = "需补习"**
|
||||
|
||||
最后打印摘要,并两次调用下方的「等级说明」(便于 view 下拉切换调用帧):
|
||||
|
||||
> print text=人数 `人数` · 均分 `均分` · 等级 `等级`
|
||||
**说明 = > 等级说明 等级=等级**
|
||||
> print text=`说明`
|
||||
**对照 = > 等级说明 等级="优秀"**
|
||||
> print text=对照:`对照`
|
||||
|
||||
## 等级说明
|
||||
|
||||
对于输入变量`等级`,我们按字面再分支一次,返回一句说明文字。
|
||||
|
||||
1. `等级` == "优秀"
|
||||
*"均分很高,保持节奏即可。"*
|
||||
2. `等级` == "及格"
|
||||
*"已过线,仍可把薄弱项补一补。"*
|
||||
3. *
|
||||
*"建议安排复习周,再测一次。"*
|
||||
Reference in new issue
Block a user