外部流出なしで使えるオフライン文法チェッカー Harper の構築方法
TuBrief 편집팀
2026년 7월 25일
0
Computing/Software원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
커뮤니티의 다른 글
댓글 (0)
Log in to leave a comment
아직 작성된 글이 없습니다
원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
Log in to leave a comment
아직 작성된 글이 없습니다
社内のセキュリティ方針によって Grammarly などの外部 AI ツールが制限されていると、開発者は頭を悩ませることになります。技術ドキュメントやコードコメントに誤字を残したままリリースすると信頼性が低下しますが、かといって目視で一つひとつチェックするには時間がもったいなさすぎます。
Harper はこの問題をスマートに解決します。Rust で開発されたオフライン専用の文法チェックエンジンであるため、外部サーバーとの通信を完全に遮断します。Java ベースで動作し、メモリを数百メガバイト単位で消費していた LanguageTool とは異なり、メモリ使用量は十数メガバイト程度にすぎません。10ms 未満の応答速度で動作するため、エディタが重くなる心配もありません。
harper-ls は端末内部でローカルの CPU リソースのみを使用して構文解析を行います。OS に合ったパッケージマネージャーでバイナリをインストールし、エディタに標準 LSP として登録するだけで設定完了です。
ターミナルでコマンドを実行してバイナリをインストールします。
brew install harpercargo install harper-ls --lockedscoop install harperNeovim では nvim-lspconfig を使用して対象ファイルタイプとリンターのルールを設定します。
`lua
local lspconfig = require('lspconfig')
lspconfig.harper_ls.setup({
filetypes = { 'markdown', 'gitcommit', 'rust', 'go', 'typescript', 'python' },
settings = {
["harper-ls"] = {
userDictPath = "~/config/harper/user_dict.txt",
workspaceDictPath = ".harper-dictionary.txt",
linters = {
SpellCheck = true,
SpelledNumbers = false,
AnA = true,
SentenceCapitalization = false,
UnclosedQuotes = true,
WrongApostrophe = false,
LongSentences = true,
RepeatedWords = true,
Spaces = true,
CorrectNumberSuffix = true
}
}
}
})
`
Neovim 0.11 以降のネイティブ LSP API を使う場合は、vim.lsp.config['harper'] を構成して vim.lsp.enable('harper') を呼び出します。VS Code ユーザーは elijah-potter.harper 拡張機能をインストールした後、.vscode/settings.json に "harper.path": "/usr/local/bin/harper-ls" のパスを指定すれば完了です。
Harper は Tree-sitter AST パーサーを内蔵しているため、実際のソースコードはスキップし、コメントブロック内の英文テキストのみを抽出してチェックします。特定の関数コメントをチェック対象から完全に除外したい場合は、インライン指示子を挿入します。
`javascript
// harper:ignore
function processInternalSecurityToken() {
// spellcheck:ignore
// 内部セキュリティトークンロジック
}
`
デフォルトの英単語辞書だけで実行すると、gRPC、OAuth2、Prometheus などの技術用語がすべてエラーと判定されてしまいます。階層型の辞書構造を活用することで、警告ノイズをすばやく除去できます。
Harper は 4 つの階層で単語を検証します。
| 辞書階層 | 保存場所 | 目的 |
|---|---|---|
| Static Dictionary | harper-ls バイナリ内蔵 |
修正不可の基本英単語 DB |
| User Dictionary | ~/.config/harper-ls/dictionary.txt |
個人開発環境用のグローバル辞書 |
| Workspace Dictionary | プロジェクトルートの .harper-dictionary.txt |
プロジェクト専用用語辞書（Git 管理） |
| File-Local Dictionary | OS データパス内に保存 | 単一ファイル専用の識別子保存 |
.harper-dictionary.txt ファイルを作成します。`text
Kubernetes
gRPC
OAuth2
OpenTelemetry
Prometheus
mTLS
Netty
Etcd
`
Ctrl + .、Neovim: Code Action キーバインド）を押して、対象の単語を .harper-dictionary.txt にその場で追加できます。このファイルさえ Git リポジトリにコミットしておけば、チームメンバー全員で同じ単語リストを共有できます。
コメント作成時に煩わしいルールはオフにします。
SentenceCapitalization: コメントの先頭文字の大文字強制ルールを無効にするには false に設定します。LongSentences: 技術ドキュメントの特性上長くなりやすい文章の警告を無効にするには false に設定します。SpellCheck および UnclosedQuotes: スペルミスと引用符の閉じ忘れチェックは true のままにしておきます。開発者がエディタで見落とした誤字は、PR 段階でブロックする必要があります。CLI ツールである harper-cli をパイプラインに組み込めば、メインブランチへのマージ前に文法エラーを自動で検出できます。
.github/workflows/harper-lint.yml ファイルに、変更された Markdown ファイルのみを抽出してチェックするジョブを定義します。
`yaml
name: Technical Documentation Linting
on:
pull_request:
paths:
- 'docs/'
- '.md'
jobs:
harper-grammar-check:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust Toolchain
uses: dtolnay/rust-toolchain@stable
- name: Cache Harper CLI Binary
uses: actions/cache@v3
with:
path: ~/.cargo/bin/harper-cli
key: ${{ runner.os }}-harper-cli-${{ hashFiles('**/Cargo.lock') }}
- name: Install Harper CLI
run: |
if ! command -v harper-cli &> /dev/null; then
cargo install harper-cli --locked
fi
- name: Get Changed Markdown Files
id: changed-files
run: |
git fetch origin ${{ github.base_ref }}
FILES=$(git diff --name-only --diff-filter=AM origin/${{ github.base_ref }} HEAD | grep '\.md$' || true)
echo "files=$FILES" >> $GITHUB_OUTPUT
- name: Run Harper Lint Check
if: steps.changed-files.outputs.files != ''
run: |
ERRORS=0
for file in ${{ steps.changed-files.outputs.files }}; do
echo "Linting $file with Harper..."
harper-cli lint "$file" || ERRORS=$((ERRORS+1))
done
if [ $ERRORS -gt 0 ]; then
echo "Harper validation failed with $ERRORS error(s)."
exit 1
fi
`
プロジェクトルートの .harper-dictionary.txt も一緒にコミットしておけば、CI ランナーもエディタと同じ単語リストを基準にチェックを適用できます。MkDocs や Docusaurus などの静的サイトジェネレーター（SSG）を使用している場合は、ビルドスクリプトの実行直前に harper-cli lint docs/ コマンドが実行されるよう設定しておくと安全です。