mongoose-studio/alcaparra-lsp

# alcaparra-lsp ### 由 Mongoose Studio 出品      **alcaparra-lsp** 是 [AlcaparraLang](https://github.com/mongoose-studio/alcaparra-lang) 的官方语言服务器。 它将 `.caper` 文件转化为完整的开发体验：在你的编辑器中直接提供实时诊断、智能自动补全、代码导航和专业的工具链。 它基于 [tower-lsp](https://github.com/ebkalderon/tower-lsp) 实现了 LSP 3.17 协议，并为 `.caper` 和 `.capercfg` 文件提供实时诊断、上下文自动补全、文档悬停提示、跳转定义、重命名、格式化以及完整的语义高亮。 它可以与任何兼容 LSP 的编辑器配合使用。官方集成的插件有： - **[alcaparra-vscode](https://github.com/mongoose-studio/alcaparra-vscode)** — Visual Studio Code 扩展 - **[alcaparra-intellij](https://github.com/mongoose-studio/alcaparra-intellij)** — JetBrains IDEs 插件 (IntelliJ IDEA, PHPStorm, RustRover 等) 与基础的集成或仅仅是语法高亮不同， **alcaparra-lsp** 能够真正理解代码：分析作用域，检测真实的错误， 并提供与现代编程语言相媲美的工具链。 **总而言之**：**alcaparra-lsp** 能将你的编辑器转化为真正适用于 AlcaparraLang 的开发工具……快速、精准，且毫无烦恼 🇨🇱。 ### 10 秒看懂： - 编写 `.caper` - 实时查看错误 - 自动补全函数和变量 - 像在任何现代编程语言中一样导航代码 ## 目录 - [功能特性](#funcionalidades) - [安装说明](#instalación) - [从源码构建](#desde-el-código-fuente) - [curl 脚本 (macOS / Linux)](#script-curl-macos--linux) - [macOS .pkg](#macos-pkg) - [Linux .deb](#linux-deb) - [VS Code 集成](#integración-con-vs-code) - [JetBrains 集成](#integración-con-jetbrains) - [详细功能说明](#funcionalidades-en-detalle) - [诊断](#diagnósticos) - [自动补全](#autocompletado) - [悬停提示](#hover) - [Signature Help](#signature-help) - [跳转定义](#go-to-definition) - [查找引用与重命名](#referencias-y-rename) - [语义高亮](#highlighting-semántico) - [Code Lens](#code-lens) - [格式化](#formateo) - [Document Symbols](#document-symbols) - [Color Scheme](#color-scheme) - [项目配置 (.capercfg)](#configuración-del-proyecto-capercfg) - [架构](#arquitectura) - [开发](#desarrollo) - [项目状态](#estado-del-proyecto) - [许可证](#licencia) - [支持](#apoyo) - [作者](#autor) - [贡献](#contribuciones) ## 功能特性 | 能力 | 描述 | |-----------|-------------| | **诊断** | 语法错误、未声明的变量、`MISSING_EMIT`、`DEAD_EMIT`、未使用的导入、修改不可变变量、重复声明 | | **自动补全** | stdlib 函数、局部变量、用户自定义函数、`use` 路径、上下文变量 | | **悬停提示** | stdlib 文档以及用户自定义函数的 `///` DocBlocks | | **Signature Help** | 在输入参数时显示当前函数的参数信息 | | **跳转定义** | 变量、局部函数、导入的函数、上下文变量 → `.capercfg` | | **引用** | 文档中某个标识符的所有出现位置 | | **Document Highlight** | 高亮当前函数作用域内的出现位置 | | **重命名** | 在整个文档中安全地重命名标识符 | | **Semantic Tokens** | 为关键字、字符串、函数、命名空间、常量、上下文变量、正则表达式模式、`true`/`false`/`null` 等提供不同的颜色 | | **Code Lens** | 在每个 `main {}` 块上方显示 ▶ 运行 按钮 | | **格式化** | 委托给 `alcaparra` 的格式化工具执行，并支持 `.capercfg` | | **Document Symbols** | 文件大纲（函数、变量、常量） | | **Workspace Cache** | 缓存已打开的文档以实现即时响应 | ## 安装说明 ### curl 脚本 (macOS / Linux) ``` curl -fsSL https://alcaparra.mongoosestudio.cl/install.sh | sh ``` 自动检测平台，并将 `caper` 和 `alcaparra-lsp` 安装到 `/usr/local/bin`。 ### macOS .pkg 从 [Releases](https://github.com/mongoose-studio/alcaparra-lang/releases) 下载安装包： ``` alcaparra-macos-arm64.pkg # Apple Silicon (M1/M2/M3/M4/M5) alcaparra-macos-x86_64.pkg # Intel ``` ### Linux .deb ``` wget https://github.com/mongoose-studio/alcaparra-lang/releases/latest/download/alcaparra-linux-x86_64.deb sudo dpkg -i alcaparra-linux-x86_64.deb ``` ### 从源码构建 需要预先安装 [AlcaparraLang](https://github.com/mongoose-studio/alcaparra-lang) 作为本地 crate（LSP 将其作为依赖项用于解析和格式化）。 ``` git clone https://github.com/mongoose-studio/alcaparra-lsp cd alcaparra-lsp cargo build --release ``` 生成的二进制文件位于 `target/release/alcaparra-lsp`。将其复制到你的 `PATH` 中或创建一个 symlink： ``` sudo ln -sf "$(pwd)/target/release/alcaparra-lsp" /usr/local/bin/alcaparra-lsp ``` 验证安装： ``` alcaparra-lsp --version ``` ## VS Code 集成 1. 从应用市场安装 **AlcaparraLang** 扩展（或者打开从 Releases 下载的 `.vsix` 文件）。 2. 打开任意 `.caper` 文件 —— LSP 将自动启动。 该扩展会检测 PATH 中的 `alcaparra-lsp` 二进制文件。如果你将其放在了其他位置，请在设置中进行配置： ``` { "alcaparra.lspPath": "/ruta/a/alcaparra-lsp", "alcaparra.caperPath": "/ruta/a/caper" } ``` **可用命令** (`Ctrl/Cmd + Shift + P`)： | 命令 | 描述 | |---------|-------------| | `AlcaparraLang: New Script` | 创建一个包含 `header + main` 模板的 `.caper` 文件 | | `AlcaparraLang: New Library` | 创建一个包含函数模板的 `.caper` 库 | | `AlcaparraLang: New Config` | 创建一个包含所有字段的 `.capercfg` 文件 | | `AlcaparraLang: Run Script` | 在可复用的终端中使用 `caper run` 运行当前文件 | | `AlcaparraLang: New Project` | 执行 `caper new <名称>` 来创建一个完整的项目 | ## JetBrains 集成 1. 从应用市场安装 **AlcaparraLang** 插件（或通过 `Settings → Plugins → Install from disk` 安装）。 2. 插件会自动检测 PATH 中的 `alcaparra-lsp`。 3. 如有必要，请在 `Settings → Tools → AlcaparraLang` 中配置路径。 **插件的额外特性：** - **专属 Color Scheme** — 可在 `Settings → Editor → Color Scheme → AlcaparraLang` 中配置 - **Cmd+Click** 上下文变量 → 跳转至 `.capercfg` - **Cmd+Click** 导入的函数 → 跳转至外部的 `.caper` 文件 - **Run Configuration** — 直接从 IDE 中运行 `.caper` 脚本，并支持传入上下文参数 - 在项目菜单中增加 **New → AlcaparraLang Script / Library** - 支持 `main {}`, `fn`, `header {}`, `if`, `foreach` 代码块的 **Folding**（折叠） - **Structure View** — 文件中函数和变量的大纲视图 - 为 `.capercfg` 提供 **JSON Schema** 支持，包含验证和自动补全 ## 详细功能说明 ### 诊断 LSP 会在每次代码改动后进行 300ms 的防抖处理，并执行三趟分析： ``` Interpreter::validate(source) → errores léxicos y de parse Interpreter::lint(source) → MISSING_EMIT, DEAD_EMIT, NO_RETURN scope::check_undefined(source) → variables/funciones no declaradas ``` **支持的诊断：** | 代码 | 严重程度 | 描述 | |--------|-----------|-------------| | `UNDEFINED_VARIABLE` | Error | 使用了未声明的变量或函数 | | `IMMUTABLE_ASSIGN` | Error | 重新赋值给 `let` 或 `const` 变量 | | `VARIABLE_REDECLARATION` | Error | 在同一作用域内重复声明名称 | | `MISSING_EMIT` | Warning | 脚本未产生任何输出 | | `DEAD_EMIT` | Warning | `emit` 无法被执行到（前方已有其他 `emit`） | | `NO_RETURN` | Warning | 函数至少有一条分支没有包含 `emit` | | `UNUSED_IMPORT` | Warning | 通过 `use` 导入的名称未被使用 | 作用域分析是**保守的**：绝不会产生误报。它能自动识别 `.capercfg` 中的上下文变量、`header {}` 中的常量、`match` 的绑定 (`n if n <= 30`)、闭包参数、`foreach` 变量以及 `catch` 块中的错误对象。 ### 自动补全 自动补全会根据光标的位置提供上下文相关的建议： - **在 `use ` 之后** — 可用的 stdlib 模块（`std.math`, `std.arrays`, `std.regex`, …）以及 `.capercfg` 中的别名（`@formulas`, `@lib`, …） - **在 `use std.math.` 之后** — 该模块下的函数（`round`, `abs`, `ceil`, …） - **在表达式中** — 导入的 stdlib 函数、用户自定义函数、已声明的变量、上下文变量 - **优先级** — 局部函数会排在最前面，其次是导入的 stdlib 函数 ``` use std.math.{ ro| } // → round, round_half_up, … let x = rou| // → round(n, decimales) ``` ### 悬停提示 当光标悬停在标识符上时，会显示相关文档： - **stdlib 函数** — 从目录中读取的签名、模块和描述 - **用户自定义函数** — 写在函数定义上方的 `///` DocBlock - **上下文变量** — 如果可用，显示 `.capercfg` 中的值 ``` /// Calcula la gratificación legal anual. /// @param sueldo Sueldo base mensual /// @param meses Meses trabajados en el año /// @returns Monto de gratificación fn calcular_gratificacion(sueldo, meses) { … } ``` 当在文件的任意位置悬停在 `calcular_gratificacion(…)` 上时，就会显示完整的 DocBlock。 ### Signature Help 当在函数调用中输入括号或逗号时，LSP 会显示该函数的参数，并高亮当前正在输入的参数： ``` round( n, decimales ) ^ ← cursor aquí: primer parámetro activo ``` ### 跳转定义 `Cmd+Click` (macOS) 或 `Ctrl+Click` 可跳转至： | 标识符 | 目标位置 | |---|---| | 局部函数 | 同一文件中的 `fn` 声明处 | | `main {}` 中的函数 | 文本声明处（回退方案） | | 导入的函数 | 外部 `.caper` 文件的声明行 | | 局部变量 | `let` / `var` 声明处 | | 上下文变量 | 项目 `.capercfg` 中该键所在的行 | ### 查找引用与重命名 - **查找引用** — 列出文档中该标识符的所有出现位置 - **Document Highlight** — 高亮当前函数作用域内的出现位置（不会跨越代码块） - **重命名** — 通过一条命令在所有出现的位置重命名该符号 ### 语义高亮 Semantic Tokens 可以为每一类 token 提供视觉上的区分。默认颜色如下： | Token | 默认颜色 | |---|---| | 关键字 (`let`, `fn`, `emit`, …) | 取决于 IDE 主题 | | 字符串 | 取决于 IDE 主题 | | 数字 | 取决于 IDE 主题 | | 函数（声明和调用） | 蓝色 `#5fb4e8` | | `use` 中的模块 / 命名空间 | 紫色 `#c678dd` | | `use` 中的导入名称 | 蓝色 `#5fb4e8` | | 常量 (`const`) | 主题的 `enumMember` 颜色 | | 上下文变量 (`.capercfg`) | 绿色 `#9bba2c`，**加粗**，带下划线 | | 可变变量 (`var`) | 带有细微的下划线 | | 正则表达式模式 | 金色 `#e5c07b` | | `true` / `false` / `null` | 橙色 `#d19a66` | | DocBlocks `///` | 主题的文档注释颜色 | | `@param`, `@returns` 标签 | 主题的文档注释标签颜色，加粗 | 所有颜色均可在两种 IDE 中进行自定义（参见 [Color Scheme](

标签：Rust, SOC Prime, 云安全监控, 代码补全, 开发工具, 网络流量审计, 语言服务协议, 通知系统, 静态分析