Main Directories in Automattic/harper: A Complete Monorepo Breakdown

The Automattic/harper repository is a Rust-based monorepo organized into specialized top-level directories including the core grammar engine, WebAssembly bindings, Language Server Protocol implementation, editor plugins, and a Tauri desktop application.

Harper is a grammar and spell checker built by Automattic that targets both prose and source code comments. The project uses a monorepo structure where each top-level directory represents an independent crate or package, ranging from the core Rust engine to platform-specific integrations.

Core Grammar Engine and WebAssembly

harper-core

The harper-core directory contains the foundational grammar-checking engine that powers all other Harper products. This crate implements the rule engine, tokenizers, and default configuration files. The public API surface is exposed in harper-core/src/lib.rs, which defines the primary linting interface used by downstream consumers.

harper-wasm

To enable browser-based usage, harper-wasm compiles the core engine to WebAssembly. This directory houses the Rust code that exposes core functionality to JavaScript environments. The entry point at harper-wasm/src/lib.rs handles the WASM bindings, allowing the engine to run in web pages and Node.js applications through the harper.js package.

Editor Integration and LSP Support

harper-ls

The harper-ls directory implements the Language Server Protocol (LSP) used by editors such as VS Code, Neovim, Helix, and Zed. The server binary entry point is located at harper-ls/src/main.rs. This component communicates with editors via JSON-RPC to provide real-time diagnostics and code actions without requiring external processes.

harper-comments

Before linting source code, Harper extracts natural language from comments. The harper-comments directory contains parsers that handle this extraction across multiple programming languages. The central logic resides in harper-comments/src/lib.rs, which identifies comment boundaries and strips syntax markers so the core engine can analyze the text.

Natural Language Processing Utilities

harper-pos-utils

Part-of-speech tagging utilities live in harper-pos-utils, including a Brill-style tagger and supporting dictionaries. The utility functions are defined in harper-pos-utils/src/lib.rs.

harper-brill

The harper-brill directory specifically houses the trained models and runtime for the Brill tagging algorithm used by the POS utilities.

harper-thesaurus

For synonym suggestions and lexical enrichment, harper-thesaurus maintains a simple thesaurus database used by the suggestion engine.

Specialized Domain Linters

harper-ink

The harper-ink directory contains a specialized linter for Ink story files, which are used for interactive fiction and narrative scripting.

harper-jjdescription

Version control integration includes harper-jjdescription, which parses and validates "JJ" commit descriptions following the project's commit style guidelines.

harper-git-commit

The harper-git-commit directory provides a linter for conventional Git commit messages, ensuring formatting standards are met before changes are committed.

harper-tree-sitter

Fast parsing of source files relies on Tree-sitter grammars housed in harper-tree-sitter. This directory enables the linter to parse code structure efficiently across supported languages.

First-Party Integrations and Applications

packages

The packages directory is a collection of first-party integrations and UI components:

• chrome-plugin – Browser extension for Chrome and Firefox
• vscode-plugin – Visual Studio Code extension packaging
• obsidian-plugin – Integration for the Obsidian note-taking app
• wordpress-plugin – WordPress CMS integration
• harper.js – JavaScript/TypeScript wrapper exported from harper-wasm
• harper-editor – Shared Svelte components used by the website and desktop application
• web – Public documentation site and demo application source

The JavaScript wrapper entry point is located at packages/harper.js/src/index.ts, while the documentation landing page resides at packages/web/src/routes/docs/about/+page.md.

harper-desktop

For offline usage, harper-desktop contains a Tauri-based desktop application providing an offline editor, system tray UI, and overlay highlighter. The Tauri backend entry point is harper-desktop/src-tauri/src/main.rs.

Testing and Infrastructure

fuzz

The fuzz directory contains fuzzing harnesses used to stress-test the core engine for crashes and undefined behavior.

harper-stats

Data collection utilities for internal analytics live in harper-stats, which records lint-run statistics across various deployment targets.

Configuration Files

Top-level configuration files like docker-compose.yml support local development by orchestrating the full stack, while Cargo.toml and pnpm-workspace.yaml define the Rust and JavaScript workspace boundaries.

Key Entry Points

When navigating the Harper source code, these files serve as the primary interfaces:

• harper-core/src/lib.rs – Public API of the core engine
• harper-wasm/src/lib.rs – JavaScript exposure via WASM
• harper-ls/src/main.rs – LSP server startup
• harper-comments/src/lib.rs – Comment extraction logic
• packages/harper.js/src/index.ts – JavaScript wrapper
• harper-desktop/src-tauri/src/main.rs – Desktop binary entry
• justfile – Central task runner for builds

Building and Testing Components

Developers interact with specific directories using standard Rust tooling:

# Build the core engine

cargo build -p harper-core

# Compile WebAssembly for browser usage

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

# Run the Language Server locally

cd harper-ls && cargo run --release

# Test comment extraction

cargo test -p harper-comments --lib

# Launch desktop app (requires Tauri CLI)

cd harper-desktop && just dev-desktop

Summary

• harper-core provides the foundational grammar engine at harper-core/src/lib.rs
• harper-wasm enables browser execution through WebAssembly bindings
• harper-ls implements the Language Server Protocol for editor integration
• harper-comments extracts translatable text from source code comments
• packages contains first-party integrations including VS Code, Chrome, Obsidian, and WordPress plugins
• harper-desktop delivers a Tauri-based offline application
• fuzz and harper-stats support quality assurance and analytics

Frequently Asked Questions

What is the purpose of the harper-core directory?

The harper-core directory houses the Rust-based grammar-checking engine that tokenizes input and applies linting rules. It serves as the foundation for all other Harper products, with its public API defined in harper-core/src/lib.rs.

How does harper-ls differ from the packages in the packages directory?

The harper-ls directory implements the Language Server Protocol server that provides diagnostics to any LSP-compatible editor, while the packages directory contains specific UI implementations and wrappers like the VS Code extension (packages/vscode-plugin) and JavaScript library (packages/harper.js).

Where is the WebAssembly compilation logic located?

WebAssembly bindings are defined in harper-wasm/src/lib.rs within the harper-wasm directory. This crate compiles the core engine to WASM so it can be consumed by the harper.js package and web-based interfaces.

Which directory should I modify to add support for a new programming language's comments?

To add support for extracting comments from a new programming language, modify the harper-comments directory, specifically the parsers in harper-comments/src/lib.rs that identify comment syntax across different file types.

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