@gege-mn/gege-linter

中文文档
0.13.0发布于 2026/11/07MITTypeScriptES Module近 30 天下载 2162

Linter for traditional Mongolian script (Mongol bichig) text — flags incorrect or legacy Unicode usage: suffix connectors, FVS placement, PUA leftovers.

原始使用文档
文档目录11 节
  1. Three invisible failures
  2. The ground kept moving
  3. Usage
  4. CLI
  5. Library
  6. Rules
  7. Modes
  8. Why it matters
  9. Agent skills
  10. Development
  11. License

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

Three failure modes, each shown wrong-vs-correct with code points: NNBSP vs MVS render pixel-identically; a plain space demotes the genitive suffix to a standalone vowel; Ali Gali U+1888 passes for Hudum U+182C at a glance.

  1. 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.
  2. 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.
  3. 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

RuleCodeSeverityWhat it flags
mvs-contextGL0201errorMVS not sitting between two Mongolian letters — structurally broken; fonts render a visible nominal glyph
fvs-placementGL0301–03errorFVS1–4 not immediately after the Mongolian letter it modifies (a doubled FVS fails the same test)
no-puaGL0401errorPrivate Use Area code points — Menksoft-era glyph encoding, tofu everywhere else; contiguous runs report once
detached-suffixGL1201errorThe 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-suffixGL1202warningFormal mode only. The comitative ᠲᠠᠢ / ᠲᠡᠢ (-тай/-тэй) and the ordinals ᠳᠤᠭᠠᠷ / ᠳᠦᠭᠡᠷ (-дугаар/-дүгээр), ᠳᠠᠬᠢ / ᠳᠡᠬᠢ (-дахь/-дэх) after a connector. Same fix. Never reported after a digit
wrong-blockGL0501–05warningTodo / Sibe / Manchu / Ali Gali letters in Hudum text; known look-alikes (U+1888/U+1889) get a mechanical fix
zwj-zwnjGL0601–02warningZWJ/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-legacyGL0101–02warningNNBSP joining two Mongolian letters — the pre-16.0 suffix connector; fix: MVS
unknown-suffixGL0801–03warningMVS- (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-suffixGL1301warningA 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-suffixGL1302infoThe same, for suffixes that are also words (ᠪᠠᠷ бар, ᠨᠠᠷ нар, ᠲᠠᠢ тай, ᠳᠤᠷ дур…): the text cannot say which is meant, so no fix
doubled-aeGL1001warningAdjacent ᠠᠠ / ᠡᠡ — 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-aeGL1401warningᠢᠢ + 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-unregisteredGL1501–02warningAn 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-shaGL1601warningᠱ 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-punctuationGL1101–03warningPunctuation 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-oGL0701infoO/Ö (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-punctuationGL1104infoU+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:

RuleCodeSeverityWhat it flags
fusable-stackGL0901infoAn 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).

版本与发布记录

@gege-mn/gege-linter 共发布 19 个版本,首次发布于 2026/07/23;过去 12 个月发布了 19 个版本。

版本发布日期距今
0.13.0latest2026/11/079 天前
0.12.02026/11/069 天前
0.11.02026/11/0312 天前
0.10.32026/10/3115 天前
0.10.22026/10/3115 天前
0.10.12026/10/3115 天前

关于 @gege-mn/gege-linter 的常见问题

@gege-mn/gege-linter 是什么?

Linter for traditional Mongolian script (Mongol bichig) text — flags incorrect or legacy Unicode usage: suffix connectors, FVS placement, PUA leftovers.

如何安装 @gege-mn/gege-linter?

在项目目录运行 npm install @gege-mn/gege-linter,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gege-linter,可以用 npx gege-linter 直接运行。

@gege-mn/gege-linter 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gege-mn/gege-linter 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gege-mn/gege-linter 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gege-mn/gege-linter 可以商用吗?

@gege-mn/gege-linter 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gege-mn/gege-linter 的下载量有多少?

根据 npm 官方下载统计,@gege-mn/gege-linter 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,162 次,日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gege-mn/gege-linter 还在维护吗?

最新版本 0.13.0 发布于 2026/11/07(9 天前);至今共发布 19 个版本,其中过去 12 个月发布了 19 个;首次发布于 2026/07/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。