Automattic/harper 딥다이브
— Grammarly가 서버로 빼가던 당신의 문장을, Rust가 10밀리초 만에 내 컴퓨터에서 고친다

1프로젝트 한 줄 요약

글을 쓰는 도구에 문법 검사기를 붙이는 건 이제 당연한 일이 됐다. 문제는 그 대부분이 당신이 입력하는 모든 문장을 클라우드로 전송한다는 점이다. 이메일 초안, 일기, 회사 기밀 문서까지 — 검사받는 순간 남의 서버를 거친다. harper의 원저자 Elijah Potter는 이걸 "프라이버시 악몽(privacy nightmare)"이라 불렀고, 그 반대편에 서는 도구를 만들었다.

harper가 하는 일은 단순하다. 텍스트를 받아 → 토큰(단어·기호 조각)으로 쪼개고 → 품사를 붙이고 → 284개의 문법·철자·문체 규칙을 적용해 → 오류 위치와 수정 제안을 내놓는다. 이 코어 엔진(harper-core)을 세 가지 얼굴로 재사용한다: 에디터에 붙는 LSP 서버(harper-ls), 브라우저에서 도는 WASM(harper-wasm), 그리고 명령줄 도구(harper-cli)다.

2왜 주목받는가

문법 검사기 시장엔 이미 거인들이 있다. Grammarly(상용), LanguageTool(오픈소스), hunspell(철자만). harper가 이들 사이를 비집고 트렌딩에 오른 이유는 딱 하나로 요약된다 — 속도와 프라이버시를 동시에 잡았고, 그 격차가 "조금"이 아니라 "자릿수(order of magnitude)" 수준이라는 것이다.

레포의 COMPARISON.md가 제시하는 정면 비교표다(원문 인용):

숫자를 곱씹어 보자. harper의 10ms는 LanguageTool(650ms)보다 약 65배, Grammarly(4000ms)보다 약 400배 빠르다. 문법 검사에서 속도는 단순한 편의가 아니다. 타이핑하는 동안 글자마다 실시간으로 검사하려면, 왕복 수백 밀리초는 곧 "느껴지는 렉"이 된다. harper는 그 지연을 사람이 인지하기 어려운 수준으로 떨어뜨렸다.

또 하나 놓치기 쉬운 강점은 침투 범위다. harper는 순수한 산문만 검사하는 게 아니라, harper-comments + tree-sitter로 소스 코드의 주석과 문자열만 뽑아 검사하고, Markdown·LaTeX·Typst·AsciiDoc·Org-mode·깃 커밋 메시지까지 포맷별 파서를 갖췄다. 개발자가 코드를 쓰든 문서를 쓰든 커밋을 쓰든, 같은 엔진 하나가 따라붙는다. 이 "어디에나 붙는 단일 코어" 전략이 harper를 단순 맞춤법 검사기 이상으로 만든다.

3기술 스택 전체 지도

harper는 Rust 에디션 2024로 쓰인 거대한 Cargo 워크스페이스다. 워크스페이스란 여러 개의 크레이트(Rust의 패키지 단위)를 한 저장소에서 함께 빌드·관리하는 구조인데, harper는 무려 21개로 잘게 쪼개 놨다. "왜 이렇게 잘게?"의 답이 곧 이 프로젝트의 설계 철학이다 — 코어는 순수하게, 주변부는 갈아끼울 수 있게.

3-1. 크레이트 역할 지도 (핵심만)

3-2. harper-core를 떠받치는 크레이트들

엔진 심장부의 의존성을 보면 harper가 "무엇으로 빠른가"가 드러난다. 무거운 ML 프레임워크가 아니라, 작고 날카로운 자료구조 라이브러리들로 채워져 있다.

릴리스 빌드 프로파일도 성능에 진심이다. Cargo.toml은 opt-level=3(최대 최적화), lto="fat"(링크 시점 전역 최적화), panic="abort"(패닉 처리 코드 제거로 바이너리 축소)로 설정돼 있다. "빠른 언어를 골랐으니 끝"이 아니라, 컴파일러가 낼 수 있는 최대치까지 짜냈다는 뜻이다.

3-3. 언어별 구성

GitHub 기준 언어 비율은 Rust 79.1% · TypeScript 11.6% · Svelte 6.0% 순이다. 로컬 집계로는 Rust가 590개 파일 12만 줄+, TS가 154개 파일 1.8만 줄. 즉 두뇌는 전부 Rust이고, JS/TS/Svelte는 그 두뇌를 브라우저·에디터·웹사이트에 연결하는 얇은 배선이다. 프론트엔드 툴체인은 Node 22+·pnpm 10·포매터는 Biome를 쓴다.

4아키텍처 심화 분석

harper를 이해하는 가장 빠른 길은 "텍스트 한 줄이 어떤 컨베이어 벨트를 지나 '여기 오타요'가 되는지"를 따라가는 것이다. 부품 이름부터 외우면 길을 잃는다. 흐름부터 보자.

4-1. 독수리 시점 — 검사 파이프라인 전체

이 벨트에서 가장 영리한 결정이 ①번에 숨어 있다. harper는 문자열을 잘라 복사하지 않는다. 원문을 Lrc<[char]>(참조 카운트 공유 배열)로 딱 한 번 만들어 두고, 모든 토큰은 "원문의 몇 번째부터 몇 번째까지"라는 범위(span)만 들고 다닌다. 이게 무할당(zero-copy) 설계의 핵심이다 — 수천 개 토큰을 만들어도 문자열 복사가 0번이니, 그만큼 빠르고 메모리를 덜 쓴다.

4-2. 규칙 엔진 — 트레잇 하나로 284개를 꿴다

harper의 문법 규칙 284개는 어떻게 관리될까? 답은 Rust의 트레잇(trait)이다. 모든 규칙은 Linter라는 공통 인터페이스를 구현하는 "무상태 부품"이다.

pub trait Linter: LSend {
    fn lint(&mut self, document: &Document) -> Vec<Lint>;
    fn description(&self) -> &str;
}

그런데 규칙 284개를 매번 이 저수준 트레잇으로 손수 짜면 지친다. 그래서 harper는 대부분의 규칙이 쓰는 고수준 트레잇 ExprLinter를 얹었다. "찾을 패턴(expr)"과 "매치되면 어떻게 고칠지(match_to_lint)"만 선언하면, Linter 구현은 자동으로 딸려 온다(블랭킷 impl).

pub trait ExprLinter: LSend {
    type Unit: DocumentIterator;   // Chunk(절) | Sentence(문장) 단위
    fn expr(&self) -> &dyn Expr;              // 찾을 패턴
    fn match_to_lint(&self, matched: &[Token], src: &[char]) -> Option<Lint>;
    fn description(&self) -> &str;
}

이 Expr가 바로 harper가 과거 의존하던 nlprule을 걷어내고 자체 개발한 선언적 패턴 언어다. 소스 주석은 그 동기를 이렇게 적는다 — "규칙을 쓰기 쉽게, 그리고 읽기 쉽게. 남의 Rust 코드 로직을 손으로 파싱하던 시절은 끝." SequenceExpr 빌더에 40개+ 콤비네이터를 체이닝해 "비교급 형용사 → 공백 → that → 단어" 같은 패턴을 문장처럼 선언한다.

이 284개는 LintGroup이라는 중앙 레지스트리가 매크로로 등록·실행한다. 내역을 세어 보면 Expr 기반 224개 + 커스텀 구조체 35개 + 사전/방언 필요 25개다. 규칙의 종류(LintKind)도 21가지로 세분화돼 있는데, 흔한 오타·철자뿐 아니라 Eggcorn(민간어원 오류, 예: "for all intensive purposes"), Malapropism(비슷한 소리 오용), 중복 표현, 지역 방언까지 잡는다.

4-3. 사전의 속 — FST + 레벤슈타인 오토마톤

"오프라인인데 어떻게 오타 교정까지?"의 답이 여기 있다. harper의 사전은 dictionary.dict(hunspell 스타일, 54,719줄)를 FST(Finite State Transducer)로 컴파일해 실행 파일 안에 넣는다(include_str!). FST는 수만 단어를 글자 공유 그래프로 압축해, 조회를 "단어 길이에 비례하는" 속도로 처리하는 자료구조다.

오타 교정은 여기에 레벤슈타인 오토마톤(Levenshtein automaton)을 교차시킨다. "편집거리 3 이내의 모든 단어"를 받아들이는 오토마톤을 즉석에서 만들고, 그걸 FST와 교차(intersection)해 비슷한 단어 후보를 한 번에 스트리밍으로 뽑는다. 후보 랭킹도 정교하다 — 첫 글자가 같으면 가점, 흔한 단어면 가점, 방언 변형(color/colour, -ize/-ise)을 인지해 감점하는 휴리스틱이 붙어 있다. 접사(affix) 확장도 있어서, annotations.json의 접두/접미사 규칙(un-, -ment, -ly …)이 어간을 곱해 실효 어휘를 5.4만보다 훨씬 크게 파생시킨다.

4-4. LSP — 에디터와 harper가 대화하는 법

harper-ls는 언어 서버 프로토콜(LSP)을 구현한다. LSP는 마이크로소프트가 표준화한 "에디터↔언어도구" 공용 규약으로, 이걸 구현하면 VS Code·Neovim·Helix·Emacs·Zed에 한 번에 붙는다. 통신 방식은 기본 TCP(127.0.0.1:4000) 또는 --stdio 표준입출력 모드다.

즉 당신이 에디터에서 타이핑하면 did_change가 날아가고, harper-ls가 즉시 재검사해 밑줄(publish_diagnostics)을 그린다. 밑줄에 커서를 올려 퀵픽스를 부르면 code_action으로 수정 제안이 온다. 이 왕복이 전부 로컬 프로세스 간 통신이라 네트워크가 개입하지 않는다 — 2번 섹션의 "10ms"가 실제 편집 경험으로 체감되는 지점이다.

5디렉토리 구조 해부

워크스페이스 최상위를 열면 harper-* 크레이트들이 나란히 있고, 그 무게중심은 압도적으로 harper-core에 쏠려 있다. 아래는 핵심만 추린 트리다.

이 구조의 교훈: "확장 지점을 파일 규칙으로 못박아 두면 기여가 쉬워진다." 새 문법 규칙을 넣고 싶으면 linting/에 .rs 하나(로직 + #[test])를 만들어 LintGroup에 매크로로 등록하면 끝이다. 코어의 나머지는 손대지 않는다. iFixAi가 "검사 하나 = 폴더 하나"였다면, harper는 "규칙 하나 = 파일 하나 + 등록 한 줄"이다.

6학습 포인트

impl Default for ThatThan {
    fn default() -> Self {
        let expr = SequenceExpr::default()
            .then_kind_except(TokenKind::is_comparative_adjective, &["better","later"])
            .t_ws().t_aco("that").t_ws()      // 공백-that-공백
            .then_word_except(&["way"]);
        Self { expr }
    }
}

pub struct Token {
    pub span: Span<char>,              // 원문의 [start, end) 범위
    pub kind: TokenKind,
}
pub enum TokenKind {
    Word(Option<DictWordMetadata>),   // None = 사전에 없는 단어
    Punctuation(Punctuation), Number(Number),
    Space(usize), Url, EmailAddress, Unlintable, …
}

7시스템 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/Automattic/harper (Apache-2.0 · v2.6.0 · ★10.5k)
• TrendShift: trendshift.io/repositories/12372 (2026-07-24 Daily #4)
• 웹 데모: writewithharper.com (설치 없이 WASM으로 브라우저에서 체험)
• 핵심 문서: COMPARISON.md(경쟁 비교표) · README.md(설계 철학) · docs/
• 핵심 소스: harper-core/src/linting/mod.rs(Linter 트레잇) · expr_linter.rs · that_than.rs(규칙 예시) · spell/fst_dictionary.rs(FST 사전) · harper-ls/src/backend.rs(LSP)
• 바로 써볼 것: VS Code "Harper" 확장 설치 · 또는 harper-ls --stdio를 에디터 LSP에 연결
• 배경 개념: FST(Lucene·Elasticsearch) · Levenshtein automaton · Language Server Protocol · Rust trait / blanket impl · WASM(wasm-pack)