easyen 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhangxiangliang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.EN.md

@@ -0,0 +1,22 @@
+# easyen
+
+[English](README.EN.md) · [中文](README.md)
+
+Ever notice how AI likes to dress English up? It says simple things in hard
+words, and gives one idea three different ways — tiring to read. It is not the
+AI's fault; it is just how it was trained, and it does not feel it.
+
+easyen checks two things in the AI's English, and reminds it to keep things
+simple:
+
+* **Words** — which words are too hard, picked out for you.
+* **Sentences** — which sentences are too long, picked out for you.
+
+It only measures; it changes nothing. It shows you the hard words and the long
+sentences clearly. Whether to change them, and how — the AI decides.
+
+## How to use
+
+Hand this one line to your AI (like Claude Code), and it does the rest:
+
+> Read and follow https://github.com/zhangxiangliang/easyen/blob/main/SKILL.md

package/README.md

@@ -0,0 +1,20 @@
+# easyen
+
+[English](README.EN.md) · [中文](README.md)
+
+你有没有发现，让 AI 写英文，它总爱端着——简单的意思非说得文绉绉，一个意思还换着好几种说法，读起来累人。
+这不怪它，是训练出来的习惯，它自己没感觉。
+
+easyen 就帮 AI 量两件事，提醒它把话说简单点：
+
+* **词汇** —— 哪些词超纲了，挑出来。
+* **句子** —— 哪些句子太长了，挑出来。
+
+它只量、不改。哪些词偏难、哪些句子绕，给你标得清清楚楚；至于换不换、怎么换，
+AI 自己拿主意。
+
+## 如何使用
+
+把下面这句话丢给你的 AI（比如 Claude Code），剩下的它自己搞定：
+
+> Read and follow https://github.com/zhangxiangliang/easyen/blob/main/SKILL.md

package/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: easyen
+description: Check how easy an English text is to read — its word level and its sentence length. Use it when writing or checking English that should stay simple (for learners), to find hard words to change and long sentences to break up, or to keep your own English at a chosen level.
+---
+
+# easyen
+
+See how easy a piece of English is to read, by running `npx easyen`.
+It gives you two simple signals — you decide what to change:
+
+1. **Words** — how many of the words are in a chosen word list, and which words
+   are too hard.
+2. **Sentences** — the average sentence length, and which sentences are long.
+
+easyen only reports. It does not change your text. You decide which hard words
+to make simpler and which long sentences to break up.
+
+## When to use
+
+- You wrote some English and want it to stay simple for the reader.
+- You want to find the hard words or long sentences in a text.
+- You want to keep your writing at a level (everyday, academic, or technical).
+
+## How to run
+
+No install needed — `npx easyen` gets the package on first run. It reads text
+from stdin and prints JSON. Pipe the text in, using whatever your shell offers
+(this follows the Unix convention, and works on macOS, Linux, and Windows
+PowerShell / cmd). `everyday` is the default word list.
+
+```bash
+cat your-doc.md | npx easyen                 # macOS / Linux
+Get-Content your-doc.md | npx easyen         # Windows PowerShell
+```
+
+If piping is hard on your system, read a file directly instead:
+
+```bash
+npx easyen --file your-doc.md --dict everyday,tech
+```
+
+You can also compose with other tools — e.g. strip code first so it does not
+count as hard words: `<remove code> | npx easyen --dict everyday,tech`.
+
+### Choose a word list by reader
+
+`everyday` is the base. The others are **add-ons** — combine them onto everyday,
+like `everyday,academic`; each one only adds its own extra words.
+
+- `everyday` — the base, about 2800 common words. Use it alone for the simplest level.
+- `academic` — academic words. `--dict everyday,academic`
+- `tech` — software words (api, deploy, schema ...). `--dict everyday,tech`
+- `frameworks` — tool and language names (vue, vite, webpack, docker ...).
+  `--dict everyday,tech,frameworks` for a frontend or server text.
+
+Use only what the reader needs — a smaller list marks more words to change. You
+can also add your own word file (one word per line), e.g. your team's product
+names:
+
+```bash
+cat your-doc.md | npx easyen --dict everyday,tech,./our-product-names.txt
+```
+
+## Reading the result
+
+The JSON has:
+
+- `ratio` — 0 to 1, how much of the text is in the word list (higher = easier).
+- `hardWords` — words not in the list, sorted A–Z. These are the ones to change.
+- `hardWordCounts` — the same words with how many times each one appears, most
+  first. Fix the common ones first.
+- `sentences.wordsPerSentence` — the average sentence length (lower reads easier).
+- `sentences.longSentences` — sentences over 30 words. These are the ones to
+  break up.
+
+## What to do with it
+
+These are **defaults, not rules**. Adapt them to your project, your reader, and
+your taste — projects differ, and readers know different words. The signals show
+you what to look at; you choose what to change.
+
+**Hard words.** A hard word may have a simpler form (verify → check) — change it.
+Or it may be a needed term (an api name), or a word the reader already knows (a
+reader who learned English for an exam may find `implement` easier than "carry
+out") — then keep it. You decide, based on the reader.
+
+**Long sentences.** Split them: one idea per sentence, about 15–20 words,
+subject then verb then object. Avoid chaining ideas with "which" / "that", and
+avoid stacking nouns ("data migration rollback procedure" → "a plan to undo the
+data change").
+
+**A few habits that help, when they fit:**
+- Keep a technical term, but explain it the first time ("idempotent — safe to
+  run more than once with the same result").
+- Use the same word for the same thing every time (not ticket → task → work item).
+- Drop idioms and slang ("a piece of cake" → "easy").
+- Prefer short paragraphs, lists, and one example after each point.
+
+Then run easyen again to check the signals improved.
+
+## Notes
+
+- Remove code and links from the text before you check it, so code does not
+  count as hard words.
+- Keep the word list small — that is the point: a small list marks more words to
+  make simpler. Do not reach for a bigger list just to raise the score.

package/dist/base-form.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Return every possible base form for a lower-cased word, including the word
+ * itself. The result is a de-duplicated array in a fixed, deterministic order
+ * (insertion order), so look-ups always try the forms the same way.
+ */
+export declare function possibleBaseForms(word: string): string[];

package/dist/base-form.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.possibleBaseForms = possibleBaseForms;
+/**
+ * Reduce an inflected word to a set of candidate base forms.
+ *
+ * "base form" = the dictionary form of a word: studies -> study, ran -> run.
+ * We do NOT need the single correct base form. We only ask: "is any plausible
+ * base form of this word in the dictionary?" So we generate several candidates
+ * by reversing common English ending rules, plus the irregular map, and let
+ * the caller test each one against the dictionary.
+ */
+const irregulars_1 = require("./irregulars");
+/** A consonant doubling like "stopp" (ed) or "runn" (ing) -> drop one. */
+function deDouble(stem) {
+    const n = stem.length;
+    if (n < 2)
+        return null;
+    const a = stem[n - 1];
+    const b = stem[n - 2];
+    if (a === b && !"aeiou".includes(a))
+        return stem.slice(0, -1);
+    return null;
+}
+/**
+ * Add a stem and its near variants (bare, +"e", de-doubled) as candidates.
+ * Example: "mak" -> also "make"; "stopp" -> also "stop".
+ */
+function pushStemVariants(out, stem) {
+    if (stem.length >= 2)
+        out.add(stem);
+    out.add(stem + "e");
+    const dd = deDouble(stem);
+    if (dd && dd.length >= 2)
+        out.add(dd);
+}
+/**
+ * Return every possible base form for a lower-cased word, including the word
+ * itself. The result is a de-duplicated array in a fixed, deterministic order
+ * (insertion order), so look-ups always try the forms the same way.
+ */
+function possibleBaseForms(word) {
+    const out = new Set();
+    out.add(word);
+    const irregular = irregulars_1.IRREGULARS[word];
+    if (irregular)
+        out.add(irregular);
+    // Too short to inflect meaningfully.
+    if (word.length <= 2)
+        return [...out];
+    // --- plural / 3rd person singular: -s / -es / -ies ---
+    if (word.endsWith("ies") && word.length > 4) {
+        out.add(word.slice(0, -3) + "y"); // studies -> study
+    }
+    if (word.endsWith("ves") && word.length > 4) {
+        out.add(word.slice(0, -3) + "f"); // wolves -> wolf
+        out.add(word.slice(0, -3) + "fe"); // knives -> knife
+    }
+    if (word.endsWith("es") && word.length > 3) {
+        out.add(word.slice(0, -2)); // boxes -> box, goes -> go
+        out.add(word.slice(0, -1)); // houses -> house
+    }
+    if (word.endsWith("s") && !word.endsWith("ss") && word.length > 3) {
+        out.add(word.slice(0, -1)); // cats -> cat
+    }
+    // --- past tense / past participle: -ed / -ied ---
+    if (word.endsWith("ied") && word.length > 4) {
+        out.add(word.slice(0, -3) + "y"); // studied -> study
+    }
+    if (word.endsWith("ed") && word.length > 3) {
+        pushStemVariants(out, word.slice(0, -2)); // walked->walk, liked->like, stopped->stop
+    }
+    // --- present participle / gerund: -ing ---
+    if (word.endsWith("ing") && word.length > 4) {
+        pushStemVariants(out, word.slice(0, -3)); // walking->walk, making->make, running->run
+    }
+    // --- comparative / superlative: -er / -est ---
+    if (word.endsWith("ier") && word.length > 4) {
+        out.add(word.slice(0, -3) + "y"); // happier -> happy
+    }
+    if (word.endsWith("iest") && word.length > 5) {
+        out.add(word.slice(0, -4) + "y"); // happiest -> happy
+    }
+    if (word.endsWith("er") && word.length > 3) {
+        pushStemVariants(out, word.slice(0, -2)); // bigger->big, taller->tall
+    }
+    if (word.endsWith("est") && word.length > 4) {
+        pushStemVariants(out, word.slice(0, -3)); // biggest->big, tallest->tall
+    }
+    // --- adverb: -ly ---
+    if (word.endsWith("ily") && word.length > 4) {
+        out.add(word.slice(0, -3) + "y"); // happily -> happy
+    }
+    if (word.endsWith("ly") && word.length > 3) {
+        out.add(word.slice(0, -2)); // quickly -> quick
+    }
+    return [...out];
+}

package/dist/classify.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tiny predicates over a single token. Each answers one yes/no question and
+ * is pure.
+ */
+/** True when the word is a number like "3", "3.14" or "1,000". */
+export declare function isNumber(token: string): boolean;
+/** True when the token starts with an upper-case letter. */
+export declare function isCapitalized(token: string): boolean;
+/**
+ * True for a single-letter token that is not a real word. "a" and "i" are
+ * words; every other lone letter (b, e, g, x ...) comes from abbreviations,
+ * list markers or variable names and is not vocabulary.
+ */
+export declare function isSingleLetter(token: string): boolean;
+/** True when the token is a spelled-out number word ("two", "zero"). */
+export declare function isNumberWord(token: string): boolean;
+/**
+ * True for an all-caps token of 2+ letters (AWS, JSON, SEO). These are
+ * acronyms, not vocabulary. Used only when the token is also unknown, so a
+ * normal word written in capitals (NOTE) still counts via its lower-case form.
+ */
+export declare function isAllCapitals(token: string): boolean;

package/dist/classify.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Tiny predicates over a single token. Each answers one yes/no question and
+ * is pure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNumber = isNumber;
+exports.isCapitalized = isCapitalized;
+exports.isSingleLetter = isSingleLetter;
+exports.isNumberWord = isNumberWord;
+exports.isAllCapitals = isAllCapitals;
+/** True when the word is a number like "3", "3.14" or "1,000". */
+function isNumber(token) {
+    return /^[0-9]/.test(token);
+}
+/** True when the token starts with an upper-case letter. */
+function isCapitalized(token) {
+    return /^[A-Z]/.test(token);
+}
+/**
+ * True for a single-letter token that is not a real word. "a" and "i" are
+ * words; every other lone letter (b, e, g, x ...) comes from abbreviations,
+ * list markers or variable names and is not vocabulary.
+ */
+function isSingleLetter(token) {
+    if (token.length !== 1)
+        return false;
+    const lower = token.toLowerCase();
+    return lower !== "a" && lower !== "i";
+}
+/** Spelled-out cardinal numbers and magnitudes. Treated like digits. */
+const NUMBER_WORDS = new Set([
+    "zero", "one", "two", "three", "four", "five", "six", "seven", "eight",
+    "nine", "ten", "eleven", "twelve", "thirteen", "fourteen", "fifteen",
+    "sixteen", "seventeen", "eighteen", "nineteen", "twenty", "thirty",
+    "forty", "fifty", "sixty", "seventy", "eighty", "ninety",
+    "hundred", "thousand", "million", "billion", "trillion",
+]);
+/** True when the token is a spelled-out number word ("two", "zero"). */
+function isNumberWord(token) {
+    return NUMBER_WORDS.has(token.toLowerCase());
+}
+/**
+ * True for an all-caps token of 2+ letters (AWS, JSON, SEO). These are
+ * acronyms, not vocabulary. Used only when the token is also unknown, so a
+ * normal word written in capitals (NOTE) still counts via its lower-case form.
+ */
+function isAllCapitals(token) {
+    return token.length >= 2 && /^[A-Z]+$/.test(token);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Command-line interface for easyen. Reads text from stdin (the Unix way) and
+ * prints JSON, so it composes with other tools across platforms:
+ *
+ *   cat doc.md | npx easyen --dict everyday,tech     # macOS / Linux
+ *   Get-Content doc.md | npx easyen                  # Windows PowerShell
+ *   type doc.md | npx easyen                         # Windows cmd
+ *
+ * When piping is not convenient, read a file directly:  npx easyen --file doc.md
+ *
+ * Zero dependencies: arguments are parsed by hand.
+ */
+const node_fs_1 = require("node:fs");
+const index_1 = require("./index");
+function parseArgs(argv) {
+    const args = { dict: "everyday", options: {}, help: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        switch (argv[i]) {
+            case "-h":
+            case "--help":
+                args.help = true;
+                break;
+            case "-d":
+            case "--dict":
+                args.dict = argv[++i] ?? args.dict;
+                break;
+            case "-f":
+            case "--file":
+                args.file = argv[++i];
+                break;
+            case "--proper-nouns": // ignore likely proper nouns
+                args.options.ignoreProperNouns = true;
+                break;
+            case "--count-numbers": // count numbers instead of ignoring them
+                args.options.ignoreNumbers = false;
+                break;
+        }
+    }
+    return args;
+}
+const HELP = `easyen — check how easy an English text is to read. Prints JSON.
+
+Reads text from stdin (pipe it in), the standard Unix way. Works on any shell
+that supports pipes (bash, PowerShell, cmd). If piping is hard, use --file.
+
+Usage:
+  cat file.md | easyen [options]            # macOS / Linux
+  Get-Content file.md | easyen [options]    # Windows PowerShell
+  easyen --file file.md [options]           # any OS, no pipe
+
+Options:
+  -d, --dict <spec>   Word list to use (default: everyday). Comma-separated to
+                      combine: each item is a built-in name OR a path to a
+                      word-list file. e.g.  --dict everyday,tech,./terms.txt
+  -f, --file <path>   Read the text from a file instead of stdin
+  --proper-nouns      Ignore capitalised unknown words (names, places)
+  --count-numbers     Count numbers instead of ignoring them
+  -h, --help          Show this help
+
+Built-in word lists: ${(0, index_1.listDictionaries)().join(", ")}`;
+/**
+ * Turn a --dict spec into a dictionary. A single built-in name is passed
+ * through (so its cached Set is reused); anything else (multiple items, or a
+ * file path) is read and merged into one Set.
+ */
+function resolveDictSpec(spec) {
+    const builtins = new Set((0, index_1.listDictionaries)());
+    const parts = spec.split(",").map((s) => s.trim()).filter(Boolean);
+    if (parts.length === 1 && builtins.has(parts[0]))
+        return parts[0];
+    const sources = parts.map((part) => builtins.has(part) ? part : (0, node_fs_1.readFileSync)(part, "utf8").split(/\s+/));
+    return (0, index_1.combineDictionaries)(...sources);
+}
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    // --help, or no input at all (no --file and nothing piped): show help.
+    if (args.help || (!args.file && process.stdin.isTTY)) {
+        console.log(HELP);
+        return;
+    }
+    try {
+        const text = args.file ? (0, node_fs_1.readFileSync)(args.file, "utf8") : readStdin();
+        if (!text.trim()) {
+            console.error("No text given. Pipe text in, or use --file <path>.");
+            process.exitCode = 1;
+            return;
+        }
+        const result = (0, index_1.checkCoverage)(text, resolveDictSpec(args.dict), args.options);
+        const sentences = (0, index_1.checkSentences)(text);
+        console.log(JSON.stringify({ ...result, sentences }, null, 2));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+function readStdin() {
+    try {
+        return (0, node_fs_1.readFileSync)(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+main();

package/dist/coverage.d.ts

@@ -0,0 +1,64 @@
+import { DictionaryName } from "./dictionaries";
+/** What you can pass as the dictionary argument. */
+export type DictionarySource = DictionaryName | Iterable<string> | ReadonlySet<string>;
+export interface CheckOptions {
+    /**
+     * Ignore pure-number tokens ("3", "3.14"). Numbers are not vocabulary, so
+     * they are excluded from the ratio by default.
+     * @default true
+     */
+    ignoreNumbers?: boolean;
+    /**
+     * Ignore capitalised words that are not in the dictionary (likely proper
+     * nouns such as names or places). Note: this is a simple, position-free
+     * heuristic — with a small dictionary it may also drop a sentence-initial
+     * normal word. Use a full dictionary for best results.
+     * @default false
+     */
+    ignoreProperNouns?: boolean;
+}
+export interface WordResult {
+    /** Lower-cased word that was checked. */
+    word: string;
+    /** Whether a base form of this word is in the dictionary. */
+    known: boolean;
+    /** The matching dictionary entry, if found (may differ from `word`). */
+    base?: string;
+}
+/** A hard word and how many times it appears in the text. */
+export interface HardWord {
+    word: string;
+    count: number;
+}
+export interface CoverageResult {
+    /** Number of counted words (after the ignore filters). */
+    total: number;
+    /** Number of counted words found in the dictionary. */
+    covered: number;
+    /** covered / total, in [0, 1]. Is 0 when there are no counted words. */
+    ratio: number;
+    /** Hard words (not in the dictionary), unique and sorted A–Z. Reword these. */
+    hardWords: string[];
+    /** Hard words with how many times each appears, most frequent first. */
+    hardWordCounts: HardWord[];
+    /** Per-word result, in reading order. */
+    details: WordResult[];
+}
+/**
+ * Combine several dictionary sources (built-in names, word lists, or Sets)
+ * into one lower-cased look-up Set. Lets a caller compose their own
+ * vocabulary — e.g. the everyday list plus a list of allowed domain words:
+ *
+ *   const dict = combineDictionaries("everyday", ["api", "endpoint"]);
+ *   checkCoverage(text, dict);
+ */
+export declare function combineDictionaries(...sources: DictionarySource[]): Set<string>;
+/**
+ * Check what fraction of a text's words are covered by a vocabulary.
+ *
+ * @param text       The text to check.
+ * @param dictionary A built-in dictionary name, a word list (base forms
+ *                   only), or a prebuilt Set.
+ * @param options    See {@link CheckOptions}.
+ */
+export declare function checkCoverage(text: string, dictionary: DictionarySource, options?: CheckOptions): CoverageResult;

package/dist/coverage.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.combineDictionaries = combineDictionaries;
+exports.checkCoverage = checkCoverage;
+/**
+ * The top-level pipeline. `checkCoverage` only wires the small pure steps
+ * together; every real piece of logic lives in its own single-purpose
+ * function (normalize -> expand -> extract -> match -> summarize).
+ */
+const pipe_1 = require("./pipe");
+const normalize_1 = require("./normalize");
+const extract_1 = require("./extract");
+const classify_1 = require("./classify");
+const dictionary_1 = require("./dictionary");
+const dictionaries_1 = require("./dictionaries");
+/** Clean raw text into a space-separated, contraction-free string. */
+const prepare = (0, pipe_1.pipe)(normalize_1.normalizeApostrophes, normalize_1.expandContractions);
+/** Turn one extracted token into a WordResult, or null if it is filtered out. */
+function classifyToken(token, dict, options) {
+    // Numbers and spelled-out number words are not vocabulary to grade.
+    if ((0, classify_1.isNumber)(token) || (0, classify_1.isNumberWord)(token)) {
+        return options.ignoreNumbers ? null : { word: token.toLowerCase(), known: false };
+    }
+    // A lone letter (b, e, g, x ...) is never a word; never count it.
+    if ((0, classify_1.isSingleLetter)(token))
+        return null;
+    const lower = token.toLowerCase();
+    const base = (0, dictionary_1.findInDictionary)(lower, dict);
+    if (base === null) {
+        // Unknown all-capitals word (AWS, JSON) is a short form, not vocabulary.
+        if ((0, classify_1.isAllCapitals)(token))
+            return null;
+        if (options.ignoreProperNouns && (0, classify_1.isCapitalized)(token))
+            return null;
+        return { word: lower, known: false };
+    }
+    return { word: lower, known: true, base };
+}
+/**
+ * Combine several dictionary sources (built-in names, word lists, or Sets)
+ * into one lower-cased look-up Set. Lets a caller compose their own
+ * vocabulary — e.g. the everyday list plus a list of allowed domain words:
+ *
+ *   const dict = combineDictionaries("everyday", ["api", "endpoint"]);
+ *   checkCoverage(text, dict);
+ */
+function combineDictionaries(...sources) {
+    const set = new Set();
+    for (const source of sources) {
+        const words = typeof source === "string" ? (0, dictionaries_1.getDictionary)(source) : source;
+        for (const word of words) {
+            const trimmed = word.trim().toLowerCase();
+            if (trimmed)
+                set.add(trimmed);
+        }
+    }
+    return set;
+}
+/**
+ * Turn any accepted dictionary source into a fast look-up set. Built-in
+ * dictionaries are built once and cached, so repeated calls are cheap.
+ */
+const builtinCache = new Map();
+function resolveDictionary(source) {
+    if (typeof source === "string") {
+        const cached = builtinCache.get(source);
+        if (cached)
+            return cached;
+        const set = (0, dictionary_1.buildDictionary)((0, dictionaries_1.getDictionary)(source));
+        builtinCache.set(source, set);
+        return set;
+    }
+    if (source instanceof Set)
+        return source;
+    return (0, dictionary_1.buildDictionary)(source);
+}
+/** Fold per-word results into the final coverage summary. */
+function summarize(results) {
+    const counts = new Map();
+    let covered = 0;
+    for (const result of results) {
+        if (result.known)
+            covered += 1;
+        else
+            counts.set(result.word, (counts.get(result.word) ?? 0) + 1);
+    }
+    // Most frequent first; ties sorted A–Z for a stable, deterministic order.
+    const hardWordCounts = [...counts.entries()]
+        .map(([word, count]) => ({ word, count }))
+        .sort((a, b) => b.count - a.count || a.word.localeCompare(b.word));
+    const total = results.length;
+    return {
+        total,
+        covered,
+        ratio: total === 0 ? 0 : covered / total,
+        hardWords: [...counts.keys()].sort(),
+        hardWordCounts,
+        details: results,
+    };
+}
+/**
+ * Check what fraction of a text's words are covered by a vocabulary.
+ *
+ * @param text       The text to check.
+ * @param dictionary A built-in dictionary name, a word list (base forms
+ *                   only), or a prebuilt Set.
+ * @param options    See {@link CheckOptions}.
+ */
+function checkCoverage(text, dictionary, options = {}) {
+    const settings = {
+        ignoreNumbers: options.ignoreNumbers ?? true,
+        ignoreProperNouns: options.ignoreProperNouns ?? false,
+    };
+    const dict = resolveDictionary(dictionary);
+    const results = (0, extract_1.splitWords)(prepare(text))
+        .flatMap(extract_1.splitCamelCase) // getUserById -> get / User / By / Id
+        .map((token) => classifyToken(token, dict, settings))
+        .filter((result) => result !== null);
+    return summarize(results);
+}