gege-linter
The errors you cannot see. A linter for traditional Mongolian script (Mongol bichig) — the first of its kind.
Mongol bichig text can look perfect and still be encoded wrong. The script's grammar lives partly in invisible characters — connectors and variation selectors with no shape of their own. When one is wrong, nothing looks broken today; the text quietly fails tomorrow — in another font, another OS, a search index, or a copy-paste.
Three invisible failures

- The legacy connector —
nnbsp-legacy, shipped. NNBSP (U+202F) and MVS (U+180E) joined suffixes render pixel-identically, but the left was made legacy by Unicode 16.0 (2024). No eye and no font can tell; only the bytes differ. - The plain space —
space-before-suffix, shipped. An ordinary space quietly demotes the suffix to a standalone vowel — grammatically visible, yet nothing complains. This exact bug once shipped on gege.mn's footer. - The look-alike letter —
wrong-block, shipped. A letter from the Ali Gali block (Sanskrit–Tibetan transcription) passing for Hudum ᠬ at a glance. Real keyboards actually emit it — and search, sorting, and screen readers all silently break.
The ground kept moving
The "correct" way to write a Mongolian suffix has changed under everyone's feet:
- 1999 — Unicode 3.0 prescribes NNBSP (U+202F) as the suffix connector.
- 2017 — A dedicated suffix-connector character is proposed; the committee takes no action, and its code point later becomes a fourth variation selector instead.
- 2023 — Noto Sans Mongolian is re-engineered onto the new shaping model.
- 2024 — Unicode 16.0 moves the connector role to MVS (U+180E). NNBSP becomes legacy — mentioned only in the rewritten spec chapter, not the release notes.
- 2025 — W3C's Mongolian layout requirements still document the old model.
So text that was correct when written is legacy today, guidance online contradicts itself, and no tool existed to check any of it — for a script used by millions. gege-linter encodes the current model (Unicode 16+, UTN #57) as mechanical rules.
Usage
CLI
pnpm dlx @gege-mn/gege-linter file.txt # lint (or: npx @gege-mn/gege-linter)
gege-linter --fix file.txt # apply mechanical fixes in place
gege-linter --json file.txt # machine-readable output
cat file.txt | gege-linter --fix - > out.txt # stdin; fixed text on stdout
gege-linter --mode formal contract.txt # formal documents (see Modes)
gege-linter --lang mn file.txt # findings in en, mn, zh-Hans or fr
Exit codes: 0 clean or warnings only · 1 error-severity findings ·
2 usage or I/O failure.
Library
import { applyFixes, lint } from '@gege-mn/gege-linter';
const diagnostics = lint(text);
// [{ rule: 'nnbsp-legacy', severity: 'warning', start: 5, end: 6, fix: '\u180E', … }]
const fixed = applyFixes(text, diagnostics); // code-point-safe — never String.slice
Every diagnostic carries code-point offsets and, when the correction is
mechanical, a fix replacement string.
message is English. The same finding in Mongolian, Simplified Chinese or
French:
import { localize } from '@gege-mn/gege-linter';
localize(diagnostics[0], 'mn'); // 'NNBSP (U+202F) нөхцөл холбогч нь …'
// locales: 'en' | 'mn' | 'zh-Hans' | 'fr'
Each diagnostic also names its catalog entry (messageId, e.g.
nnbsp-legacy/connector), the values filled into it (data), and its
language-neutral code (GL0101), for a consumer that keeps its own wording.
Text typed with Tungaamal
import { isTungaamal, tungaamalToUnicode } from '@gege-mn/gege-linter';
if (isTungaamal(text)) text = tungaamalToUnicode(text); // standard Unicode Hudum
Tungaamal's output is the Mongolian block plus two substitutions — feminine k
and g as the Ali Gali look-alikes U+1888/U+1889 — on the pre-Unicode-16
connector model. tungaamalToUnicode corrects the letters first and the
connectors second, which a single applyFixes(text, lint(text)) cannot: a particle still
spelled with U+1889 is not recognised, and gets a connector where it takes a
space. Last, it reads Tungaamal's y before i, inside a word after a vowel:
y + i is the double-tooth i (ᠰᠠᠶᠢᠨ → ᠰᠠᠢᠨ), y + FVS1 + i a real y (may1iγ →
ᠮᠠᠶᠢᠭ), and чамайг/намайг keep FVS1 (čimay1i). Each decision reads the
input, so the second never turns into the first; but for the same reason a
second run would, so run it once. Punctuation and whatever else lint
reports are left for lint.
Text in the Menksoft encoding
import { isMenksoft, menksoftToUnicode } from '@gege-mn/gege-linter';
if (isMenksoft(text)) text = menksoftToUnicode(text); // standard Unicode Hudum
Menksoft text is Private Use Area glyphs (U+E234–E34F), one code point per
letter shape. menksoftToUnicode reads them back as letters with a port of
suragch's mongol_code (CC0), then
applies this package's own fixes to the result: a particle gets a plain space
instead of a connector, and vertical presentation forms become ordinary
punctuation. Hudum only. isMenksoft is true when a Menksoft letter is
present and no Private Use Area code point lies outside the band. no-pua
offers the same reading as a fix, run by run.
Tungaamal, continued
Use it only on text known to be Tungaamal's — real Ali Gali uses those two
letters in their own right, and standard text's own ᠮᠠᠶᠢᠭ would lose its y.
isTungaamal is one test: either look-alike present, and no other Ali Gali
letter anywhere in the text. It is false for Tungaamal text that happens to
contain no feminine k or g, which nothing distinguishes from other legacy
text; when you know the text is Tungaamal's or Kimo's (it uses the same
encoding), call tungaamalToUnicode without asking.
Rules
| Rule | Code | Severity | What it flags |
|---|---|---|---|
mvs-context | GL0201 | error | MVS not sitting between two Mongolian letters — structurally broken; fonts render a visible nominal glyph |
fvs-placement | GL0301–03 | error | FVS1–4 not immediately after the Mongolian letter it modifies (a doubled FVS fails the same test) |
no-pua | GL0401 | error | Private Use Area code points — Menksoft-era glyph encoding, tofu everywhere else; contiguous runs report once |
detached-suffix | GL1201 | error | The habitual verbal ending ᠳᠠᠭ / ᠳᠡᠭ (-даг/-дэг) after a suffix connector (MVS or legacy NNBSP). It is always written attached to the stem; fix: delete the connector, and the MVS of a separated final a/e before it |
detached-suffix | GL1202 | warning | Formal mode only. The comitative ᠲᠠᠢ / ᠲᠡᠢ (-тай/-тэй) and the ordinals ᠳᠤᠭᠠᠷ / ᠳᠦᠭᠡᠷ (-дугаар/-дүгээр), ᠳᠠᠬᠢ / ᠳᠡᠬᠢ (-дахь/-дэх) after a connector. Same fix. Never reported after a digit |
wrong-block | GL0501–05 | warning | Todo / Sibe / Manchu / Ali Gali letters in Hudum text; known look-alikes (U+1888/U+1889) get a mechanical fix |
zwj-zwnj | GL0601–02 | warning | ZWJ/ZWNJ between two Mongolian letters — FVS1–4 is the mechanism for a form override. At a word boundary a joiner is selecting a positional form in isolation, which the core spec sanctions and abbreviations (ЗХУ) rely on, so it is left alone — as are emoji sequences |
nnbsp-legacy | GL0101–02 | warning | NNBSP joining two Mongolian letters — the pre-16.0 suffix connector; fix: MVS |
unknown-suffix | GL0801–03 | warning | MVS- (or legacy NNBSP-) joined letter run not in the curated Hudum suffix dictionary (references/suffixes.md in the mongol-bichig skill); a run that is a separate word is named as one, with a fix to a plain space (after MVS only — after NNBSP nnbsp-legacy already fixes an overlapping span); the separated final a/e (ᠬᠠᠷ‑ᠠ) is exempt |
space-before-suffix | GL1301 | warning | A dictionary suffix after a plain U+0020 instead of a connector, which no font shows and no other rule sees; fix: MVS. Particles other than ᠴᠤ/ᠴᠦ, ᠬᠢ/ᠬᠢᠨ and the words that take a space (ᠤᠤ, ᠦᠭᠡᠢ…) are never reported |
space-before-suffix | GL1302 | info | The same, for suffixes that are also words (ᠪᠠᠷ бар, ᠨᠠᠷ нар, ᠲᠠᠢ тай, ᠳᠤᠷ дур…): the text cannot say which is meant, so no fix |
doubled-ae | GL1001 | warning | Adjacent ᠠᠠ / ᠡᠡ — long a/e take the γ/g hiatus, never a doubled vowel, so this is Cyrillic аа/ээ copied letter for letter. No fix: the reflexive wants ᠢᠶᠠᠨ/ᠢᠶᠡᠨ and the vocative wants a single ᠠ/ᠡ as its own word. ᠣᠣ (short o) and ᠤᠤ/ᠦᠦ are untouched |
ii-before-final-ae | GL1401 | warning | ᠢᠢ + connector + a separated final ᠠ / ᠡ that ends the word (ᠰᠤᠮᠢᠢ‑ᠠ for Сумъяа). The second i is the y: Unicode encodes by sound, and UTN #57 writes daliy·a. Both draw the same in Noto, so only the code points show it; fix: ᠢᠶ, combining with nnbsp-legacy's fix. A long ii elsewhere (γaǰiiqu, qabii) and ii + any other suffix are untouched |
fvs-unregistered | GL1501–02 | warning | An FVS after a Hudum letter that selects no Hudum form — checked against mongfontbuilder's MNG locale through mongol-bichig's fvsStatus, in the letter's joining position (per letter only, next to MVS, NNBSP, ZWJ, ZWNJ or nirugu). GL1502 names a form only Todo, Sibe, Manchu or Ali Gali registers, such as NA + FVS3 medial. Noto draws these as a visible marker. No fix: the writer meant some form, and only a reader knows which |
undotted-sha | GL1601 | warning | ᠱ directly before ᠢ with no selector. UTN #57 makes the dotless form the default there, so the font draws ᠰ and жишээ, жишиг read as if spelled with s; fix: ᠱ + FVS2 (U+180C), which selects the dotted form. A deliberate FVS1 is left alone |
compat-punctuation | GL1101–03 | warning | Punctuation encoded as a presentation form — Vertical Forms (U+FE10–FE1F), CJK Compatibility Forms (U+FE30–FE4F), Small Form Variants (U+FE50–FE6F). These exist only to round-trip GB 18030 / CNS 11643; the vertical glyph is the font's job, and NFKC flattens U+FE16 to bare ? rather than to ?. Fixed to the native ᠂ ᠃ ᠁ for comma / full stop / ellipsis and ? for the question mark (UTN #57 Table 1 requires the CJK form), but plain ASCII ! for the exclamation — no source requires a fullwidth one — and the nominal character otherwise |
non-initial-o | GL0701 | info | O/Ö (U+1823/U+1825) past the first syllable — dumb vowel-position heuristic; loanwords (ᠹᠣᠲᠣ) and lexical exceptions (ᠭᠣᠣᠯ) are legitimate, but ᠮᠣᠩᠭᠣᠯ is a real hit — write ᠮᠣᠩᠭᠤᠯ |
compat-punctuation | GL1104 | info | U+3001 / U+3002 (and halfwidth U+FF61 / U+FF64) inside Hudum text — core spec 13.5 gives the Chinese-borrowed marks to Todo and Sibe; Hudum writes ᠂ / ᠃. Silent unless the text really contains Hudum letters, since these are correct in Chinese. Sanctioned Western , . ? ! are never flagged |
Every finding carries a code — GL, two digits for the rule, two for
the variant (GL0101 is NNBSP as a suffix connector, GL0102 NNBSP before a
particle). It reads the same in every language, and a published code is never
renumbered or reused; codes maps each messageId to its code.
One further rule is exported but not in the default set, because it reports text that is already correct:
| Rule | Code | Severity | What it flags |
|---|---|---|---|
fusable-stack | GL0901 | info | An analytic case + reflexive stack (ᠳᠤ + ᠪᠠᠨ) that may also be written as one fused suffix (ᠳᠠᠭᠠᠨ). Both are correct, so it carries no fix — the fused sequence is named in the message instead |
import { fusableStack, lint, rules } from '@gege-mn/gege-linter';
lint(text, [...rules, fusableStack]); // opt in to the style hint
Modes
The comitative -тай/-тэй and the ordinals -дугаар/-дүгээр, -дахь/-дэх may be joined to the stem with a connector or attached to it: a matter of style in ordinary text, which the default mode leaves alone. Legal and other formal documents attach them, and formal mode reports the connector-joined spelling as a warning with a fix.
import { applyFixes, formalRules, lint } from '@gege-mn/gege-linter';
const diagnostics = lint(text, formalRules); // or rulesFor('formal')
const attached = applyFixes(text, diagnostics);
On the command line it is --mode formal. formalRules is rules with two
rules swapped for their formal variants, detachedSuffixFormal and
nnbspLegacyFormal; use the two together when building a rule list by hand,
because the first deletes connectors the plain nnbspLegacy would rewrite.
The suffix dictionary itself ships as part of the public API (suffixes),
sourced from school grammar, UTN #57, and the mongfontbuilder registry.
Roadmap (see docs/rules.md): FVS registration against
the standardized-variant tables · full stem–suffix vowel-harmony agreement.
Why it matters
- First of its kind. No Mongolian encoding linter existed before this (surveyed 2026-07).
- Mechanical, not opinionated. Rules encode Unicode 16 + UTN #57 — the published standard, not taste.
- Fixes, not just flags. Every legacy connector comes with a one-code-point replacement.
- No third-party dependencies. Pure TypeScript, code-point offsets, runs
anywhere — editor, CI, browser. The one dependency is
@gege-mn/mongol-bichig, the first-party data package that also backs the converter.
Agent skills
Two agent skills cover this
project — mongol-bichig (the script's encoding model, for any agent
that touches bichig text) and gege-linter (using this library and
CLI). Both live in the
mongol-bichig repository,
alongside the source-verified knowledge base they distil:
npx skills add gege-mn/mongol-bichig # pick interactively
npx skills add gege-mn/mongol-bichig --all # both
That repository is also where the deep reference documentation lives — encoding model, history, variation sequences, script styles, suffixes, legacy encodings, fonts and rendering, orthography.
Development
pnpm install
pnpm test
pnpm build
pnpm lint
License
MIT. Example images rendered with Noto Sans Mongolian (OFL).