tdk-api-wrapper 1.3.0 → 1.4.0

package/dist/index.mjs

@@ -2,11 +2,25 @@ import {
   TDK,
   TDKError,
   TDKNetworkError,
-  TDKValidationError
-} from "./chunk-SLNXKZKR.mjs";
+  TDKValidationError,
+  TURKISH_SUFFIXES,
+  TURKISH_VOWELS,
+  getStemCandidates,
+  isVowel,
+  restoreConsonantSoftening,
+  restoreInfinitive,
+  restoreVowelDrop
+} from "./chunk-5TYJDVHK.mjs";
 export {
   TDK,
   TDKError,
   TDKNetworkError,
-  TDKValidationError
+  TDKValidationError,
+  TURKISH_SUFFIXES,
+  TURKISH_VOWELS,
+  getStemCandidates,
+  isVowel,
+  restoreConsonantSoftening,
+  restoreInfinitive,
+  restoreVowelDrop
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tdk-api-wrapper",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "TDK (Türk Dil Kurumu) unofficial live data API wrapper for Node.js",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -16,7 +16,8 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean --shims"
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean --shims",
+    "test": "node test/morphology.test.js"
   },
   "keywords": [
     "tdk",

package/src/cli.ts

@@ -12,6 +12,9 @@ const KNOWN_COMMANDS = new Set([
   "hece",
   "uyum",
   "yazim",
+  "kok",
+  "stem",
+  "deyim",
   "gunun",
   "rastgele",
   "esanlam",
@@ -55,7 +58,7 @@ async function run() {
   if (!command || command === "--help" || command === "-h") {
     console.log("Kullanım: tdk [komut] <kelime> [--json]");
     console.log(
-      "Komutlar: ara, anlam, koken, ornek, hece, uyum, yazim, gunun, rastgele, esanlam, karsit, yabanci, kurallar, kural, karsilastir, analiz, oneri, kubbealti, nisanyan, viki"
+      "Komutlar: ara, anlam, koken, ornek, hece, uyum, yazim, kok, deyim, gunun, rastgele, esanlam, karsit, yabanci, kurallar, kural, karsilastir, analiz, oneri, kubbealti, nisanyan, viki"
     );
     console.log("Not: Komut belirtilmezse doğrudan kelime anlamı aranır (örn: tdk selam)");
     process.exit(command ? 0 : 1);
@@ -123,7 +126,11 @@ async function run() {
         const spellResult = await TDK.checkSpelling(word);
         printResult(spellResult, () => {
           if (spellResult.isCorrect) {
-            console.log("Doğru yazım.");
+            if (spellResult.isInflected && spellResult.root) {
+              console.log(`Doğru yazım (çekimli biçim, kök: ${spellResult.root}).`);
+            } else {
+              console.log("Doğru yazım.");
+            }
           } else {
             console.log(`Yanlış yazım.${spellResult.suggestion ? " Doğrusu: " + spellResult.suggestion : ""}`);
           }
@@ -131,6 +138,35 @@ async function run() {
         break;
       }
 
+      case "kok":
+      case "stem": {
+        if (!word) throw new Error("Kelime belirtmelisiniz.");
+        const stemResult = await TDK.stem(word);
+        printResult(stemResult, () => {
+          if (!stemResult) {
+            console.log("Kök bulunamadı.");
+          } else if (stemResult.isInflected) {
+            console.log(`Kök: ${stemResult.root} (çekimli biçim)`);
+          } else {
+            console.log(`Kök: ${stemResult.root} (yalın biçim)`);
+          }
+        });
+        break;
+      }
+
+      case "deyim": {
+        if (!word) throw new Error("Kelime belirtmelisiniz.");
+        const proverbs = await TDK.getProverbs(word);
+        printResult(proverbs, () => {
+          if (proverbs.length === 0) {
+            console.log("Atasözü/deyim bulunamadı.");
+          } else {
+            proverbs.forEach((p, i) => console.log(`${i + 1}. ${p}`));
+          }
+        });
+        break;
+      }
+
       case "gunun": {
         const wotd = await TDK.getWordOfTheDay();
         printResult(wotd, () => {
@@ -239,7 +275,8 @@ async function run() {
           } else {
             analysis.forEach((a) => {
               if (a.found) {
-                console.log(`${a.word}: ${a.meaning ?? "-"} (${a.origin})`);
+                const rootLabel = a.isInflected && a.root ? ` (kök: ${a.root})` : "";
+                console.log(`${a.word}${rootLabel}: ${a.meaning ?? "-"} (${a.origin})`);
               } else {
                 console.log(`${a.word}: bulunamadı`);
               }

package/src/index.ts

@@ -1,3 +1,4 @@
 export { TDK } from "./tdk";
 export * from "./types";
 export * from "./errors";
+export * from "./morphology";

package/src/morphology.ts

@@ -0,0 +1,214 @@
+/**
+ * Turkish Morphology Engine & Stem Candidate Generator.
+ *
+ * Implements heuristic-based progressive suffix stripping (BFS) with:
+ * 1. Comprehensive Turkish suffix catalogue (inflectional, derivational, composite)
+ * 2. Reverse consonant mutation (ünsüz yumuşaması / sertleşmesi: b->p, c->ç, d->t, ğ->k, g->k)
+ * 3. Reverse vowel drop (ünlü düşmesi: akl->akıl, şehr->şehir, omz->omuz)
+ * 4. Infinitive restoration (-mek / -mak for verbal stems)
+ * 5. Apostrophe stripping for proper nouns (İstanbul'da -> İstanbul)
+ */
+
+export const TURKISH_VOWELS = "aeıioöuü";
+
+export function isVowel(ch: string): boolean {
+  return TURKISH_VOWELS.includes(ch);
+}
+
+/**
+ * Turkish suffixes ordered strictly by descending length so that longer
+ * composite suffixes match before their individual subcomponents.
+ */
+export const TURKISH_SUFFIXES: readonly string[] = [
+  // 9-letter composite suffixes
+  "lerimizden", "larımızdan", "lerinizden", "larınızdan",
+  // 8-letter composite suffixes
+  "lerinin", "larının", "lerinde", "larında", "lerinden", "larından",
+  "leriyle", "larıyla", "lerini", "larını", "lerimize", "larımıza",
+  "lerimizle", "larımızla", "lerinizin", "larınızın", "lerinizde", "larınızda",
+  "dığından", "diğinden", "duğundan", "düğünden", "tığından", "tiğinden", "tuğundan", "tüğünden",
+  // 7-letter composite suffixes
+  "ecektir", "acaktır", "eceğim", "acağım", "eceksin", "acaksın",
+  "eceğiz", "acağız", "lerimiz", "larımız", "leriniz", "larınız",
+  "umuzdan", "ümüzden", "inizden", "ınızdan", "ünüzden",
+  "dığında", "diğinde", "duğunda", "düğünde", "tığında", "tiğinde", "tuğunda", "tüğünde",
+  "masına", "mesine", "ıyorsunuz", "iyorsunuz", "uyorsunuz", "üyorsunuz", "yorsunuz",
+  // 6-letter composite suffixes
+  "iyorsa", "iyorduk", "iyordu", "iyormuş", "ıyorsa", "ıyorduk", "ıyordu", "ıyormuş",
+  "uyorsa", "uyorduk", "uyordu", "uyormuş", "üyorsa", "üyorduk", "üyordu", "üyormuş",
+  "ıyorsun", "iyorsun", "uyorsun", "üyorsun", "ıyorlar", "iyorlar", "uyorlar", "üyorlar",
+  "iyoruz", "ıyoruz", "uyoruz", "üyoruz",
+  "imizin", "ımızın", "umuzun", "ümüzün", "imizde", "ımızda", "umuzda", "ümüzde",
+  "imizden", "ımızdan", "imizle", "ımızla", "umuzla", "ümüzle",
+  "lerdir", "lardır", "muştur", "miştir", "muştur", "müştür",
+  "lerden", "lardan", "lerine", "larına", "leriyle", "larıyla",
+  "seniz", "sanız", "diniz", "dınız", "dunuz", "dünüz", "tiniz", "tınız", "tunuz", "tünüz",
+  "siniz", "sınız", "sunuz", "sünüz",
+  "dıkça", "dikçe", "dukça", "dükçe", "tıkça", "tikçe", "tukça", "tükçe",
+  "ırken", "irken", "urken", "ürken", "arken", "erken",
+  // 5-letter suffixes
+  "lerde", "larda", "lerle", "larla", "lerin", "ların", "lerim", "larım",
+  "dirler", "dırlar", "dürler", "durlar", "tirler", "tırlar", "türler", "turlar",
+  "siniz", "sınız", "sunuz", "sünüz", "yorum", "yorsun", "uyoruz", "yorsunuz", "yorlar",
+  "eceks", "acaks", "eyim", "ayım",
+  "indik", "ındık", "unduk", "ündük", "ildik", "ıldık", "ulduk", "üldük",
+  "meden", "madan", "yınız", "yiniz", "yunuz", "yünüz",
+  // 4-letter suffixes
+  "imiz", "ımız", "umuz", "ümüz", "iniz", "ınız", "unuz", "ünüz",
+  "leri", "ları", "idir", "ıdır", "udur", "üdür", "ecek", "acak",
+  "erek", "arak", "ince", "ınca", "unca", "ünce", "ken",
+  "meli", "malı", "iyor", "ıyor", "uyor", "üyor",
+  "mişti", "mıştı", "muştu", "müştü", "seydi", "saydı",
+  "ydim", "ydım", "ydum", "ydüm", "tiler", "tılar", "diler", "dılar",
+  "ikten", "ıktan", "uktan", "ükten",
+  // 3-letter suffixes
+  "ler", "lar", "den", "dan", "ten", "tan", "dir", "dır", "dur", "dür",
+  "tir", "tır", "tur", "tür", "nin", "nın", "nun", "nün", "yle", "yla",
+  "miş", "mış", "muş", "müş", "dim", "dım", "dum", "düm", "tim", "tım", "tum", "tüm",
+  "din", "dın", "dun", "dün", "tin", "tın", "tun", "tün", "dik", "dık", "duk", "dük",
+  "tik", "tık", "tuk", "tük", "ydi", "ydı", "ydu", "ydü", "yim", "yım", "yum", "yüm",
+  "sin", "sın", "sun", "sün", "siz", "sız", "suz", "süz", "lik", "lık", "luk", "lük",
+  "ici", "ıcı", "ucu", "ücü", "gen", "gan", "ken", "kan",
+  "len", "lan", "leş", "laş", "mek", "mak", "yor",
+  // 2-letter suffixes
+  "de", "da", "te", "ta", "im", "ım", "um", "üm", "in", "ın", "un", "ün",
+  "iz", "ız", "uz", "üz",
+  "si", "sı", "su", "sü", "ye", "ya", "le", "la", "di", "dı", "du", "dü",
+  "ti", "tı", "tu", "tü", "se", "sa", "ce", "ca", "çe", "ça", "me", "ma",
+  "ip", "ıp", "up", "üp", "en", "an", "iş", "ış", "uş", "üş",
+  "li", "lı", "lu", "lü", "ci", "cı", "cu", "cü", "çi", "çı", "çu", "çü",
+  // 1-letter suffixes (vowels / basic case endings)
+  "e", "a", "i", "ı", "u", "ü"
+];
+
+/**
+ * Reverses Turkish consonant softening (ünsüz yumuşaması):
+ * When a root ends with p, ç, t, k, it softens to b, c, d, ğ, g before a vowel.
+ * This restores the hardened dictionary headword form.
+ */
+export function restoreConsonantSoftening(stem: string): string[] {
+  if (stem.length < 2) return [];
+  const last = stem.slice(-1);
+  const base = stem.slice(0, -1);
+  switch (last) {
+    case "b": return [base + "p"];
+    case "c": return [base + "ç"];
+    case "d": return [base + "t"];
+    case "ğ": return [base + "k"];
+    case "g": return [base + "k"];
+    default: return [];
+  }
+}
+
+/**
+ * Reverses Turkish vowel drop (ünlü düşmesi):
+ * In words like akıl->aklım, şehir->şehre, burun->burnu, omuz->omzum,
+ * the narrow vowel in the second syllable drops when receiving a vowel-initial suffix.
+ * This restores the harmonic dropped vowel between the final consonant cluster.
+ */
+export function restoreVowelDrop(stem: string): string[] {
+  if (stem.length < 3) return [];
+  const c1 = stem[stem.length - 2];
+  const c2 = stem[stem.length - 1];
+  if (!isVowel(c1) && !isVowel(c2)) {
+    // Look for the last vowel prior to the cluster
+    const vowelsInBase = stem.slice(0, -2).split("").filter(isVowel);
+    if (vowelsInBase.length > 0) {
+      const lastVowel = vowelsInBase[vowelsInBase.length - 1];
+      let inserted = "i";
+      if ("aı".includes(lastVowel)) inserted = "ı";
+      else if ("ei".includes(lastVowel)) inserted = "i";
+      else if ("ou".includes(lastVowel)) inserted = "u";
+      else if ("öü".includes(lastVowel)) inserted = "ü";
+      return [stem.slice(0, -1) + inserted + c2];
+    }
+  }
+  return [];
+}
+
+/**
+ * Restores verb infinitive headword form (-mek / -mak):
+ * Since TDK registers verbs in their infinitive form (e.g. okumak, gelmek, yazmak),
+ * conjugated verb stems (e.g. oku, gel, yaz) need -mak/-mek appended according to vowel harmony.
+ */
+export function restoreInfinitive(stem: string): string[] {
+  if (stem.length < 2) return [];
+  const vowelsInBase = stem.split("").filter(isVowel);
+  if (vowelsInBase.length === 0) return [];
+  const lastVowel = vowelsInBase[vowelsInBase.length - 1];
+  return "aıou".includes(lastVowel) ? [stem + "mak"] : [stem + "mek"];
+}
+
+/**
+ * Generates candidate roots for a given Turkish word using progressive BFS suffix stripping,
+ * consonant mutation restoration, vowel drop restoration, and infinitive restoration.
+ *
+ * Candidates are sorted so that longer base stems (less aggressive stripping) are checked first,
+ * preventing spurious 2-letter roots from overshadowing genuine headwords.
+ *
+ * @param word The input word to analyze
+ * @param minStemLength Minimum allowed length for candidate stems (default: 2)
+ * @param maxDepth Maximum levels of progressive suffix stripping (default: 4)
+ * @returns Array of unique candidate roots in prioritized order
+ */
+export function getStemCandidates(
+  word: string,
+  minStemLength: number = 2,
+  maxDepth: number = 4
+): string[] {
+  if (!word || word.trim().length === 0) return [];
+
+  const raw = word.trim();
+  const normalized = raw.toLocaleLowerCase("tr-TR");
+
+  const candidatesWithWeight: { candidate: string; baseLength: number }[] = [];
+  const seen = new Set<string>();
+
+  // If proper noun contains apostrophe (e.g. "İstanbul'da", "Ankara'dan"),
+  // the part before the apostrophe is an immediate high-priority candidate.
+  if (raw.includes("'") || raw.includes("’")) {
+    const apostropheStem = normalized.split(/['’]/)[0];
+    if (apostropheStem.length >= minStemLength) {
+      candidatesWithWeight.push({ candidate: apostropheStem, baseLength: apostropheStem.length + 10 });
+      seen.add(apostropheStem);
+    }
+  }
+
+  let frontier = [normalized];
+
+  for (let depth = 0; depth < maxDepth; depth++) {
+    const nextFrontier: string[] = [];
+
+    for (const current of frontier) {
+      for (const suffix of TURKISH_SUFFIXES) {
+        if (current.length - suffix.length >= minStemLength && current.endsWith(suffix)) {
+          const stem = current.slice(0, -suffix.length);
+
+          const hardened = restoreConsonantSoftening(stem);
+          const vowelDropped = restoreVowelDrop(stem);
+          // Infinitives only apply to direct stems or consonant-hardened stems (e.g. gid -> git -> gitmek),
+          // NOT to vowel-dropped nouns (nouns like akıl/omuz/şehir don't take infinitive -mek/-mak).
+          const verbalBases = [stem, ...hardened];
+          const infinitives = verbalBases.flatMap((v) => restoreInfinitive(v));
+          const variants = [stem, ...hardened, ...vowelDropped, ...infinitives];
+
+          for (const variant of variants) {
+            if (!seen.has(variant) && variant !== normalized) {
+              seen.add(variant);
+              nextFrontier.push(variant);
+              candidatesWithWeight.push({ candidate: variant, baseLength: stem.length });
+            }
+          }
+        }
+      }
+    }
+
+    if (nextFrontier.length === 0) break;
+    frontier = nextFrontier;
+  }
+
+  // Sort candidates by baseLength descending (longer stem = higher priority)
+  candidatesWithWeight.sort((a, b) => b.baseLength - a.baseLength);
+
+  return [...new Set(candidatesWithWeight.map((c) => c.candidate))];
+}

package/src/tdk.ts

@@ -2,6 +2,7 @@ import type {
   WordInfo,
   DailyContent,
   SpellCheckResult,
+  StemResult,
   WordOfTheDay,
   DailyPick,
   WordComparison,
@@ -11,6 +12,7 @@ import type {
   WiktionaryEntry,
 } from "./types";
 import { TDKValidationError, TDKNetworkError } from "./errors";
+import { getStemCandidates } from "./morphology";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
@@ -107,6 +109,8 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
   private static wordCache = new Map<string, WordInfo[]>();
   private static dailyContentCache: DailyContent | null = null;
   private static autocompleteCache: string[] = [];
+  private static autocompleteSet: Set<string> = new Set<string>();
+  private static stemCache = new Map<string, string | null>();
 
   /**
    * Enables or disables in-memory caching for API requests.
@@ -125,6 +129,8 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     this.wordCache.clear();
     this.dailyContentCache = null;
     this.autocompleteCache = [];
+    this.autocompleteSet.clear();
+    this.stemCache.clear();
   }
 
   private static delay(ms: number) {
@@ -241,6 +247,18 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     }
   }
 
+  /**
+   * Ensures TDK's ~81k headword list is loaded in memory for fast O(1) set operations.
+   */
+  private static async ensureAutocompleteLoaded(): Promise<void> {
+    if (this.autocompleteCache.length === 0) {
+      this.autocompleteCache = await this.fetchAutocompleteData();
+      this.autocompleteSet = new Set(
+        this.autocompleteCache.map((w) => w.toLocaleLowerCase("tr-TR"))
+      );
+    }
+  }
+
   /**
    * Returns autocomplete suggestions for a given prefix, searched over TDK's
    * full headword list (see `fetchAutocompleteData`). The list is fetched
@@ -250,9 +268,7 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
   public static async getSuggestions(prefix: string): Promise<string[]> {
     if (!prefix || prefix.trim() === "") return [];
 
-    if (this.autocompleteCache.length === 0) {
-      this.autocompleteCache = await this.fetchAutocompleteData();
-    }
+    await this.ensureAutocompleteLoaded();
 
     const cleanPrefix = prefix.trim().toLocaleLowerCase("tr-TR");
     return this.autocompleteCache
@@ -260,6 +276,88 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       .slice(0, 10);
   }
 
+  /**
+   * Checks whether a word exists as a known headword in TDK dictionary.
+   * Checks in-memory autocompleteSet (81k headwords) if loaded, or queries TDK API.
+   */
+  public static async isHeadword(word: string): Promise<boolean> {
+    if (!word || word.trim() === "") return false;
+    const clean = word.trim().toLocaleLowerCase("tr-TR");
+
+    await this.ensureAutocompleteLoaded();
+    if (this.autocompleteSet.size > 0) {
+      return this.autocompleteSet.has(clean);
+    }
+
+    try {
+      const results = await this.getWord(clean);
+      return results.length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Generates candidate roots for a given Turkish word using progressive BFS suffix stripping,
+   * consonant mutation restoration, and vowel drop restoration.
+   */
+  public static getStemCandidates(word: string): string[] {
+    return getStemCandidates(word);
+  }
+
+  /**
+   * Finds the dictionary root (headword) of a word by checking direct existence
+   * and evaluating candidate stems generated by morphological analysis.
+   * Returns the root headword string if found, or null if no match in TDK.
+   */
+  public static async findRoot(word: string): Promise<string | null> {
+    if (!word || word.trim() === "") return null;
+    const clean = word.trim().toLocaleLowerCase("tr-TR");
+
+    if (this.stemCache.has(clean)) {
+      return this.stemCache.get(clean)!;
+    }
+
+    // 1. If the word itself is an exact headword, it is its own root
+    if (await this.isHeadword(clean)) {
+      this.stemCache.set(clean, clean);
+      return clean;
+    }
+
+    // 2. Test morphological stem candidates
+    const candidates = getStemCandidates(clean);
+    for (const candidate of candidates) {
+      if (await this.isHeadword(candidate)) {
+        this.stemCache.set(clean, candidate);
+        return candidate;
+      }
+    }
+
+    this.stemCache.set(clean, null);
+    return null;
+  }
+
+  /**
+   * Performs morphological stemming on a Turkish word.
+   * Returns a StemResult containing the original word, resolved root, and whether it is inflected.
+   */
+  public static async stem(word: string): Promise<StemResult | null> {
+    if (!word || word.trim() === "") return null;
+    const clean = word.trim().toLocaleLowerCase("tr-TR");
+    const root = await this.findRoot(word);
+
+    if (!root) {
+      return null;
+    }
+
+    return {
+      word,
+      root,
+      isInflected: root !== clean,
+      candidates: getStemCandidates(word),
+    };
+  }
+
   /**
    * Returns a list of proverbs and idioms containing the word.
    */
@@ -486,7 +584,21 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       }
     }
 
-    // 3. No exact match in TDK's curated lists: fall back to the closest
+    // 3. Morphology Fallback: Check if the word is an inflected form of a known headword
+    // (e.g., "halılarımızın" -> "halı", "kitabımız" -> "kitap", "çocuğa" -> "çocuk")
+    const root = await this.findRoot(word);
+    if (root) {
+      const cleanWord = word.trim().toLocaleLowerCase("tr-TR");
+      const isInflected = root !== cleanWord;
+      return {
+        isCorrect: true,
+        word,
+        isInflected,
+        root,
+      };
+    }
+
+    // 4. No exact match or morphology root: fall back to the closest
     // headword (by edit distance) across TDK's full ~81k-word list (the same
     // data `getSuggestions()` uses). Restricted to single-token, lowercase
     // headwords so it doesn't suggest compounds/phrases or proper nouns.
@@ -713,20 +825,65 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     });
   }
 
+  /**
+   * Kubbealtı indexes headwords with full classical Turkish orthography,
+   * including letters that a plain-ASCII-ish query tends to drop — most
+   * commonly ü/ö/ç/ğ/ş, but also the circumflex ("düzeltme işareti") used in
+   * Arabic/Persian loanwords like "rüzgâr". A search for "ruzgar" misses
+   * entirely (verified: even "ruzgâr" alone still misses — it's the missing
+   * ü, not the missing â, that actually breaks the match). This generates
+   * single-letter-substitution variants to retry, one substitution per
+   * variant (not combinatorial) — covers the overwhelmingly common case of
+   * one "de-Turkished" letter without an explosion of API calls for words
+   * with several.
+   */
+  private static readonly TURKISH_DEASCII_MAP: Record<string, string[]> = {
+    a: ["â"],
+    i: ["ı", "î"],
+    o: ["ö"],
+    u: ["ü", "û"],
+    c: ["ç"],
+    g: ["ğ"],
+    s: ["ş"],
+  };
+
+  private static generateTurkishVariants(word: string): string[] {
+    const lower = word.trim().toLocaleLowerCase("tr-TR");
+    const variants: string[] = [];
+    for (let i = 0; i < lower.length; i++) {
+      for (const replacement of this.TURKISH_DEASCII_MAP[lower[i]] ?? []) {
+        variants.push(lower.slice(0, i) + replacement + lower.slice(i + 1));
+      }
+    }
+    return variants;
+  }
+
   /**
    * Returns Kubbealtı Lugatı ("Misalli Büyük Türkçe Sözlük") entries for a
    * word, scraped from the site's own data API — undocumented, and Kubbealtı
    * Lugatı is a commercial dictionary product, unlike TDK's or Wiktionary's
    * openly-published data, so use this in line with their terms. `anlam` is
    * raw HTML (rich typography markup); use `getKubbealtiMeanings()` for
-   * plain text. Returns `null` on any fetch/parse failure, `[]` if the word
-   * isn't found.
+   * plain text. Falls back to `generateTurkishVariants()` if the exact query
+   * comes up empty (see its doc comment). Returns `null` on any fetch/parse
+   * failure, `[]` if no variant matches either.
    */
   public static async getKubbealti(word: string): Promise<KubbealtiEntry[] | null> {
     if (!word || word.trim() === "") return null;
+
     const data = await this.fetchKubbealtiJson(`/rest/s/${encodeURIComponent(word.trim())}/`);
     if (!data || !Array.isArray(data.content)) return null;
-    return data.content.map((entry: any) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+    if (data.content.length > 0) {
+      return data.content.map((entry: any) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+    }
+
+    for (const variant of this.generateTurkishVariants(word)) {
+      const variantData = await this.fetchKubbealtiJson(`/rest/s/${encodeURIComponent(variant)}/`);
+      if (variantData && Array.isArray(variantData.content) && variantData.content.length > 0) {
+        return variantData.content.map((entry: any) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+      }
+    }
+    return [];
   }
 
   /**
@@ -777,20 +934,10 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     }
   }
 
-  /**
-   * Returns the Turkish Wiktionary (`tr.wiktionary.org`) entry for a word,
-   * via MediaWiki's official Action API (`action=query&prop=extracts`) — no
-   * scraping involved, this is a stable, documented public API. `sections`
-   * splits the plain-text extract on its `== Heading ==`/`=== Heading ===`
-   * markers (e.g. "Köken", "Söyleniş", "Ad") for convenience; `raw` has the
-   * unsplit text. Returns `null` if the page doesn't exist or the request
-   * fails.
-   */
-  public static async getWiktionary(word: string): Promise<WiktionaryEntry | null> {
-    if (!word || word.trim() === "") return null;
+  private static async fetchWiktionaryEntry(title: string): Promise<WiktionaryEntry | null> {
     try {
       const url = `https://tr.wiktionary.org/w/api.php?action=query&prop=extracts&titles=${encodeURIComponent(
-        word.trim()
+        title
       )}&format=json&explaintext=1&formatversion=2`;
       const response = await fetch(url, { headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" } });
       if (!response.ok) return null;
@@ -814,6 +961,32 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     }
   }
 
+  /**
+   * Returns the Turkish Wiktionary (`tr.wiktionary.org`) entry for a word,
+   * via MediaWiki's official Action API (`action=query&prop=extracts`) — no
+   * scraping involved, this is a stable, documented public API. `sections`
+   * splits the plain-text extract on its `== Heading ==`/`=== Heading ===`
+   * markers (e.g. "Köken", "Söyleniş", "Ad") for convenience; `raw` has the
+   * unsplit text. This wiki has title capitalization turned off
+   * ($wgCapitalLinks=false — common for Wiktionaries, since case is
+   * meaningful for a dictionary: "Türkiye" the country vs. a lowercase
+   * common word), so an exact-case miss retries with the first letter
+   * uppercased (Turkish-locale-aware, so "istanbul" tries "İstanbul", not
+   * "Istanbul") before giving up. Returns `null` if neither is found or the
+   * request fails.
+   */
+  public static async getWiktionary(word: string): Promise<WiktionaryEntry | null> {
+    if (!word || word.trim() === "") return null;
+    const trimmed = word.trim();
+
+    const direct = await this.fetchWiktionaryEntry(trimmed);
+    if (direct) return direct;
+
+    const capitalized = trimmed.charAt(0).toLocaleUpperCase("tr-TR") + trimmed.slice(1);
+    if (capitalized === trimmed) return null;
+    return this.fetchWiktionaryEntry(capitalized);
+  }
+
   /**
    * Convenience filter over `getWiktionary()`: returns just one section's
    * text (e.g. `getWiktionarySection(word, "Köken")` for etymology), matched
@@ -936,13 +1109,30 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
 
     const analyses: WordAnalysis[] = [];
     for (const word of unique) {
-      const results = await this.getWord(word);
-      const found = results.length > 0;
+      let results = await this.getWord(word);
+      let found = results.length > 0;
+      let root: string | undefined;
+      let isInflected: boolean | undefined;
+
+      if (!found) {
+        const resolvedRoot = await this.findRoot(word);
+        if (resolvedRoot) {
+          results = await this.getWord(resolvedRoot);
+          if (results.length > 0) {
+            found = true;
+            root = resolvedRoot;
+            isInflected = true;
+          }
+        }
+      }
+
       analyses.push({
         word,
         found,
         meaning: found ? this.firstMeaning(results) : null,
         origin: found ? results[0].lisan || "Türkçe" : null,
+        root,
+        isInflected,
       });
       await this.delay(200);
     }