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 <cursoragent@cursor.com>
This commit is contained in:
1 parent
e08cd839be
commit
f4f798a4d0
11 files changed
+442
-3
No files matched your search
+1
-3
@@ -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/
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
.vscode/**
|
||||
.vscode-test/**
|
||||
node_modules/**
|
||||
out/**
|
||||
*.vsix
|
||||
npm-debug.log*
|
||||
.DS_Store
|
||||
@@ -0,0 +1,9 @@
|
||||
.vscode/**
|
||||
.vscode-test/**
|
||||
src/**
|
||||
tsconfig.json
|
||||
node_modules/**
|
||||
.gitignore
|
||||
**/*.map
|
||||
**/*.ts
|
||||
!out/**/*.js
|
||||
@@ -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 <workspace> -o .marqdo`。
|
||||
- 生成物已在语言仓 `.gitignore`(`.marqdo/`);扩展只负责调用与打开 `index.md` / `catalog.yaml`。
|
||||
|
||||
## 非目标(本阶段)
|
||||
|
||||
- 在扩展内实现完整树遍历 / 字节码
|
||||
- 替代 `marqdo view` 静态站
|
||||
- 强制用户登录或云服务
|
||||
@@ -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 开发宿主可重复加载,无激活期未捕获异常
|
||||
@@ -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 为真相源。**
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"comments": {
|
||||
"lineComment": null,
|
||||
"blockComment": null
|
||||
},
|
||||
"brackets": [
|
||||
["{", "}"],
|
||||
["[", "]"],
|
||||
["(", ")"]
|
||||
],
|
||||
"autoClosingPairs": [
|
||||
{ "open": "{", "close": "}" },
|
||||
{ "open": "[", "close": "]" },
|
||||
{ "open": "(", "close": ")" },
|
||||
{ "open": "`", "close": "`" },
|
||||
{ "open": "*", "close": "*" },
|
||||
{ "open": "**", "close": "**" }
|
||||
],
|
||||
"surroundingPairs": [
|
||||
["{", "}"],
|
||||
["[", "]"],
|
||||
["(", ")"],
|
||||
["`", "`"],
|
||||
["*", "*"]
|
||||
]
|
||||
}
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
@@ -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 {}
|
||||
@@ -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": "(?<!\\*)\\*(?!\\*)",
|
||||
"end": "(?<!\\*)\\*(?!\\*)",
|
||||
"name": "markup.italic.statement.marqdo"
|
||||
},
|
||||
"list-structure": {
|
||||
"name": "markup.list.marqdo",
|
||||
"match": "^(\\s*)([-+]|\\d+\\.)\\s+"
|
||||
},
|
||||
"table": {
|
||||
"name": "markup.table.marqdo",
|
||||
"match": "^\\s*\\|.*\\|\\s*$"
|
||||
},
|
||||
"code-fence": {
|
||||
"name": "markup.fenced_code.block.marqdo",
|
||||
"begin": "^\\s*```([\\w+-]*)\\s*$",
|
||||
"end": "^\\s*```\\s*$",
|
||||
"beginCaptures": {
|
||||
"1": { "name": "entity.name.tag.lang.marqdo" }
|
||||
}
|
||||
},
|
||||
"comment": {
|
||||
"name": "comment.line.marqdo",
|
||||
"match": "^.+$"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"module": "commonjs",
|
||||
"target": "ES2020",
|
||||
"outDir": "out",
|
||||
"rootDir": "src",
|
||||
"lib": ["ES2020"],
|
||||
"sourceMap": true,
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true
|
||||
},
|
||||
"exclude": ["node_modules", ".vscode-test"]
|
||||
}
|
||||
Reference in new issue
Block a user