From ecc87f173f4c1e2572c0fe543a456687d1e0488e Mon Sep 17 00:00:00 2001 From: _ov4 Date: Tue, 13 Oct 2026 06:20:22 +0000 Subject: docs: use English and separate plugin agent guidance Co-Authored-By: Claude Fable 5.1 --- plugin/AGENTS.md | 8 ++++-- plugin/AGENTS/ARCH.md | 65 ++++++++++++++++++++++++++++++++++++++++++++ plugin/AGENTS/DEVELOPMENT.md | 63 ++++++++++++++++++++++++++++++++++++++++++ plugin/README.md | 55 ++++++++----------------------------- plugin/test/brackets.test.js | 2 +- 5 files changed, 146 insertions(+), 47 deletions(-) create mode 100644 plugin/AGENTS/ARCH.md create mode 100644 plugin/AGENTS/DEVELOPMENT.md (limited to 'plugin') diff --git a/plugin/AGENTS.md b/plugin/AGENTS.md index f0b45b5..721c6fd 100644 --- a/plugin/AGENTS.md +++ b/plugin/AGENTS.md @@ -1,3 +1,7 @@ -Refer to all markdown files in `plugin/AGENTS/` +Refer to all markdown files in `plugin/AGENTS/`. -@AGENTS/HOW_TO_COMMIT.md (apply global commit conventions) \ No newline at end of file +- `plugin/AGENTS/ARCH.md`: implementation, language rules and upstream reuse. +- `plugin/AGENTS/DEVELOPMENT.md`: development, verification and packaging. + +Apply the global conventions in `AGENTS/CONVENTIONS.md` and +`AGENTS/HOW_TO_COMMIT.md`. diff --git a/plugin/AGENTS/ARCH.md b/plugin/AGENTS/ARCH.md new file mode 100644 index 0000000..1f9e84c --- /dev/null +++ b/plugin/AGENTS/ARCH.md @@ -0,0 +1,65 @@ +# Plugin architecture + +The extension registers `cie-pseudocode` for `.cps` files. It targets VS Code 1.85+ +and dark themes. Runtime code uses CommonJS JavaScript and the VS Code API, with +no npm runtime dependencies or connection to the compiler or cpptools. + +## Native editor capabilities and upstream references + +- VS Code provides the TextMate engine, theme scope resolution, bracket pair + colors, automatic bracket closing, formatting commands and keybindings. +- `language-configuration.json` adapts the built-in C++ configuration for CIE's + comments, brackets, quote pairs and identifiers. +- `syntaxes/cie-pseudocode.tmLanguage.json` adapts small C++ comment, quote and + comma rules and uses the same general token scope categories. CIE keyword, + builtin, number and operator patterns are locally defined. +- cpptools was consulted for provider registration. Its formatter and language + server are not called, imported or bundled. This extension is not a cpptools + fork. The formatting API accepts locally computed edits; it does not implement + CIE indentation itself. + +Native `indentationRules` and `onEnterRules` are not currently configured. The +on-type provider uses the same custom block-depth engine as selection formatting. + +References, ignored by Git and excluded from the VSIX: + +- `reference/vscode-cpptools/`: shallow clone of + https://github.com/microsoft/vscode-cpptools +- `reference/vscode-cpp/`: original configuration and grammar from + https://github.com/microsoft/vscode/tree/main/extensions/cpp + +Source attribution is retained in `ThirdPartyNotices.md`. + +## Custom CIE behavior + +- `src/extension.js` registers range and on-type formatting providers and manages + invalid bracket decorations for visible editors. Language changes reopen + documents, so refresh on document open as well as edits and editor changes. +- `src/indentation.js` computes block depth from earlier lines and returns edits + to leading whitespace only. A selection ending at column zero excludes that + final line. Formatting is idempotent and preserves line endings and other text. +- `src/lexical.js` masks quotes and comments while preserving UTF-16 offsets. +- `src/brackets.js` uses a stack to report unmatched opening and closing brackets + and crossed types. Only invalid brackets receive the red decoration; native + bracket coloring handles valid pairs. + +## Language rules and defaults + +Follow the current compiler, rather than implementing every PDF feature: + +- Uppercase, case-sensitive keywords; ASCII `<-` assignment; `//` comments. +- Double-quoted strings and single-quoted characters have no escapes or multiline + continuation. The compiler accepts `'''` as a quote character literal. +- Blocks: IF/THEN/ELSE/ENDIF, WHILE/DO/ENDWHILE, REPEAT/UNTIL, FOR/NEXT, + FUNCTION/ENDFUNCTION, PROCEDURE/ENDPROCEDURE and record TYPE/ENDTYPE. +- Separate THEN and DO lines activate the pending block once. Enum and pointer + `TYPE Name = ...` declarations do not open a record block. +- Builtins: LENGTH, MID, RIGHT, LEFT, LCASE, UCASE, ASC, CHR, IS_NUM, NUM_TO_STR, + STR_TO_NUM and EOF. See the table in `lib/CodeGen/CodeGen.cc`. +- CASE, classes, SET, DATE and random-file operations are outside the current + plugin scope. Do not add them without an explicit scope change. + +Language defaults use real Tabs, display width 4, disabled indentation detection, +full automatic indentation, on-type formatting and native bracket pair colors. +The default formatter is `ovfor4.cie-pseudocode`. User and workspace settings can +override editor defaults. diff --git a/plugin/AGENTS/DEVELOPMENT.md b/plugin/AGENTS/DEVELOPMENT.md new file mode 100644 index 0000000..6a7da98 --- /dev/null +++ b/plugin/AGENTS/DEVELOPMENT.md @@ -0,0 +1,63 @@ +# Plugin development + +Keep `plugin/README.md` short and focused on installation and use. Put developer +and AI notes here and in `ARCH.md`. All project text must be in English. + +## Commands + +Use Node.js 22+ for development. From `plugin/`: + +```sh +npm ci --ignore-scripts +npm run check +npm test +npm run package +``` + +`npm run package` runs syntax checks and the existing Node tests, then uses vsce +to generate `cie-pseudocode-0.1.0.vsix`. Runtime dependencies are not bundled. +`@vscode/vsce`, `vscode-textmate` and `vscode-oniguruma` are development tools only. + +Do simple verification before each feature commit and follow the global commit +instructions. Do not introduce a complex test framework for routine changes. + +## Verification + +The existing tests check real TextMate tokenization, nested block indentation, +selection context, idempotence and bracket errors. Keep Unicode offset tests, +using English text and non-CJK characters such as an emoji. + +For changes to editor integration, check in VS Code with a dark theme: + +- Open `.cps` and confirm the language mode and syntax colors. +- Press Enter after a block header and type an ending keyword to check Tab depth. +- Format a selection inside a nested block and check its surrounding context. +- Check mixed bracket nesting, unmatched left/right brackets, quotes and comments. +- Repair errors and switch language or files to check decoration cleanup. + +Existing local editor smoke scripts, if present, live under the ignored +`reference/vscode-smoke/` directory. They are not a required build dependency. + +## Packaging and installation + +`.vscodeignore` excludes tests, agent instructions, dependencies and build +artifacts. Git ignores dependencies, VSIX files and editor test downloads. +Check the generated package contains the runtime files, grammar, language +configuration, concise English README and notices, without `AGENTS/` or tests. + +For a local installation, use the Extensions panel's **Install from VSIX...** or: + +```sh +code --install-extension cie-pseudocode-0.1.0.vsix --force +``` + +In a remote terminal, `code` installs into the connected remote editor. For an +isolated Electron test installation, unset `VSCODE_IPC_HOOK_CLI` and explicitly +set both `--user-data-dir` and `--extensions-dir` on that test editor's CLI. +For GUI tests in this environment, also unset `ELECTRON_RUN_AS_NODE`; a virtual +display may be needed. Avoid changing the user's active editor during isolated +tests. + +If user settings disable defaults, inspect the `[cie-pseudocode]` editor settings +declared in `package.json`: real Tabs, tab size 4, automatic indentation, on-type +formatting, the extension as default formatter and enabled bracket pair colors. diff --git a/plugin/README.md b/plugin/README.md index aa57cc8..a05c5fa 100644 --- a/plugin/README.md +++ b/plugin/README.md @@ -1,57 +1,24 @@ # CIE Pseudocode -用于本项目 `.cps` 文件的 VS Code 插件。需要 VS Code 1.85 或更新版本，仅适配深色主题，语法颜色跟随当前主题，参考 C++ 的配色分类。 +VS Code support for this project's `.cps` files. Requires VS Code 1.85 or newer and a dark theme. -## 安装 +## Install -在 VS Code 的扩展面板点击右上角 `…` → **Install from VSIX…（从 VSIX 安装）**，选择 `cie-pseudocode-0.1.0.vsix`。 - -也可以在 VSIX 所在目录执行： +In the Extensions panel, choose **... > Install from VSIX...** and select `cie-pseudocode-0.1.0.vsix`, or run: ```sh code --install-extension cie-pseudocode-0.1.0.vsix ``` -打开 `.cps` 文件后，右下角语言模式应显示 **CIE Pseudocode**。建议使用 **Dark+** 或其他深色主题。 - -## 使用 - -- **自动缩进**：默认每层一个真实 Tab，显示宽度为 4。块开始后回车自动缩进，输入完整的 `ELSE`、`ENDIF`、`NEXT` 等关键字时自动回退。 -- **整理选区**：选中代码，按 macOS 的 **⌘K，然后 ⌘F**；Windows/Linux 为 **Ctrl+K，然后 Ctrl+F**。也可以右键 → **Format Selection（格式化选区）**。只整理选中行的行首缩进，使用前文确定层级，保留其他文本和换行格式。空行整理后为空。 -- **括号**：圆括号和方括号按嵌套层级上色；落单左括号、落单右括号及类型错配立即变红，补齐后恢复。字符串、字符和注释中的括号不参与检查。 -- **高亮**：关键字、类型、布尔值、运算符、字符串、字符、数字、注释和 12 个内置函数使用对应的 C++ 风格配色分类。 - -缩进支持 IF/ELSE、WHILE、REPEAT、FOR、FUNCTION、PROCEDURE 和记录 TYPE；`THEN`、`DO` 可以单独成行。枚举和指针的单行 `TYPE ... = ...` 不增加缩进。 - -关键字必须大写；赋值使用 `<-`；注释使用 `//`；字符串及字符没有反斜杠转义。仅覆盖当前编译器已实现的语法，暂不支持 PDF 中的 CASE、类、SET、DATE 等未实现语法。 - -示例在 [examples/highlighting.cps](examples/highlighting.cps)。这是编辑辅助插件，编译与运行仍使用项目的 `cpsc` 命令。 - -如果用户或工作区设置覆盖了插件默认值，可在 VS Code 设置中确认： - -```json -"[cie-pseudocode]": { - "editor.insertSpaces": false, - "editor.tabSize": 4, - "editor.detectIndentation": false, - "editor.autoIndent": "full", - "editor.formatOnType": true, - "editor.defaultFormatter": "ovfor4.cie-pseudocode", - "editor.bracketPairColorization.enabled": true -} -``` - -## 开发与打包 +Open a `.cps` file. The language mode should show **CIE Pseudocode**. -在 `plugin/` 目录下执行，开发依赖需要 Node.js 22 或更新版本： +## Features -```sh -npm ci --ignore-scripts -npm run check -npm test -npm run package -``` +- C++ style syntax colors that follow your dark theme. +- Automatic Tab indentation and outdent for block keywords. +- **Format Selection**: select code, then press **Cmd+K, Cmd+F** on macOS or **Ctrl+K, Ctrl+F** on Windows/Linux. Only indentation changes. +- Colored `()` and `[]` pairs; unmatched brackets turn red. Quotes and comments are ignored. -打包命令会先检查语法并运行简单测试，然后生成 `cie-pseudocode-0.1.0.vsix`。插件运行时没有 npm 依赖，不需要安装编译器或 cpptools。VSIX、依赖和测试产物不提交 Git。 +Use uppercase keywords, `<-` for assignment and `//` for comments. Support matches the current compiler. Compile and run with `cpsc` separately. -语言配置、注释/字符串规则及配色 scope 改造自 [VS Code 内置 C++ 扩展](https://github.com/microsoft/vscode/tree/main/extensions/cpp)，provider 注册方式参考 [cpptools](https://github.com/microsoft/vscode-cpptools)。本仓库的参考克隆位于 `reference/vscode-cpptools/`，原始 C++ 配置及 grammar 位于 `reference/vscode-cpp/`，均不纳入插件包。 +See [examples/highlighting.cps](examples/highlighting.cps) for an example. diff --git a/plugin/test/brackets.test.js b/plugin/test/brackets.test.js index acb18d0..e144335 100644 --- a/plugin/test/brackets.test.js +++ b/plugin/test/brackets.test.js @@ -22,7 +22,7 @@ test('comments and quotes are ignored with correct UTF-16 offsets after Unicode assert.deepEqual(unmatchedBrackets('OUTPUT "[( //" // )]\nOUTPUT \'[\''), []); const unfinished = 'OUTPUT "unfinished [\r\nA['; assert.deepEqual(unmatchedBrackets(unfinished), [unfinished.length - 1]); - const unicode = 'OUTPUT "你好😀"\r\nA['; + const unicode = 'OUTPUT "Hello😀"\r\nA['; assert.deepEqual(unmatchedBrackets(unicode), [unicode.length - 1]); // Backslashes do not escape CIE quotes. assert.deepEqual(unmatchedBrackets('"x\\"['), [4]); -- cgit v1.3.1-4-g156e