{"id":48679309,"url":"https://github.com/soundscript-lang/soundscript","last_synced_at":"2026-04-25T00:03:18.777Z","repository":{"id":349388918,"uuid":"1198967653","full_name":"soundscript-lang/soundscript","owner":"soundscript-lang","description":"Sound checker and language tooling for TypeScript.","archived":false,"fork":false,"pushed_at":"2026-04-22T20:40:49.000Z","size":15314,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T22:28:32.219Z","etag":null,"topics":["lsp","soundscript","static-analysis","type-checker","typescript"],"latest_commit_sha":null,"homepage":"https://soundscript.dev/docs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soundscript-lang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T23:56:18.000Z","updated_at":"2026-04-22T20:40:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/soundscript-lang/soundscript","commit_stats":null,"previous_names":["soundscript-lang/soundscript"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/soundscript-lang/soundscript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundscript-lang%2Fsoundscript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundscript-lang%2Fsoundscript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundscript-lang%2Fsoundscript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundscript-lang%2Fsoundscript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soundscript-lang","download_url":"https://codeload.github.com/soundscript-lang/soundscript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundscript-lang%2Fsoundscript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32245156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lsp","soundscript","static-analysis","type-checker","typescript"],"created_at":"2026-04-10T22:08:05.613Z","updated_at":"2026-04-25T00:03:14.736Z","avatar_url":"https://github.com/soundscript-lang.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# soundscript\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./media/brand/logo-dark.png\" alt=\"soundscript logo\" width=\"520\" /\u003e\n\u003c/p\u003e\n\nsoundscript is a sound checker and language tooling layer for TypeScript projects.\n\nPrebuilt macOS, Linux, and Windows CLI downloads are attached to GitHub releases.\n\nThe intended stable v1 surface is the checker, mixed `.ts` / `.sts` adoption story, the VS Code\nextension, a very small stdlib, and a narrow macro surface. Broader macro work and Wasm remain\nexperimental.\n\nFor the fastest orientation on the builtin surface and the recommended coding patterns, see\n[docs/reference/builtin-modules.md](docs/reference/builtin-modules.md) and\n[docs/guides/idiomatic-soundscript.md](docs/guides/idiomatic-soundscript.md) and\n[docs/guides/common-rewrites.md](docs/guides/common-rewrites.md).\n\nIt adds a second file type, `.sts`, for code checked under a stricter rule set. Ordinary `.ts` files\nkeep normal TypeScript behavior. The goal is incremental adoption: move the parts of a codebase you\ncare about into `.sts`, keep the rest as `.ts`, and make interop explicit.\n\n## Status\n\nThe release-facing v1 surface is:\n\n- `.sts` for sound code\n- mixed `.ts` / `.sts` projects\n- `soundscript check`\n- LSP support\n- import-scoped macro authoring through the compiler-provided `sts:macros` builtin module\n  - user-authored macro modules are `.macro.sts` compile-time plugin modules, not ordinary `.sts`,\n    `.ts`, or `.js` scripts\n- compiler-owned builtin modules under `sts:*`, with the stable v1 surface centered on\n  `sts:prelude`, `sts:result`, `sts:match`, `sts:failures`, `sts:url`, `sts:fetch`, `sts:text`,\n  `sts:random`, `sts:json`, `sts:compare`, `sts:hash`, `sts:decode`, `sts:encode`, `sts:codec`,\n  `sts:derive`, `sts:async`, `sts:hkt`, `sts:typeclasses`, and `sts:macros`\n- the canonical runtime/toolchain npm package `@soundscript/soundscript`, with emitted runtime and\n  TS interop imports under `@soundscript/soundscript/*`\n\nThis repository also contains broader implemented experimental work beyond the stable v1 contract.\nThat includes the `soundscript compile` path, experimental builtin surfaces such as `sts:numerics`,\n`sts:value`, and `sts:experimental/*`, `#[newtype]` and `#[value]`, proof and framework macros like\n`#sql`, `#css`, `#graphql`, and `#component`, and the broader public Wasm target/runtime matrix\nwork. Those surfaces exist in the repo, but they are not the stable release-facing v1 contract.\n\n## Quick start\n\nBuild the CLI:\n\n```bash\ndeno task build\n./bin/soundscript --help\n```\n\nStart a new project:\n\n```bash\n./bin/soundscript init\n./bin/soundscript check\n```\n\nThat creates `src/main.sts` and a `tsconfig.json` that includes both `src/**/*.ts` and\n`src/**/*.sts`.\n\nAdd soundscript to an existing TypeScript project:\n\n```bash\n./bin/soundscript init --mode existing\n./bin/soundscript check --project tsconfig.soundscript.json\n```\n\nThat creates a `tsconfig.soundscript.json` overlay so you can start adding `.sts` files without\nrewriting the rest of the project.\n\nFor CI or tooling:\n\n```bash\n./bin/soundscript check --project tsconfig.soundscript.json --format json\n./bin/soundscript check --project tsconfig.soundscript.json --format ndjson\n./bin/soundscript deno run src/main.sts\n./bin/soundscript explain SOUND1002\n```\n\nFor local Node execution, use `@soundscript/register`:\n\n```bash\nnode --import @soundscript/register src/main.sts\n```\n\nYou can also opt selected `.ts` / `.tsx` / `.mts` / `.cts` files into local soundscript behavior\nwithout renaming them:\n\n```json\n{\n  \"soundscript\": {\n    \"include\": [\"src/**/*.ts\", \"src/**/*.tsx\"]\n  }\n}\n```\n\n`@soundscript/register` and `soundscript deno` expect `@soundscript/soundscript` to be installed in\nthe current project or an ancestor workspace, because the transformed graph imports the runtime\npackage.\n\nFor published libraries, the intended package shape is:\n\n- ordinary ESM `js + d.ts` for TypeScript and runtime consumers\n- shipped authored `.sts` source under `package.json#soundscript.exports`\n- `soundscript build` as the canonical package emit flow\n- `@soundscript/register` and `soundscript deno` as local runtime wrappers for mixed `.ts/.sts` apps\n- explicit adapter packages for local source-driven apps and bundlers: `@soundscript/register`,\n  `@soundscript/bun-plugin`, `@soundscript/vite`, and `@soundscript/webpack-loader`\n- source maps back to original `.sts` so stack traces and debuggers stay on authored source\n\nThe repository split is now:\n\n- `soundscript` for the checker, CLI, LSP, runtime package, and generic project-transform support\n  used by first-party adapters\n- `website` for the public docs site and mirrored reference pages\n- `adapters` for the explicit adapter packages and their host-specific implementations\n- `editors` for editor clients such as the VS Code extension and `@soundscript/tsserver-plugin`\n\nThe public website and docs now live in the standalone website repository:\n[soundscript-lang/website](https://github.com/soundscript-lang/website).\n\nThe leaf adapter packages are no longer vendored in this repo. Use the standalone adapters\nrepository: [soundscript-lang/adapters](https://github.com/soundscript-lang/adapters).\n\nThe editor packages are no longer vendored in this repo. Use the standalone editors repository:\n[soundscript-lang/editors](https://github.com/soundscript-lang/editors).\n\nFor package emit:\n\n```bash\n./bin/soundscript build --project tsconfig.soundscript.json\n```\n\nThe intended platform design is Deno-inspired:\n\n- prefer Web-standard APIs first\n- keep stdlib modules small and composable\n- expose portable globals and leaf modules such as `fetch`, `URL`, and text encoding where the\n  current runtime supports them\n- keep host-specific behavior behind explicit wrappers instead of promising extra stable runtime\n  modules\n\nThis package model is designed for external macro-authored libraries and frameworks. The soundscript\nrepo keeps only small generic fixture coverage for packaged macro resolution and runtime\nmaterialization; framework implementations now live in their own repositories.\n\nExit codes are:\n\n- `0` for success with no blocking diagnostics\n- `1` for project diagnostics or unsupported-code findings\n- `2` for CLI usage, project setup/configuration failures, or unexpected internal tool errors\n\n## Release automation\n\nThe canonical release version comes from [src/cli/cli.ts](src/cli/cli.ts).\n\nFor a normal public release, bump `VERSION` there, push `main`, then run the `Publish Release`\nGitHub Actions workflow. It will:\n\n- run the release checks\n- prepare and publish the npm package set\n- create and push the `v\u003cversion\u003e` tag\n- create the GitHub release\n- attach the platform CLI archives plus checksums\n\nThe workflow is set up for npm trusted publishing from GitHub Actions. npm must be configured to\ntrust the `publish-release.yml` workflow file in this repository for every package in the release\nset:\n\n- `@soundscript/cli-darwin-arm64`\n- `@soundscript/cli-darwin-x64`\n- `@soundscript/cli-linux-arm64`\n- `@soundscript/cli-linux-x64`\n- `@soundscript/cli-win32-x64`\n- `@soundscript/soundscript`\n- `soundscript`\n\nIf npm returns a `404` during `npm publish`, the usual cause is that the package's trusted-publisher\nsettings have not been added yet. The workflow also needs GitHub's `id-token: write` permission,\nwhich is already configured in the workflow file.\n\nYou can bulk-configure the package set from a shell after logging in to npm with an account that has\nwrite access to all seven packages:\n\n```bash\nfor package in \\\n  @soundscript/cli-darwin-arm64 \\\n  @soundscript/cli-darwin-x64 \\\n  @soundscript/cli-linux-arm64 \\\n  @soundscript/cli-linux-x64 \\\n  @soundscript/cli-win32-x64 \\\n  @soundscript/soundscript \\\n  soundscript\ndo\n  npm trust github \"$package\" \\\n    --repo soundscript-lang/soundscript \\\n    --file publish-release.yml \\\n    --yes\n  sleep 2\ndone\n```\n\nIf you need to reattach CLI archives to an existing release, use the separate `Backfill CLI Assets`\nworkflow.\n\n## What `.sts` means\n\n`.sts` files are checked in soundscript.\n\n`.ts` files are left alone.\n\nWhen `.sts` code imports ordinary TypeScript, JavaScript, or declaration-only packages, the import\nneeds `// #[interop]`:\n\n```ts\n// #[interop]\nimport { readConfig } from './legacy.ts';\n```\n\nFrom the other direction, `.ts` can import `.sts` without any annotation. It sees a projected public\nTypeScript surface for the `.sts` module.\n\nThat is the adoption model. Existing TypeScript stays where it is. New or critical code can move\ninto `.sts`.\n\n## Remaining rough edges\n\nsoundscript removes a large set of TypeScript unsoundness paths, but it still lives inside JS/TS\nruntime semantics. The main remaining rough edges are:\n\n- `null` vs `undefined`, especially at JSON, regex, and trusted-interop boundaries\n- arbitrary foreign throws and rejections; expansion-enabled source normalizes `catch (error)` and\n  built-in Promise rejection handlers to plain `Error`, but other boundaries still require explicit\n  normalization such as `sts:failures.normalizeThrown(...)`\n- stable v1 still defaults to ordinary JS `number` behavior, including `NaN`, `Infinity`, and `-0`;\n  the repo also contains experimental machine numerics work under `sts:numerics`, but that is\n  outside the stable v1 contract\n- stable v1 still relies heavily on structural typing for same-shape interface and object values;\n  class nominality plus `#[newtype]` and `#[value]` exist in the repo, but the broader nominal and\n  value-semantics story remains outside the stable v1 contract\n- there is no active effort to remove raw `null` from the language; it remains part of the honest\n  platform model\n\nThe release-facing contract for those boundaries is in\n[docs/reference/v1-user-contract.md](docs/reference/v1-user-contract.md).\n\n## Example\n\n```ts\n// src/math.sts\nexport function area(radius: number): number {\n  return Math.PI * radius * radius;\n}\n\nconst raw = JSON.parse('{\"radius\": 3}');\n\nif (\n  typeof raw === 'object' \u0026\u0026\n  raw !== null \u0026\u0026\n  'radius' in raw \u0026\u0026\n  typeof raw.radius === 'number'\n) {\n  console.log(area(raw.radius));\n}\n```\n\nThere is no new syntax here. The difference is the checker.\n\n## Commands\n\nThe main commands are:\n\n- `soundscript init`\n- `soundscript check`\n- `soundscript build`\n- `soundscript expand`\n- `soundscript deno`\n- `soundscript explain`\n- `soundscript lsp`\n\nThe repo also ships `soundscript compile`. `compile` and the broader compiler / Wasm surface remain\nexperimental; the checker is still the main entry point.\n\n## Editor support\n\nThe language server runs over stdio:\n\n```bash\nsoundscript lsp\n```\n\nThere is also a VS Code client in the separate editors repo:\n\n```bash\ngit clone https://github.com/soundscript-lang/editors.git ../editors\ncd ../editors/packages/vscode\nnpm install\nnpm run compile\n```\n\nThen:\n\n1. open the `editors` repo root in VS Code\n2. run the `Run soundscript extension` launch configuration\n3. in the spawned Extension Development Host, use `File -\u003e Open Folder...` to open the workspace you\n   want to test, for example `soundscript-example`\n4. open an `.sts` file to confirm the `soundscript` language mode and TextMate grammar are active\n\nNotes:\n\n- the VS Code extension and `@soundscript/tsserver-plugin` live in\n  [soundscript-lang/editors](https://github.com/soundscript-lang/editors)\n- work from `../editors/packages/vscode` when developing the extension locally\n- the extension prefers a workspace-installed `soundscript` binary and falls back to PATH unless you\n  override `soundscript.server.command`\n- `soundscript.server.*` settings only configure how the already-loaded extension launches the\n  language server; those settings do not make VS Code discover the extension\n- custom grammar-based syntax highlighting currently applies only to `.sts`; `.ts` and `.tsx` use\n  the built-in TypeScript grammar and only pick up LSP features from soundscript\n\nCurrent LSP support includes diagnostics, hover, signature help, definition, references, rename,\ncompletions, document symbols, formatting, semantic tokens, and code actions / quick fixes.\n\n## Repository layout\n\nThe repo also contains:\n\n- checker and CLI\n- `.ts` / `.sts` interop\n- LSP\n- macro work\n- compiler / Wasm work\n\nYou do not need macros or Wasm to use soundscript as a checker.\n\n## Development\n\nThe maintainer toolchain is Deno:\n\n```bash\ndeno task build\ndeno task check\ndeno task fmt\ndeno task lint\ndeno task test\ndeno task verify\n```\n\n## Docs\n\nStart here:\n\n- [docs/architecture/spec.md](docs/architecture/spec.md)\n- [docs/project/roadmap.md](docs/project/roadmap.md)\n- [docs/README.md](docs/README.md)\n- [docs/reference/v1-user-contract.md](docs/reference/v1-user-contract.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoundscript-lang%2Fsoundscript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoundscript-lang%2Fsoundscript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoundscript-lang%2Fsoundscript/lists"}