Main Directories in the Automattic Harper Repository: Complete Monorepo Guide

The Automattic Harper repository organizes its grammar-checking ecosystem as a Rust-based monorepo with over a dozen top-level directories separating the core engine, WebAssembly bindings, language server, IDE integrations, and desktop application.

The Harper repository groups independent components into distinct crates and packages, making it possible to use the grammar engine in browsers, editors, and command-line tools. Understanding the main directories in the Automattic Harper repository helps contributors navigate the separation between the rule engine in harper-core, the WebAssembly bridge in harper-wasm, and the various editor plugins housed under packages/.

Core Grammar Engine

harper-core

The foundation of the entire project, harper-core contains the rule engine, tokenizers, and default configuration files that power all Harper products. The public API is exposed in harper-core/src/lib.rs, which defines the primary interfaces for linting text and applying grammar rules.

harper-wasm

This directory compiles the core engine to WebAssembly, enabling browser-based usage through JavaScript environments. The WASM bindings are implemented in harper-wasm/src/lib.rs, exposing the Rust engine to web applications like the harper.js package.

harper-ls

Implements the Language Server Protocol (LSP) used by VS Code, Neovim, Helix, and Zed. The server entry point is located at harper-ls/src/main.rs, which initializes the LSP runtime and connects the core engine to editor clients.

Parsing and Linguistic Utilities

harper-comments

Contains parsers that extract comments from source code in many programming languages, allowing the linter to check documentation and inline comments. The central extraction logic resides in harper-comments/src/lib.rs.

harper-tree-sitter

Houses Tree-sitter grammars that enable fast, incremental parsing of source files. These grammars provide the syntactic structure needed by harper-comments to locate comment boundaries accurately.

harper-pos-utils

Utilities for part-of-speech tagging, including a Brill-style tagger and supporting dictionaries. The POS-tagging API is defined in harper-pos-utils/src/lib.rs.

harper-brill

Contains trained models and runtime infrastructure for the Brill tagger used by the POS utilities. This directory separates the machine learning artifacts from the tagging logic itself.

Specialized Linting Tools

harper-ink

A domain-specific linter for Ink story files used in interactive fiction and narrative games.

harper-jjdescription

Parses and validates "JJ" commit descriptions according to the project's internal commit style guidelines.

harper-git-commit

Linter for conventional Git commit messages, ensuring standardized formatting in version control history.

harper-thesaurus

A lightweight thesaurus implementation providing synonym suggestions and lexical enrichment for suggestions.

harper-stats

Data-collection utilities that record lint-run statistics for internal analytics and performance monitoring.

User Interfaces and Integrations

packages

A collection of first-party integrations and UI packages organized into subdirectories:

• chrome-plugin – Browser extension for Chrome and Firefox
• vscode-plugin – Visual Studio Code extension wrapper
• obsidian-plugin – Integration for the Obsidian knowledge base
• wordpress-plugin – WordPress editor integration
• harper.js – JavaScript wrapper consuming the WASM engine (entry point at packages/harper.js/src/index.ts)
• harper-editor – Shared Svelte components used by the website and desktop application
• web – Public documentation site and demo application (source at packages/web/src/routes/docs/about/+page.md)

harper-desktop

The Tauri-based desktop application providing an offline editor, system tray UI, and overlay highlighter. The binary entry point is located at harper-desktop/src-tauri/src/main.rs.

Development and Testing Infrastructure

fuzz

Contains fuzzing harnesses used to stress-test the core engine and uncover edge cases in the grammar rules.

docker-compose.yml

Configuration files for Docker-based development, enabling contributors to run the full stack locally without installing Rust toolchains or Node.js dependencies.

Building Components from Source

Navigate to specific directories to build or test individual components:

# Build the core Rust engine

cargo build -p harper-core

# Compile the WebAssembly bundle for browser usage

cd harper-wasm && wasm-pack build --release

# Run the LSP server locally for editor integration

cd harper-ls && cargo run --release

# Test comment extraction on sample files

cargo test -p harper-comments --lib

# Launch the Tauri desktop application

cd harper-desktop && just dev-desktop

The justfile in the repository root provides convenient shortcuts for common tasks like just test and just format, orchestrating builds across the monorepo's multiple crates.

Summary

• harper-core contains the essential grammar engine and rule system at harper-core/src/lib.rs
• harper-wasm and harper-ls provide WebAssembly and LSP bindings for web and editor integration
• harper-comments and harper-tree-sitter handle source code parsing and comment extraction
• packages/ houses all user-facing integrations including VS Code, Obsidian, and the harper.js wrapper
• harper-desktop delivers a standalone Tauri application for offline usage
• Supporting directories like harper-pos-utils, harper-brill, and harper-stats provide linguistic analysis and analytics capabilities

Frequently Asked Questions

What is the purpose of the harper-core directory?

The harper-core directory contains the fundamental grammar-checking engine, including the rule engine, tokenizers, and default configuration files. All other packages in the monorepo depend on this crate, which exposes its public API through harper-core/src/lib.rs.

How does harper-wasm relate to the JavaScript packages?

The harper-wasm directory compiles the Rust core engine into WebAssembly, creating the binary module consumed by packages/harper.js. This allows the JavaScript wrapper to instantiate the grammar checker in browsers and Node.js environments without requiring a native Rust toolchain on the user's machine.

Which directory contains the VS Code extension?

The VS Code extension source code resides in packages/vscode-plugin/, while the underlying Language Server Protocol implementation it communicates with is located in harper-ls/. The extension wraps the LSP binary and provides UI components specific to the VS Code ecosystem.

What is the difference between harper-comments and harper-tree-sitter?

harper-tree-sitter contains Tree-sitter grammars for parsing source code syntax, while harper-comments uses those grammars to extract comment text from specific locations in the parse tree. The tree-sitter crate provides the parsing infrastructure, and the comments crate implements the logic for identifying and extracting comment content across multiple programming languages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}