Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ed31a2b31d | ||
|
|
56ab52356f | ||
|
|
2e425c3010 |
No files matched your search
@@ -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,8 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **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`
|
||||
|
||||
@@ -8,6 +8,39 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## 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.3.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -603,7 +603,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.1.1"
|
||||
version = "1.3.0"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "1.2.0"
|
||||
version = "1.3.0"
|
||||
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,8 +149,9 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v1.2.0)
|
||||
## 现状(v1.3.0)
|
||||
|
||||
- **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)
|
||||
@@ -151,14 +159,15 @@ marqdo catalog public -o .marqdo
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
|
||||
- **`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 +176,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.3.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
@@ -182,7 +191,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.3.0 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -221,7 +230,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.3.0
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.2.0"
|
||||
version = "1.3.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
Vendored
+8
@@ -1,3 +1,11 @@
|
||||
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)。
|
||||
|
||||
+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)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+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.3.0
|
||||
@@ -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"**
|
||||
|
||||
+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=`工程知识目录`*
|
||||
|
||||
## 解析
|
||||
+ `任务`
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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,516 @@
|
||||
//! 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" {
|
||||
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" {
|
||||
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()
|
||||
}
|
||||
@@ -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;
|
||||
|
||||
+421
-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,
|
||||
@@ -119,13 +127,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 +146,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 +287,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
|
||||
@@ -354,13 +533,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()?,
|
||||
|
||||
@@ -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*
|
||||
+162
@@ -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();
|
||||
|
||||
Reference in new issue
Block a user