soundscript-lang/soundscript

# soundscript

soundscript 是一个用于 TypeScript 项目的健全性检查器和语言工具层。 适用于 macOS、Linux 和 Windows 的预编译 CLI 可在 GitHub releases 中下载。 预期稳定的 v1 接口包括：检查器，`.ts` / `.sts` 混合采用方案，VS Code 扩展，一个非常小的标准库，以及一个有限的宏接口。更广泛的宏工作和 Wasm 仍处于实验阶段。 为了最快地了解内置接口和推荐的编码模式，请参阅 [docs/reference/builtin-modules.md](docs/reference/builtin-modules.md)、 [docs/guides/idiomatic-soundscript.md](docs/guides/idiomatic-soundscript.md) 和 [docs/guides/common-rewrites.md](docs/guides/common-rewrites.md)。 它添加了第二种文件类型 `.sts`，用于在更严格的规则集下检查代码。普通的 `.ts` 文件保持正常的 TypeScript 行为。其目标是渐进式采用：将您关心的代码库部分移入 `.sts`，将其余部分保留为 `.ts`，并使互操作变得显式。 ## 状态 面向发布的 v1 接口包括： - `.sts` 用于健全的代码 - 混合的 `.ts` / `.sts` 项目 - `soundscript check` - LSP 支持 - 通过编译器提供的 `sts:macros` 内置模块进行 import 作用域的宏编写 - 用户编写的宏模块是 `.macro.sts` 编译时插件模块，而不是普通的 `.sts`、`.ts` 或 `.js` 脚本 - 编译器拥有的内置模块位于 `sts:*` 下，稳定的 v1 接口以 `sts:prelude`、`sts:result`、`sts:match`、`sts:failures`、`sts:url`、`sts:fetch`、`sts:text`、`sts:random`、`sts:json`、`sts:compare`、`sts:hash`、`sts:decode`、`sts:encode`、`sts:codec`、`sts:derive`、`sts:async`、`sts:hkt`、`sts:typeclasses` 和 `sts:macros` 为中心 - 规范的运行时/工具链 npm 包 `@soundscript/soundscript`，其生成的运行时和 TS 互操作导入位于 `@soundscript/soundscript/*` 下 本仓库还包含超出稳定 v1 合约的更广泛的已实现实验性工作。这包括 `soundscript compile` 路径，实验性内置接口（例如 `sts:numerics`、`sts:value` 和 `sts:experimental/*`），`#[newtype]` 和 `#[value]`，证明和框架宏（如 `#sql`、`#css`、`#graphql` 和 `#component`），以及更广泛的公共 Wasm 目标/运行时矩阵工作。这些接口存在于仓库中，但它们不属于稳定的面向发布的 v1 合约。 ## 快速开始 构建 CLI： ``` deno task build ./bin/soundscript --help ``` 启动一个新项目： ``` ./bin/soundscript init ./bin/soundscript check ``` 这会创建 `src/main.sts` 和一个包含 `src/**/*.ts` 和 `src/**/*.sts` 的 `tsconfig.json`。 将 soundscript 添加到现有的 TypeScript 项目： ``` ./bin/soundscript init --mode existing ./bin/soundscript check --project tsconfig.soundscript.json ``` 这会创建一个 `tsconfig.soundscript.json` 覆盖文件，这样您就可以开始添加 `.sts` 文件，而无需重写项目的其余部分。 用于 CI 或工具链： ``` ./bin/soundscript check --project tsconfig.soundscript.json --format json ./bin/soundscript check --project tsconfig.soundscript.json --format ndjson ./bin/soundscript deno run src/main.sts ./bin/soundscript explain SOUND1002 ``` 对于本地 Node 执行，请使用 `@soundscript/register`： ``` node --import @soundscript/register src/main.sts ``` 您还可以选择将特定的 `.ts` / `.tsx` / `.mts` / `.cts` 文件加入本地的 soundscript 行为，而无需重命名它们： ``` { "soundscript": { "include": ["src/**/*.ts", "src/**/*.tsx"] } } ``` `@soundscript/register` 和 `soundscript deno` 期望 `@soundscript/soundscript` 已安装在当前项目或祖先工作区中，因为转换后的依赖图会导入该运行时包。 对于已发布的库，预期的包结构是： - 面向 TypeScript 和运行时使用者的普通 ESM `js + d.ts` - 在 `package.json#soundscript.exports` 下提供已编写的 `.sts` 源码 - `soundscript build` 作为规范的包生成流程 - `@soundscript/register` 和 `soundscript deno` 作为混合 `.ts/.sts` 应用程序的本地运行时包装器 - 面向本地源码驱动应用和打包器的显式适配器包：`@soundscript/register`、`@soundscript/bun-plugin`、`@soundscript/vite` 和 `@soundscript/webpack-loader` - 源映射回原始的 `.sts`，以便堆栈跟踪和调试器保留在编写的源码上 当前的仓库划分如下： - `soundscript` 用于检查器、CLI、LSP、运行时包以及第一方适配器使用的通用项目转换支持 - `website` 用于公共文档站点和镜像参考页面 - `adapters` 用于显式适配器包及其特定于宿主的实现 - `editors` 用于编辑器客户端，例如 VS Code 扩展和 `@soundscript/tsserver-plugin` 公共网站和文档现在位于独立的网站仓库中： [soundscript-lang/website](https://github.com/soundscript-lang/website)。 叶子适配器包不再在此仓库中提供。请使用独立的适配器仓库： [soundscript-lang/adapters](https://github.com/soundscript-lang/adapters)。 编辑器包不再在此仓库中提供。请使用独立的编辑器仓库： [soundscript-lang/editors](https://github.com/soundscript-lang/editors)。 对于包生成： ``` ./bin/soundscript build --project tsconfig.soundscript.json ``` 预期的平台设计受 Deno 启发： - 优先使用 Web 标准 API - 保持标准库模块小而可组合 - 在当前运行时支持的情况下，暴露可移植的全局对象和叶子模块（如 `fetch`、`URL` 和文本编码） - 将特定于宿主的行为保留在显式包装器之后，而不是承诺提供额外稳定的运行时模块 此包模型专为外部宏编写的库和框架而设计。soundscript 仓库仅保留针对打包宏解析和运行时具体化的小型通用固定装置覆盖范围；框架实现现在位于其各自的仓库中。 退出代码如下： - `0` 表示成功且无阻塞性诊断 - `1` 表示项目诊断或不支持的代码发现 - `2` 表示 CLI 用法、项目设置/配置失败或意外的内部工具错误 ## 发布自动化 规范的发布版本来自 [src/cli/cli.ts](src/cli/cli.ts)。 对于普通的公开发布，在那里提升 `VERSION`，推送 `main`，然后运行 `Publish Release` GitHub Actions 工作流。它会： - 运行发布检查 - 准备并发布 npm 包集 - 创建并推送 `v` 标签 - 创建 GitHub release - 附上平台 CLI 存档和校验和 该工作流设置为从 GitHub Actions 进行 npm 可信发布。必须将 npm 配置为信任此仓库中 `publish-release.yml` 工作流文件，以用于发布集中的每个包： - `@soundscript/cli-darwin-arm64` - `@soundscript/cli-darwin-x64` - `@soundscript/cli-linux-arm64` - `@soundscript/cli-linux-x64` - `@soundscript/cli-win32-x64` - `@soundscript/soundscript` - `soundscript` 如果在 `npm publish` 期间 npm 返回 `404`，通常的原因是尚未添加该包的可信发布者设置。该工作流还需要 GitHub 的 `id-token: write` 权限，这已在工作流文件中配置。 在使用对所有七个包具有写入权限的账户登录 npm 后，您可以从 shell 批量配置包集： ``` for package in \ @soundscript/cli-darwin-arm64 \ @soundscript/cli-darwin-x64 \ @soundscript/cli-linux-arm64 \ @soundscript/cli-linux-x64 \ @soundscript/cli-win32-x64 \ @soundscript/soundscript \ soundscript do npm trust github "$package" \ --repo soundscript-lang/soundscript \ --file publish-release.yml \ --yes sleep 2 done ``` 如果您需要将 CLI 存档重新附加到现有 release，请使用单独的 `Backfill CLI Assets` 工作流。 ## `.sts` 的含义 `.sts` 文件在 soundscript 中进行检查。 `.ts` 文件保持原样。 当 `.sts` 代码导入普通的 TypeScript、JavaScript 或仅声明的包时，该导入需要 `// #[interop]`： ``` // #[interop] import { readConfig } from './legacy.ts'; ``` 从另一个方向来看，`.ts` 可以在没有任何注解的情况下导入 `.sts`。它会看到 `.sts` 模块的一个投影的公共 TypeScript 接口。 这就是采用模型。现有的 TypeScript 保留在原位。新的或关键的代码可以移入 `.sts`。 ## 剩余的粗糙边缘 soundscript 移除了大量 TypeScript 不健全的路径，但它仍然存在于 JS/TS 运行时语义中。主要剩余的粗糙边缘是： - `null` 与 `undefined`，尤其是在 JSON、regex 和可信的 interop 边界处 - 任意的外部抛出和拒绝；启用扩展的源码将 `catch (error)` 和内置的 Promise 拒绝处理程序规范化为普通的 `Error`，但其他边界仍然需要显式规范化，例如 `sts:failures.normalizeThrown(...)` - 稳定的 v1 仍然默认使用普通的 JS `number` 行为，包括 `NaN`、`Infinity` 和 `-0`；该仓库还包含在 `sts:numerics` 下的实验性机器数值工作，但这超出了稳定的 v1 合约 - 稳定的 v1 在处理相同形状的 interface 和 object 值时仍然严重依赖于结构化类型；类名义性加上 `#[newtype]` 和 `#[value]` 存在于仓库中，但更广泛的名义和值语义故事仍超出了稳定的 v1 合约 - 目前没有积极努力从语言中移除原始的 `null`；它仍然是诚实平台模型的一部分 这些边界的面向发布的合约在 [docs/reference/v1-user-contract.md](docs/reference/v1-user-contract.md) 中。 ## 示例 ``` // src/math.sts export function area(radius: number): number { return Math.PI * radius * radius; } const raw = JSON.parse('{"radius": 3}'); if ( typeof raw === 'object' && raw !== null && 'radius' in raw && typeof raw.radius === 'number' ) { console.log(area(raw.radius)); } ``` 这里没有新语法。区别在于检查器。 ## 命令 主要命令包括： - `soundscript init` - `soundscript check` - `soundscript build` - `soundscript expand` - `soundscript deno` - `soundscript explain` - `soundscript lsp` 该仓库还附带了 `soundscript compile`。`compile` 和更广泛的编译器 / Wasm 接口仍处于实验阶段；检查器仍然是主要入口点。 ## 编辑器支持 语言服务器通过 stdio 运行： ``` soundscript lsp ``` 在单独的 editors 仓库中还有一个 VS Code 客户端： ``` git clone https://github.com/soundscript-lang/editors.git ../editors cd ../editors/packages/vscode npm install npm run compile ``` 然后： 1. 在 VS Code 中打开 `editors` 仓库根目录 2. 运行 `Run soundscript extension` 启动配置 3. 在生成的 Extension Development Host 中，使用 `File -> Open Folder...` 打开您要测试的工作区，例如 `soundscript-example` 4. 打开一个 `.sts` 文件以确认 `soundscript` 语言模式和 TextMate 语法处于活动状态 注意： - VS Code 扩展和 `@soundscript/tsserver-plugin` 位于 [soundscript-lang/editors](https://github.com/soundscript-lang/editors) - 在本地开发扩展时，请使用 `../editors/packages/vscode` - 该扩展优先使用工作区安装的 `soundscript` 二进制文件，除非您覆盖 `soundscript.server.command`，否则它会回退到 PATH - `soundscript.server.*` 设置仅配置已加载的扩展如何启动语言服务器；这些设置不会让 VS Code 发现该扩展 - 当前基于自定义语法的语法高亮仅适用于 `.sts`；`.ts` 和 `.tsx` 使用内置的 TypeScript 语法，并且仅从 soundscript 获取 LSP 功能 当前 LSP 支持包括诊断、悬停提示、签名帮助、定义、引用、重命名、补全、文档符号、格式化、语义 token 以及代码操作/快速修复。 ## 仓库布局 该仓库还包含： - 检查器和 CLI - `.ts` / `.sts` 互操作 - LSP - 宏工作 - 编译器 / Wasm 工作 您不需要宏或 Wasm 即可将 soundscript 用作检查器。 ## 开发 维护者工具链是 Deno： ``` deno task build deno task check deno task fmt deno task lint deno task test deno task verify ``` ## 文档 从这里开始： - [docs/architecture/spec.md](docs/architecture/spec.md) - [docs/project/roadmap.md](docs/project/roadmap.md) - [docs/README.md](docs/README.md) - [docs/reference/v1-user-contract.md](docs/reference/v1-user-contract.md)

标签：CLI 工具, LSP, MITM代理, npm包, TypeScript, VS Code 扩展, Wasm, WebAssembly, 云安全监控, 代码分析, 代码重构, 健全性检查, 凭证管理, 前后端协同, 后端开发, 增量迁移, 安全插件, 宏, 编程语言, 编译器, 语言工具链, 静态分析, 静态类型检查