Where Is the Source Code Located in Automattic/Harper? A Complete Directory Guide

The source code in Automattic/harper is organized as a multi-package monorepo with core components located in top-level directories like harper-core/, harper-ls/, and harper-desktop/, while integrations reside in packages/ subdirectories.

Harper is a Rust-based grammar engine designed to catch errors in English prose. Understanding where the source code is located helps contributors navigate the codebase and integrate the linter into their own tools.

Monorepo Structure Overview

The repository follows a flat monorepo layout. All executable code lives in top-level directories directly under the root, with no nested src/ folders at the repository level. The project separates its high-performance Rust core from language bindings and editor-specific plugins.

The directory structure splits into two categories:

• Core infrastructure: Top-level crates like harper-core/, harper-ls/, and harper-desktop/
• Integration packages: Editor plugins and JavaScript bindings located under packages/

Core Components

Grammar Engine (harper-core/)

The heart of the system resides in harper-core/. This directory contains the actual linting logic, dictionary files, and curated rule configurations.

Key locations within this directory:

• src/ – Rust source files implementing the linting algorithms
• default_config.json – Rule configuration defaults
• dictionary.dict – Built-in word list

The primary entry point is harper-core/src/lib.rs, which exposes the Linter struct and Config types that power every other component in the ecosystem.

Language Server (harper-ls/)

The LSP implementation lives in harper-ls/, providing IDE integration via the Language Server Protocol. This crate wraps the core engine in a JSON-RPC interface.

The executable entry point is harper-ls/src/main.rs, which initializes the server and handles protocol messages. This binary powers the VS Code extension and any other LSP-compatible editor.

Desktop Client (harper-desktop/)

The cross-platform desktop application uses Tauri (Rust backend) and SvelteKit (frontend). Source code is split between:

• src-tauri/src/ – Rust backend code, with harper-desktop/src-tauri/src/main.rs as the entry point
• src/ – TypeScript/JavaScript frontend assets
• package.json – Node.js dependencies for the UI layer

Package Integrations (packages/)

JavaScript SDK (packages/harper.js/)

Web and Node.js consumers use this WebAssembly-powered wrapper. The main interface is defined in packages/harper.js/src/index.ts, which exposes a Harp class that bridges JavaScript calls to the underlying Rust core.

VS Code Extension (packages/vscode-plugin/)

The Visual Studio Code integration activates through packages/vscode-plugin/src/extension.ts. This file registers a language client that communicates with the harper-ls binary, requiring no direct interaction with the core library.

Browser Extensions

Chrome and Firefox support resides in packages/chrome-plugin/, containing:

• src/ – Extension background scripts and content scripts
• manifest.json – Browser extension metadata

Obsidian Plugin (packages/obsidian-plugin/)

The Obsidian.md integration follows the standard Obsidian plugin structure with src/ containing the plugin logic and manifest.json defining the plugin metadata.

WordPress Plugin (packages/wordpress-plugin/)

WordPress support lives in packages/wordpress-plugin/, structured as a standard PHP WordPress plugin with additional build assets in src/.

Utility and Support Crates

Beyond the main components, several specialized crates handle edge cases:

• harper-cli/ – Command-line interface for linting files directly from the terminal
• harper-comments/ – Support for linting code comments in various programming languages
• harper-asciidoc/ – AsciiDoc document format support
• harper-jjdescription/ – Jujutsu version control description linting
• harper-literate-haskell/ – Literate Haskell file processing
• harper-brill/ – Additional linguistic utilities

Each of these contains a Cargo.toml and src/ directory following standard Rust crate conventions.

Key Entry Points and Usage Examples

When navigating the source code location in Automattic/harper, start with these specific files:

• Core library: harper-core/src/lib.rs exposes Linter::new() and Config::new_curated()
• LSP server: harper-ls/src/main.rs starts the language server process
• JavaScript bridge: packages/harper.js/src/index.ts exports the Harp class
• Desktop app: harper-desktop/src-tauri/src/main.rs initializes the Tauri application
• VS Code: packages/vscode-plugin/src/extension.ts handles extension activation

Using the Core Engine

use harper_core::{Linter, Config};

let config = Config::new_curated();
let linter = Linter::new(&config);
let results = linter.lint("This is an example sentence.");
println!("{:?}", results);

Running the CLI

# Lint a text file

harper-cli lint path/to/file.txt

# Show the current configuration

harper-cli config show

Calling the JavaScript SDK

import { Harp } from "harper.js";

const harper = new Harp();
const { lints } = await harper.lint("This sentence contains a error.");
console.log(lints);

Summary

• Core engine: Located in harper-core/src/ with the main library entry at harper-core/src/lib.rs
• Language server: Found in harper-ls/src/main.rs
• Desktop application: Split between harper-desktop/src-tauri/src/ (Rust) and harper-desktop/src/ (TypeScript)
• JavaScript/WebAssembly bindings: Located in packages/harper.js/src/index.ts
• Editor plugins: Each resides in packages/<plugin-name>/ with src/ directories containing platform-specific code
• Support utilities: Additional crates like harper-cli/, harper-comments/, and harper-asciidoc/ provide specialized functionality

Frequently Asked Questions

Where is the main Rust library code located in the Harper repository?

The main Rust library code is located in the harper-core/ directory at the repository root. The public API exports from harper-core/src/lib.rs, which contains the Linter struct and Config types. All other Rust crates in the monorepo depend on this core library.

What is the difference between top-level directories and the packages/ folder?

Top-level directories like harper-core/ and harper-ls/ contain Rust crates compiled with Cargo, while packages/ contains JavaScript/TypeScript projects including editor plugins and the WebAssembly JavaScript SDK. The packages/ directory organizes integrations that consume the Rust core through either the Language Server Protocol or WebAssembly bindings.

Where does the VS Code extension source code live?

The VS Code extension source code lives in packages/vscode-plugin/. The activation logic is in packages/vscode-plugin/src/extension.ts, which spawns the harper-ls binary built from the harper-ls/ crate. The extension itself contains minimal linting logic, delegating all grammar checking to the language server.

How do I find the executable entry points for the Harper tools?

Executable entry points vary by component:

• CLI tool: harper-cli/src/main.rs
• Language Server: harper-ls/src/main.rs
• Desktop app: harper-desktop/src-tauri/src/main.rs
• JavaScript library: packages/harper.js/src/index.ts (which loads the WebAssembly module)

Each entry point is named main.rs for Rust executables or index.ts for JavaScript libraries, following standard conventions for their respective ecosystems.

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