From f4f798a4d0192879429e974d2e4af2d335f4abc1 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 5 Aug 2026 16:26:33 +0800 Subject: [PATCH] Bootstrap VS Code extension workspace and development norms. Add Marqdo language registration, TextMate grammar stub, and docs for the vscode-extension branch workflow. Co-authored-by: Cursor --- .gitignore | 4 +- vscode-extension/.gitignore | 7 ++ vscode-extension/.vscodeignore | 9 ++ vscode-extension/ARCHITECTURE.md | 61 ++++++++++ vscode-extension/DEVELOPMENT.md | 60 ++++++++++ vscode-extension/README.md | 105 ++++++++++++++++++ vscode-extension/language-configuration.json | 26 +++++ vscode-extension/package.json | 57 ++++++++++ vscode-extension/src/extension.ts | 13 +++ .../syntaxes/marqdo.tmLanguage.json | 89 +++++++++++++++ vscode-extension/tsconfig.json | 14 +++ 11 files changed, 442 insertions(+), 3 deletions(-) create mode 100644 vscode-extension/.gitignore create mode 100644 vscode-extension/.vscodeignore create mode 100644 vscode-extension/ARCHITECTURE.md create mode 100644 vscode-extension/DEVELOPMENT.md create mode 100644 vscode-extension/README.md create mode 100644 vscode-extension/language-configuration.json create mode 100644 vscode-extension/package.json create mode 100644 vscode-extension/src/extension.ts create mode 100644 vscode-extension/syntaxes/marqdo.tmLanguage.json create mode 100644 vscode-extension/tsconfig.json diff --git a/.gitignore b/.gitignore index ae8fa23..dadca75 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -/target/ +/target/ /dist/ **/*.rs.bk .idea/ @@ -11,8 +11,6 @@ /public/index.html /public/pages/ -# VS Code extension lives on branch `vscode-extension` only (see doc/design/vscode-extension.md) -/vscode-extension/ # Python spike venv (local) spike/.venv/ diff --git a/vscode-extension/.gitignore b/vscode-extension/.gitignore new file mode 100644 index 0000000..ec69cf3 --- /dev/null +++ b/vscode-extension/.gitignore @@ -0,0 +1,7 @@ +.vscode/** +.vscode-test/** +node_modules/** +out/** +*.vsix +npm-debug.log* +.DS_Store diff --git a/vscode-extension/.vscodeignore b/vscode-extension/.vscodeignore new file mode 100644 index 0000000..202b045 --- /dev/null +++ b/vscode-extension/.vscodeignore @@ -0,0 +1,9 @@ +.vscode/** +.vscode-test/** +src/** +tsconfig.json +node_modules/** +.gitignore +**/*.map +**/*.ts +!out/**/*.js diff --git a/vscode-extension/ARCHITECTURE.md b/vscode-extension/ARCHITECTURE.md new file mode 100644 index 0000000..d6b1cff --- /dev/null +++ b/vscode-extension/ARCHITECTURE.md @@ -0,0 +1,61 @@ +# 架构(规范) + +## 进程边界 + +``` +┌─────────────────────────────┐ +│ VS Code Extension Host │ +│ · 语言配置 / TextMate │ +│ · 命令、任务、Problems │ +│ · (日后)LSP client │ +│ · (日后)DAP client │ +└─────────────┬───────────────┘ + │ spawn / stdio + ▼ +┌─────────────────────────────┐ +│ marqdo CLI(已安装) │ +│ · run / catalog / debug │ +│ · 诊断文案与行号真相 │ +└─────────────────────────────┘ +``` + +扩展 **不嵌入** Rust 解释器;分发上用户安装 CLI(或日后可选打包 sidecar,仍属后置决策)。 + +## 语言 id + +- VS Code `languageId`: `marqdo` +- 文件:`*.mq.md`(必须保留 `.md` 后缀以便通用预览;用 `filename` / `filenamePattern` 关联,避免抢全部 Markdown) + +## 与 Markdown 扩展共存 + +`.mq.md` 同时是 Markdown。策略: + +1. **默认**用 Marqdo 语言模式(执行语义优先)。 +2. 提供命令「以 Markdown 打开预览」调用内置 Markdown preview(不切换语言 id 也可预览时,优先不破坏高亮)。 +3. 不禁用用户其它 Markdown 扩展;冲突时文档说明如何 `files.associations`。 + +## 诊断契约 + +CLI 用户可见失败: + +```text +path:line:col: message +``` + +扩展将相对路径解析到工作区 URI,`severity` 为 0-based。与语言仓 P0 诊断模型一致。 + +## 调试(P3) + +- 短期:命令「在外部打开 `marqdo debug`」或 Simple Browser 打开本地 debug URL。 +- 中期:DAP 适配器进程包装现有 debug session API(`src/view/debug_api.rs` 语义),避免第三套断点模型。 + +## OKF / catalog(P3) + +- 命令触发 `marqdo catalog -o .marqdo`。 +- 生成物已在语言仓 `.gitignore`(`.marqdo/`);扩展只负责调用与打开 `index.md` / `catalog.yaml`。 + +## 非目标(本阶段) + +- 在扩展内实现完整树遍历 / 字节码 +- 替代 `marqdo view` 静态站 +- 强制用户登录或云服务 diff --git a/vscode-extension/DEVELOPMENT.md b/vscode-extension/DEVELOPMENT.md new file mode 100644 index 0000000..d2704e1 --- /dev/null +++ b/vscode-extension/DEVELOPMENT.md @@ -0,0 +1,60 @@ +# 开发流程 + +## 环境 + +- Node.js 20+(LTS) +- VS Code 1.85+(`engines.vscode` 在 `package.json` 收紧) +- 本机已安装 **Marqdo CLI ≥ 0.1.0**(`marqdo --version`),用于 Run / catalog 集成 + +## 首次 + +```bash +git checkout vscode-extension +cd vscode-extension +npm install +``` + +按 F5(「运行扩展」)打开 Extension Development Host,打开任意 `.mq.md` 验证语言 id / 高亮。 + +## 日常脚本(约定) + +| npm script | 用途 | +|------------|------| +| `npm run compile` | `tsc -p .` → `out/` | +| `npm run watch` | 监视编译 | +| `npm run lint` | 日后 ESLint(先可空) | +| `npm run package` | `vsce package` 打 `.vsix`(发布前) | + +尚未加入的脚本:落地 `package.json` 时按上表补齐,勿引入与 Marqdo 语言仓抢戏的重型框架。 + +## 改语法 / 高亮 + +1. 对照语言仓 `doc/design/markdown-mapping.md`(以 `main` 为准)。 +2. 改 `syntaxes/*.tmLanguage.json`(或等价)。 +3. 用 `tests/` 与 `public/` 下真实 `.mq.md` 肉眼验收(Extension Host 打开语言仓 worktree)。 + +## 改 CLI 集成 + +- 子进程调用 `marqdo`,cwd = 工作区根或文件目录(与 `marqdo run` 导入/`lib/` 解析一致)。 +- 解析 stderr 的 `path:line:col: message` 写入 `DiagnosticCollection`。 +- **禁止**在扩展内重新实现解释器。 + +## 提交与推送 + +只在 **`vscode-extension` 分支** 提交本目录: + +```bash +git status # 确认在 vscode-extension +git add vscode-extension +git commit -m "…" +git push -u origin vscode-extension +``` + +不要把本目录合并进 `main`(`main` 的 `.gitignore` 会忽略它)。 + +## 验收清单(P0) + +- [ ] `.mq.md` 打开后 Language Mode = Marqdo +- [ ] `#` / `*` / `**` / `>` / 表格 / 注释行有可区分着色 +- [ ] 函数体内 `---` / `***`、空返回 `****` 不与普通 Markdown 粗体完全糊成一团(尽力) +- [ ] F5 开发宿主可重复加载,无激活期未捕获异常 diff --git a/vscode-extension/README.md b/vscode-extension/README.md new file mode 100644 index 0000000..1e74e08 --- /dev/null +++ b/vscode-extension/README.md @@ -0,0 +1,105 @@ +# VS Code 扩展(分支工作区) + +| | | +|---|---| +| 状态 | **规范起步**(伴随 Marqdo **v0.1.0** 稳定小版本) | +| 日期 | 2026-08-05 | +| 语言仓 | [`cflmy/marqdo`](https://github.com/cflmy/marqdo) `main` | +| 扩展仓形态 | **同仓库专用分支** `vscode-extension`(本目录);`main` **不跟踪**本目录 | + +--- + +## 1. 与 `public` / `gh-pages` 的类比 + +| | `public/` 用户站 | `vscode-extension/` | +|--|------------------|---------------------| +| **main** | 跟踪可执行 `.mq.md` 源 | **忽略**本目录(不进 `main` 历史) | +| **专用分支** | `gh-pages`:生成 HTML | **`vscode-extension`**:扩展源码与规范 | +| **消费者** | 浏览器 / Pages | VS Code / Open VSX / Marketplace(日后) | + +开发扩展时: + +```bash +git fetch origin +git checkout vscode-extension +cd vscode-extension +npm install +``` + +回到语言本体: + +```bash +git checkout main +``` + +可选:`git worktree add ../marqdo-vscode vscode-extension`,语言与扩展并行目录开发。 + +--- + +## 2. 目标(对齐 v0.1.0 分发) + +v0.1.0 已是「可解释 + view + debug CLI + catalog」的阶段性稳定小版本。扩展的第一阶段目标是 **编辑体验**,而不是一次做满 IDE: + +| 优先级 | 能力 | 说明 | +|--------|------|------| +| **P0** | `.mq.md` 语言登记 + 基础语法高亮 | TextMate / semantic 二选一;先 TextMate | +| **P0** | 语言配置 | 注释、括号、自动缩进粗线条 | +| **P1** | 任务 / 命令 | `marqdo run` 当前文件;探测 `PATH` / 工作区 `marqdo` | +| **P1** | 问题面板 | 把 `path:line:col: message` 诊断喂给 Problems | +| **P2** | 轻量语言特性 | 大纲(`#` 函数)、跳转到定义(同文件 / 导入) | +| **P3** | DAP / 调试 | 对接 `marqdo debug` 语义;勿与 CLI debug 页抢两套语义 | +| **P3** | OKF / catalog | 调用 `marqdo catalog`,预览生成清单 | + +原则:**扩展是 Marqdo CLI 的薄宿主**;语义以解释器与 [markdown-mapping.md](../doc/design/markdown-mapping.md) 为准,扩展不发明第二套语法。 + +--- + +## 3. 目录约定(本分支) + +``` +vscode-extension/ + README.md # 本文件:分支模型与目标 + DEVELOPMENT.md # 日常开发流程、脚本、验收 + ARCHITECTURE.md # 进程边界、与 CLI 的契约 + package.json # 扩展清单(Marketplace id 待定) + tsconfig.json + .vscodeignore + src/ + extension.ts # activate / deactivate + syntaxes/ # TextMate 语法(P0) + language-configuration.json +``` + +生成物(`out/`、`node_modules/`、`*.vsix`)不入库;见本目录 `.gitignore`。 + +--- + +## 4. 命名与发布(待拍板) + +| 项 | 建议(可改) | +|----|--------------| +| 扩展显示名 | Marqdo | +| `publisher` | `cflmy`(或组织账号) | +| `name`(包名) | `marqdo` | +| 语言 id | `marqdo` | +| 文件关联 | `*.mq.md` | + +发布渠道:先私有 / Open VSX,再 VS Marketplace。版本号与语言仓 **不必锁死同一 semver**,但发行说明应写明「需要 Marqdo CLI ≥ 0.1.0」。 + +--- + +## 5. 文档索引(语言仓 `main`) + +在 `main` 上仅保留指针,避免扩展实现泄漏进语言历史: + +- [doc/design/vscode-extension.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension.md)(`main` 上的分支说明) +- 语法:[markdown-mapping.md](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping.md) +- 诊断:[pipeline-debug.md](https://github.com/cflmy/marqdo/blob/main/doc/design/pipeline-debug.md) +- CLI debug:[view-debug.md](https://github.com/cflmy/marqdo/blob/main/doc/design/view-debug.md) +- Catalog / OKF:[catalog-cli.md](https://github.com/cflmy/marqdo/blob/main/doc/design/catalog-cli.md) + +--- + +## 6. 一句话 + +**语言在 `main`;编辑器宿主在 `vscode-extension` 分支。先高亮与 run/诊断,再 LSP/DAP;始终以 CLI 为真相源。** diff --git a/vscode-extension/language-configuration.json b/vscode-extension/language-configuration.json new file mode 100644 index 0000000..3cbf095 --- /dev/null +++ b/vscode-extension/language-configuration.json @@ -0,0 +1,26 @@ +{ + "comments": { + "lineComment": null, + "blockComment": null + }, + "brackets": [ + ["{", "}"], + ["[", "]"], + ["(", ")"] + ], + "autoClosingPairs": [ + { "open": "{", "close": "}" }, + { "open": "[", "close": "]" }, + { "open": "(", "close": ")" }, + { "open": "`", "close": "`" }, + { "open": "*", "close": "*" }, + { "open": "**", "close": "**" } + ], + "surroundingPairs": [ + ["{", "}"], + ["[", "]"], + ["(", ")"], + ["`", "`"], + ["*", "*"] + ] +} diff --git a/vscode-extension/package.json b/vscode-extension/package.json new file mode 100644 index 0000000..123972b --- /dev/null +++ b/vscode-extension/package.json @@ -0,0 +1,57 @@ +{ + "name": "marqdo", + "displayName": "Marqdo", + "description": "Language support for Marqdo (.mq.md) — code as documentation.", + "version": "0.0.1", + "publisher": "cflmy", + "engines": { + "vscode": "^1.85.0" + }, + "categories": [ + "Programming Languages" + ], + "keywords": [ + "marqdo", + "markdown", + "mq.md" + ], + "activationEvents": [ + "onLanguage:marqdo" + ], + "main": "./out/extension.js", + "contributes": { + "languages": [ + { + "id": "marqdo", + "aliases": [ + "Marqdo", + "marqdo" + ], + "extensions": [ + ".mq.md" + ], + "filenamePatterns": [ + "*.mq.md" + ], + "configuration": "./language-configuration.json" + } + ], + "grammars": [ + { + "language": "marqdo", + "scopeName": "source.marqdo", + "path": "./syntaxes/marqdo.tmLanguage.json" + } + ] + }, + "scripts": { + "vscode:prepublish": "npm run compile", + "compile": "tsc -p ./", + "watch": "tsc -watch -p ./" + }, + "devDependencies": { + "@types/node": "^20.11.0", + "@types/vscode": "^1.85.0", + "typescript": "^5.3.0" + } +} diff --git a/vscode-extension/src/extension.ts b/vscode-extension/src/extension.ts new file mode 100644 index 0000000..b8b1bac --- /dev/null +++ b/vscode-extension/src/extension.ts @@ -0,0 +1,13 @@ +import * as vscode from "vscode"; + +/** + * Marqdo VS Code extension entry. + * Keep this host thin: language contribution lives in package.json / TextMate; + * run / diagnostics / DAP come later via the marqdo CLI. + */ +export function activate(_context: vscode.ExtensionContext): void { + // P0: grammar + language id are declarative. + // P1+: register commands that spawn `marqdo`. +} + +export function deactivate(): void {} diff --git a/vscode-extension/syntaxes/marqdo.tmLanguage.json b/vscode-extension/syntaxes/marqdo.tmLanguage.json new file mode 100644 index 0000000..9682c03 --- /dev/null +++ b/vscode-extension/syntaxes/marqdo.tmLanguage.json @@ -0,0 +1,89 @@ +{ + "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json", + "name": "Marqdo", + "scopeName": "source.marqdo", + "patterns": [ + { "include": "#frontmatter" }, + { "include": "#heading" }, + { "include": "#hr-end" }, + { "include": "#call" }, + { "include": "#return" }, + { "include": "#empty-return" }, + { "include": "#statement" }, + { "include": "#list-structure" }, + { "include": "#table" }, + { "include": "#code-fence" }, + { "include": "#comment" } + ], + "repository": { + "frontmatter": { + "name": "meta.embedded.block.frontmatter.marqdo", + "begin": "\\A---\\s*$", + "end": "^---\\s*$", + "patterns": [ + { "name": "keyword.control.import.marqdo", "match": "^\\s*>\\s+.+$" }, + { "name": "string.unquoted.frontmatter.marqdo", "match": "^.+$" } + ] + }, + "heading": { + "name": "markup.heading.marqdo", + "match": "^(#{1,6})\\s+(.+)$", + "captures": { + "1": { "name": "punctuation.definition.heading.marqdo" }, + "2": { "name": "entity.name.function.marqdo" } + } + }, + "hr-end": { + "name": "keyword.control.function.end.marqdo", + "match": "^(---+|\\*{3,})\\s*$" + }, + "call": { + "name": "meta.call.marqdo", + "match": "^(\\s*)(>)\\s+(\\S+)(.*)$", + "captures": { + "2": { "name": "keyword.operator.call.marqdo" }, + "3": { "name": "entity.name.function.call.marqdo" }, + "4": { "name": "meta.call.args.marqdo" } + } + }, + "empty-return": { + "name": "keyword.control.return.empty.marqdo", + "match": "^\\s*(\\*{4}|\\*\\*\\s+\\*\\*)\\s*$" + }, + "return": { + "name": "meta.return.marqdo", + "begin": "\\*\\*", + "end": "\\*\\*", + "name": "markup.bold.return.marqdo", + "patterns": [ + { "name": "variable.other.marqdo", "match": "`[^`]+`" } + ] + }, + "statement": { + "name": "meta.statement.marqdo", + "begin": "(?