diff --git a/editors/vscode/README.md b/editors/vscode/README.md index a0929ec..25300ed 100644 --- a/editors/vscode/README.md +++ b/editors/vscode/README.md @@ -1,29 +1,256 @@ -# Codebook VS Code Extension (Unreleased) +
+ +

Codebook Spell Checker

+

A fast, code-aware spell checker — built for code, not prose.

-**Note** This extension is a work in progress and is not released on the VS Code marketplace yet. However, it is functional. Follow the Development instructions to install if you'd like to provide feedback! + [![Version](https://img.shields.io/visual-studio-marketplace/v/blopker.codebook-vscode?color=blue&label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=blopker.codebook-vscode) + [![Installs](https://img.shields.io/visual-studio-marketplace/i/blopker.codebook-vscode)](https://marketplace.visualstudio.com/items?itemName=blopker.codebook-vscode) + [![Rating](https://img.shields.io/visual-studio-marketplace/r/blopker.codebook-vscode)](https://marketplace.visualstudio.com/items?itemName=blopker.codebook-vscode) + [![License](https://img.shields.io/github/license/blopker/codebook)](LICENSE) -This extension wires the Codebook language server into VS Code so code-specific -spell check diagnostics and quick fixes appear automatically. +
+ Report a Bug · + Request a Feature · + Why Codebook? +
+ +--- + +## Table of Contents + +- [Features](#features) +- [Requirements](#requirements) +- [Installation](#installation) +- [Usage](#usage) +- [Extension Settings](#extension-settings) +- [Configuration File](#configuration-file) +- [Supported Languages](#supported-languages) +- [Contributing](#contributing) + +--- ## Features -- Automatically launches `codebook-lsp` for supported languages. -- Downloads, caches, and updates the Codebook language server without requiring any manual installation. -- Supports custom binary locations and optional pre-release builds via - `codebook.*` settings. +![Codebook in action](https://github.com/blopker/codebook/blob/main/assets/example.png?raw=true) + +Codebook combines [Tree Sitter](https://tree-sitter.github.io) and [Spellbook](https://github.com/helix-editor/spellbook) into a Language Server written in Rust. It's designed to be fast and light on memory. If you need a traditional spell checker for prose, Codebook is probably not the right fit: it handles capitalization loosely by design and does not do grammar checking. + +**Code-aware checking** - Codebook only looks at the parts of your code where spelling actually matters: variable and function definitions, comments, string literals, and documentation. It knows how to split camelCase and snake_case, and suggests fixes in the same casing style. + +**Zero configuration** - install it and it works. No dictionaries to configure, no files to create. + +**Definitions only, not usages** - if a typo comes from an imported function name, Codebook won't flag it since you can't change it anyway. It only marks words at the point where you defined them, so every warning is something you can actually fix. + +**Private and offline** - everything runs locally. No file contents are ever sent anywhere. Once the dictionaries are downloaded, Codebook works without an internet connection. -## Development +**Hierarchical config** - set global defaults and override them per project. Works across workspaces. + +--- + +## Requirements + +- **VS Code** `1.80.0` or later +- **OS:** macOS (x86_64, aarch64), Linux (x86_64, aarch64), Windows (x86_64, arm64) +- No other dependencies. The `codebook-lsp` binary is downloaded and managed automatically on first activation. + +--- + +## Installation + +Install **Codebook Spell Checker** from the VS Code Marketplace: + +1. Open VS Code. +2. Open the Extensions panel (`Ctrl+Shift+X` / `Cmd+Shift+X`). +3. Search for **`Codebook Spell Checker`**. +4. Click **Install**. + +Or install from the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`): ``` -cd editors/vscode -bun install # or npm install / pnpm install -bun run build # or npm run build -bun run package # builds dist/ and emits a .vsix via vsce +ext install blopker.codebook-vscode ``` -The emitted JavaScript lives in `dist/` and can be loaded into VS Code via the -`Extension Tests / Run Extension` launch configuration or by using the bundled -`vsce` CLI via `bun run package`. +On first activation, Codebook downloads the `codebook-lsp` binary in the background. An internet connection is needed for this one-time step. + +--- + +## Usage + +Codebook activates automatically for all [supported languages](#supported-languages). No setup needed. + +Spelling errors are highlighted with red squiggles in: +- Variable and function names (at the point of definition) +- Comments and documentation +- String literals + +To fix an error, right-click on the highlighted word: + +| Action | Description | +|--------|-------------| +| **Add to project dictionary** | Saves the word to your project's `codebook.toml` | +| **Add to global dictionary** | Saves the word to your global Codebook config | +| **Ignore** | Dismisses the warning for this session | + +> Codebook only flags words at their *definition*. Use your language's rename/refactor tool to update all usages at once. + +--- + +## Extension Settings + +Settings can be configured in the Settings UI (`Ctrl+,`) or in `settings.json`. + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `codebook.binaryPath` | `string` | `""` | Path to a custom `codebook-lsp` binary. Leave empty to use the auto-managed one. | +| `codebook.enablePrerelease` | `boolean` | `false` | Use pre-release versions of `codebook-lsp`. | +| `codebook.logLevel` | `string` | `"info"` | Log verbosity: `debug`, `info`, `warn`, or `error`. | + +**Example `settings.json`:** + +```jsonc +{ + "codebook.binaryPath": "/usr/local/bin/codebook-lsp", + "codebook.enablePrerelease": false, + "codebook.logLevel": "info" +} +``` + +--- + +## Configuration File + +Codebook supports per-project and global configuration via TOML files. + +### File locations + +| Scope | Path | +|-------|------| +| **Project** | `codebook.toml` or `.codebook.toml` in the project root | +| **Global (Linux/macOS)** | `~/.config/codebook/codebook.toml` | +| **Global (Windows)** | `%APPDATA%\codebook\codebook.toml` | + +Project settings override global ones. Codebook searches up the directory tree to find the nearest project config. + +> **Tip:** If you create or rename a config file manually, reload the window (`Ctrl+Shift+P` > "Developer: Reload Window") to pick up the change. + +### All options + +```toml +# Dictionaries to use. Default: ["en_us"] +# Available: en_us, en_gb, de, de_at, de_ch, nl_nl, es, fr, it, +# pt_br, ru, sv, da, lv, vi_vn, pl, uk +dictionaries = ["en_us", "en_gb"] + +# Words to always allow (case-insensitive). Codebook adds words here +# when you select "Add to project dictionary". +words = ["codebook", "rustc"] + +# Words that should always be flagged as incorrect. +flag_words = ["todo", "fixme"] + +# Only spell-check files matching these glob patterns (allowlist). +# Default: [] (check everything) +include_paths = ["src/**/*.rs", "lib/**/*.rs"] + +# Skip files matching these glob patterns (blocklist). +# Takes precedence over include_paths. +ignore_paths = ["target/**/*", "**/*.json", ".git/**/*"] + +# Regex patterns — tokens within matches are skipped. +# Use single quotes to avoid backslash escaping. +ignore_patterns = [ + '\b[ATCG]+\b', # DNA sequences + '\d{3}-\d{2}-\d{4}', # Social Security Numbers +] + +# Minimum word length to check. Default: 3 +min_word_length = 3 + +# Set to false to ignore the global config for this project. +# Default: true +use_global = true +``` + +### Precedence + +1. Project config overrides global config +2. If `use_global = false`, the global config is ignored entirely for that project +3. If no project config exists, the global config applies +4. If neither exists, defaults are used + +### How words are saved + +- **Add to dictionary** saves to the project config +- **Add to global dictionary** saves to the global config +- Changes are written automatically and reloaded without a restart + +### User-defined regex patterns + +Use `ignore_patterns` to skip tokens that match a custom regex. Some things to know: + +**Built-in patterns** - these are already ignored by default: + +| Pattern | Matches | +|---------|---------| +| `https?://[^\s]+` | URLs | +| `#[0-9a-fA-F]{3,8}` | Hex colors (`#deadbeef`, `#fff`) | +| `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` | Email addresses | +| `/[^\s]*` and `[A-Za-z]:\\[^\s]*` | Unix and Windows file paths | +| `[0-9a-fA-F]{8}-...-[0-9a-fA-F]{12}` | UUIDs | +| `[A-Za-z0-9+/]{20,}={0,2}` | Base64 strings (20+ chars) | +| `\b[0-9a-fA-F]{7,40}\b` | Git commit hashes | +| `\[([^\]]+)\]\(([^)]+)\)` | Markdown link targets | + +**How matching works:** + +- Patterns run against the full source text; any token inside a match is skipped +- Multiline mode is on: `^` and `$` match line boundaries +- Use single-quoted TOML strings to avoid double-escaping backslashes + +```toml +ignore_patterns = [ + '\b[ATCG]+\b', # DNA sequences + '^vim\..*', # Lines starting with vim. + '^\s*//.*', # Full-line // comments +] +``` + +--- + +## Supported Languages + +> For the most up-to-date status, see the [main repository](https://github.com/blopker/codebook). + +| Language | Status | | Language | Status | +|----------|--------|-|----------|--------| +| C | ✅ Stable | | Markdown | ✅ Stable | +| C# | ⚠️ Needs testing | | Odin | ✅ Stable | +| C++ | ⚠️ Needs testing | | PHP | ⚠️ Needs testing | +| CSS | ⚠️ Needs testing | | Plain Text | ✅ Stable | +| Elixir | ⚠️ Needs testing | | Python | ✅ Stable | +| Erlang | ⚠️ Needs testing | | Ruby | ✅ Stable | +| Go | ✅ Stable | | Rust | ✅ Stable | +| Haskell | ⚠️ Needs testing | | Swift | ⚠️ Needs testing | +| HTML | ⚠️ Needs testing | | TOML | ✅ Stable | +| Java | ✅ Stable | | TypeScript | ✅ Stable | +| JavaScript | ✅ Stable | | Typst | ⚠️ Needs testing | +| LaTeX | ⚠️ Needs testing | | VHDL | ⚠️ Needs testing | +| Lua | ✅ Stable | | YAML | ⚠️ Needs testing | +| | | | Zig | ✅ Stable | + +**✅ Stable** - fully tested. +**⚠️ Needs testing** - works in basic cases, but needs real-world validation. If you use one of these, [open an issue](https://github.com/blopker/codebook/issues) to share what you find. + +--- + +## Contributing + +Contributions are welcome. To get started: + +1. Fork the repository on GitHub. +2. Clone your fork: `git clone https://github.com/YOUR_USER/codebook` +3. Install dependencies: `npm install` (extension) and `cargo build` (LSP server) +4. Open the project in VS Code and press `F5` to launch the Extension Development Host. +5. Submit a pull request with a description of your change. -Set `codebook.logLevel` to `debug` to see verbose logs from the language server -inside the `Codebook` output channel. +If you use a language marked ⚠️, the most useful thing you can do is test it and report what you find. diff --git a/editors/vscode/assets/codebook.png b/editors/vscode/assets/codebook.png new file mode 100644 index 0000000..bc91502 Binary files /dev/null and b/editors/vscode/assets/codebook.png differ diff --git a/editors/vscode/package.json b/editors/vscode/package.json index f975f9d..1d20ad7 100644 --- a/editors/vscode/package.json +++ b/editors/vscode/package.json @@ -2,8 +2,9 @@ "name": "codebook-vscode", "displayName": "Codebook Spell Checker", "description": "A fast, code-aware spell checker.", - "version": "0.0.1", + "icon": "assets/codebook.png", "publisher": "blopker", + "version": "0.0.1", "license": "MIT", "repository": { "type": "git", @@ -20,33 +21,17 @@ "Linters", "Other" ], + "keywords": [ + "spell", + "checker", + "spelling", + "spellchecker" + ], "extensionKind": [ "workspace" ], "activationEvents": [ - "onLanguage:c", - "onLanguage:cpp", - "onLanguage:css", - "onLanguage:elixir", - "onLanguage:go", - "onLanguage:html", - "onLanguage:haskell", - "onLanguage:java", - "onLanguage:javascript", - "onLanguage:latex", - "onLanguage:lua", - "onLanguage:markdown", - "onLanguage:php", - "onLanguage:plaintext", - "onLanguage:python", - "onLanguage:ruby", - "onLanguage:rust", - "onLanguage:toml", - "onLanguage:typescript", - "onLanguage:typst", - "onLanguage:yaml", - "onLanguage:zig", - "onLanguage:csharp" + "onStartupFinished" ], "main": "./dist/extension.js", "scripts": {