@ijonis/geo-lint 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -7,17 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-02-20
+
+### Fixed
+- `--version` flag was hardcoded to `0.1.0` -- now reads dynamically from package.json
+- `--rules` flag crashed without a config file -- now falls back to defaults so users can discover all 92 rules without project setup
+
+### Changed
+- Polished README: 1008 lines → 259 lines with stronger GEO and agentic workflow framing
+- Split reference documentation into 7 dedicated docs/ files (rules, GEO examples, configuration, custom adapters, API, agent integration)
+- Added copy-paste agent prompts for Claude Code, Cursor, Windsurf, and Copilot
+- Updated GitHub repo description, homepage, and topic tags
+
+## [0.1.1] - 2026-02-19
+
 ### Added
-- 28 new GEO rules across 4 categories (total: 35 GEO rules, 81 rules overall)
+- 28 new GEO rules across 4 categories (total: 35 GEO rules, 92 rules overall)
   - **E-E-A-T (8 rules):** source citations, expert quotes, author validation, heading quality, FAQ quality, definition patterns, how-to steps, TL;DR detection
   - **Structure (7 rules):** section length, paragraph length, list presence, citation block bounds, orphaned intros, heading density, structural element ratio
   - **Freshness (7 rules):** stale year references, outdated content, passive voice, sentence length, internal links, comparison tables, inline HTML
   - **RAG Optimization (6 rules):** extraction triggers, section self-containment, vague openings, acronym expansion, statistic context, summary sections
+- 14 content quality rules including readability analysis inspired by Yoast SEO: transition words, consecutive sentence starts, sentence length variety, vocabulary diversity, jargon density
 - `author` field support in ContentItem and MDX adapter
 - 6 new GeoConfig options: `fillerPhrases`, `extractionTriggers`, `acronymAllowlist`, `vagueHeadings`, `genericAuthorNames`, `allowedHtmlTags`
-- New utility module `geo-advanced-analyzer.ts` with 10 analysis functions
-- Extended `geo-analyzer.ts` with 6 new utility functions
-- Comprehensive tests for all 28 new rules (~120 tests)
+- Comprehensive tests for all new rules (~120 tests)
 
 ## [0.1.0] - 2026-02-18
 
@@ -30,4 +43,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - MDX/Markdown content adapter with `gray-matter`
 - CLI with `--format=json`, `--rules`, `--root`, `--config` flags
 
+[0.1.2]: https://github.com/IJONIS/geo-lint/releases/tag/v0.1.2
+[0.1.1]: https://github.com/IJONIS/geo-lint/releases/tag/v0.1.1
 [0.1.0]: https://github.com/IJONIS/geo-lint/releases/tag/v0.1.0

package/README.md

@@ -12,11 +12,13 @@
 
 ## Why this exists
 
-**GEO (Generative Engine Optimization)** is the practice of structuring content so AI search engines cite it -- ChatGPT, Perplexity, Google AI Overviews, Gemini. Traditional SEO gets you into search result lists. GEO gets you **cited in AI-generated answers**. They require different content patterns, and no existing open-source tool checks for GEO.
+I run multiple content-heavy sites and there was no deterministic way to validate whether my content was actually optimized -- not "probably fine," but actually checked against concrete rules. SEO linters exist, but they're either paid SaaS, not automatable, or completely ignore the structural patterns that AI search engines use when deciding what to cite.
 
-`@ijonis/geo-lint` is built for an agentic workflow: your AI agent runs the linter, reads the JSON violations, fixes the content, and re-lints until clean. Every rule ships with a machine-readable `suggestion` and `fixStrategy` that agents consume directly.
+So I built one. **GEO (Generative Engine Optimization)** is the practice of structuring content so it gets cited by ChatGPT, Perplexity, Google AI Overviews, and Gemini. Traditional SEO gets you into search result lists. GEO gets you **cited in AI-generated answers**. Both matter -- and no existing open-source tool checks for GEO.
 
-**92 rules: 35 GEO, 32 SEO, 14 content quality, 8 technical, 3 i18n.** Readability analysis inspired by Yoast SEO. Zero open-source alternatives for the GEO checks.
+The goal was simple: install one tool, point your AI agent at it, and walk away. The agent runs the linter, reads the JSON violations, fixes the content, re-lints until clean -- across an entire site, no manual input. One command, both SEO and GEO validated.
+
+**92 rules: 35 GEO, 32 SEO, 14 content quality, 8 technical, 3 i18n.** Readability analysis inspired by Yoast SEO. We researched the current state of GEO and AEO to make sure the rules reflect what actually gets content cited -- not outdated advice.
 
 ---
 

package/dist/cli.cjs

@@ -448,7 +448,7 @@ function createLinkExtractor(siteUrl) {
 // src/utils/slug-resolver.ts
 var import_node_fs4 = require("fs");
 var import_node_path3 = require("path");
-function extractSlugFromFile(filePath) {
+function extractSlugFromFile(filePath, defaultLocale = "de") {
   try {
     const content = (0, import_node_fs4.readFileSync)(filePath, "utf-8");
     if (!content.startsWith("---")) return null;
@@ -462,7 +462,7 @@ function extractSlugFromFile(filePath) {
     if (draftMatch) return null;
     return {
       slug: slugMatch[1].trim(),
-      locale: localeMatch ? localeMatch[1].trim() : "de"
+      locale: localeMatch ? localeMatch[1].trim() : defaultLocale
     };
   } catch {
     return null;
@@ -491,12 +491,12 @@ function scanRawContentPermalinks(knownSlugs, contentPaths) {
     const contentDir = (0, import_node_path3.join)(projectRoot, pathConfig.dir);
     if (!(0, import_node_fs4.existsSync)(contentDir)) continue;
     const urlPrefix = pathConfig.urlPrefix ?? "/";
+    const defaultLocale = pathConfig.defaultLocale ?? "de";
     for (const file of findFilesInDir(contentDir, ".mdx")) {
-      const meta = extractSlugFromFile(file);
+      const meta = extractSlugFromFile(file, defaultLocale);
       if (!meta) continue;
       let permalink;
-      const defaultLocale = pathConfig.defaultLocale ?? "de";
-      if (meta.locale !== defaultLocale && meta.locale !== "de") {
+      if (meta.locale !== defaultLocale) {
         permalink = `/${meta.locale}${urlPrefix}${meta.slug}`.replace(/\/+/g, "/");
       } else {
         permalink = `${urlPrefix}${meta.slug}`.replace(/\/+/g, "/");
@@ -1221,7 +1221,7 @@ function countSentences(text) {
 }
 
 // src/utils/readability.ts
-function estimateSyllables(word) {
+function estimateSyllables(word, locale = "de") {
   const lower = word.toLowerCase();
   const vowelPattern = /[aeiouyäöü]+/gi;
   const matches = lower.match(vowelPattern);
@@ -1229,17 +1229,21 @@ function estimateSyllables(word) {
     return 1;
   }
   let count = matches.length;
-  if (lower.endsWith("e") && count > 1) {
-    count -= 0.5;
-  }
-  if (word.length > 12) {
-    count = Math.max(count, Math.ceil(word.length / 4));
+  const lang = locale.toLowerCase().slice(0, 2);
+  if (lang === "en") {
+    if (lower.endsWith("e") && count > 1) {
+      count -= 0.5;
+    }
+  } else {
+    if (word.length > 12) {
+      count = Math.max(count, Math.ceil(word.length / 4));
+    }
   }
   return Math.max(1, Math.round(count));
 }
-function countSyllables(text) {
+function countSyllables(text, locale) {
   const words = text.split(/\s+/).filter((word) => word.length > 0).filter((word) => /\w/.test(word));
-  return words.reduce((total, word) => total + estimateSyllables(word), 0);
+  return words.reduce((total, word) => total + estimateSyllables(word, locale), 0);
 }
 function averageWordLength(text) {
   const words = text.split(/\s+/).filter((word) => word.length > 0).filter((word) => /\w/.test(word));
@@ -1247,11 +1251,35 @@ function averageWordLength(text) {
   const totalLength = words.reduce((sum, word) => sum + word.length, 0);
   return totalLength / words.length;
 }
-function calculateReadability(mdxBody) {
+var FLESCH_COEFFICIENTS = {
+  en: { intercept: 206.835, aslWeight: 1.015, aswWeight: 84.6 },
+  de: { intercept: 180, aslWeight: 1, aswWeight: 58.5 }
+};
+var INTERPRETATION_BANDS = {
+  en: [
+    { min: 90, label: "Very easy to read" },
+    { min: 80, label: "Easy to read" },
+    { min: 70, label: "Fairly easy to read" },
+    { min: 60, label: "Standard" },
+    { min: 50, label: "Fairly difficult" },
+    { min: 30, label: "Difficult" },
+    { min: 0, label: "Very difficult" }
+  ],
+  de: [
+    { min: 70, label: "Very easy to read" },
+    { min: 60, label: "Easy to read" },
+    { min: 50, label: "Fairly easy to read" },
+    { min: 40, label: "Standard" },
+    { min: 30, label: "Fairly difficult" },
+    { min: 20, label: "Difficult" },
+    { min: 0, label: "Very difficult" }
+  ]
+};
+function calculateReadability(mdxBody, locale = "de") {
   const plainText = stripMarkdown(mdxBody);
   const wordCount = countWords(mdxBody);
   const sentenceCount = countSentences(mdxBody);
-  const syllableCount = countSyllables(plainText);
+  const syllableCount = countSyllables(plainText, locale);
   if (wordCount === 0 || sentenceCount === 0) {
     return {
       score: 0,
@@ -1264,23 +1292,26 @@ function calculateReadability(mdxBody) {
   const avgSentenceLength = wordCount / sentenceCount;
   const avgSyllablesPerWord = syllableCount / wordCount;
   const avgWordLen = averageWordLength(plainText);
-  const score = Math.round(180 - avgSentenceLength - 58.5 * avgSyllablesPerWord);
+  const lang = locale.toLowerCase().slice(0, 2);
+  const coefficients = FLESCH_COEFFICIENTS[lang] ?? FLESCH_COEFFICIENTS.de;
+  const score = Math.round(
+    coefficients.intercept - coefficients.aslWeight * avgSentenceLength - coefficients.aswWeight * avgSyllablesPerWord
+  );
   const clampedScore = Math.max(0, Math.min(100, score));
   return {
     score: clampedScore,
     avgSentenceLength: Math.round(avgSentenceLength * 10) / 10,
     avgSyllablesPerWord: Math.round(avgSyllablesPerWord * 100) / 100,
     avgWordLength: Math.round(avgWordLen * 10) / 10,
-    interpretation: getInterpretation(clampedScore)
+    interpretation: getInterpretation(clampedScore, locale)
   };
 }
-function getInterpretation(score) {
-  if (score >= 70) return "Very easy to read";
-  if (score >= 60) return "Easy to read";
-  if (score >= 50) return "Fairly easy to read";
-  if (score >= 40) return "Standard";
-  if (score >= 30) return "Fairly difficult";
-  if (score >= 20) return "Difficult";
+function getInterpretation(score, locale = "de") {
+  const lang = locale.toLowerCase().slice(0, 2);
+  const bands = INTERPRETATION_BANDS[lang] ?? INTERPRETATION_BANDS.de;
+  for (const band of bands) {
+    if (score >= band.min) return band.label;
+  }
   return "Very difficult";
 }
 function isReadable(score, threshold) {
@@ -1321,7 +1352,8 @@ var lowReadability = {
       return [];
     }
     const c = context.thresholds ? resolveThresholds(context.thresholds, item.contentType).content : CONTENT_DEFAULTS;
-    const readability = calculateReadability(item.body);
+    const locale = item.locale ?? context.defaultLocale ?? "de";
+    const readability = calculateReadability(item.body, locale);
     if (!isReadable(readability.score, c.minReadabilityScore)) {
       const isExtreme = readability.score < 20;
       const severity = isExtreme ? "error" : "warning";
@@ -13605,9 +13637,9 @@ var DEFAULT_CONFIG2 = {
 function getLocaleConfig(locale) {
   return LOCALE_CONFIGS[locale.toLowerCase()] ?? DEFAULT_CONFIG2;
 }
-function isComplexWord(normalizedWord, originalWord, config, frequencyList) {
+function isComplexWord(normalizedWord, originalWord, config, frequencyList, locale = "en") {
   if (normalizedWord.length <= config.minLength) return false;
-  if (estimateSyllables(normalizedWord) < config.minSyllables) return false;
+  if (estimateSyllables(normalizedWord, locale) < config.minSyllables) return false;
   if (frequencyList?.has(normalizedWord)) return false;
   if (config.skipCapitalized && /^[A-Z]/.test(originalWord)) return false;
   return true;
@@ -13622,7 +13654,7 @@ function analyzeWordComplexity(body, locale = "en") {
   let complexCount = 0;
   for (const original of rawWords) {
     const normalized = original.toLowerCase();
-    if (isComplexWord(normalized, original, config, frequencyList)) {
+    if (isComplexWord(normalized, original, config, frequencyList, locale)) {
       complexCount++;
       complexCounts.set(normalized, (complexCounts.get(normalized) ?? 0) + 1);
     }
@@ -15372,10 +15404,10 @@ var jargonDensity = {
   severity: "warning",
   category: "content",
   fixStrategy: "Replace complex or uncommon words with simpler alternatives",
-  run: (item) => {
+  run: (item, context) => {
     const wordCount = countWords(item.body);
     if (wordCount < QUALITY_MIN_WORDS) return [];
-    const locale = item.locale ?? "en";
+    const locale = item.locale ?? context.defaultLocale ?? "en";
     const analysis = analyzeJargonDensity(item.body, locale);
     if (analysis.density >= JARGON_ERROR_THRESHOLD) {
       const topWords = analysis.topJargonWords.slice(0, 3).map((w) => `"${w.word}" (${w.count}x)`).join(", ");
@@ -15516,10 +15548,10 @@ var lowTransitionWords = {
   severity: "warning",
   category: "content",
   fixStrategy: "Add transition words (however, therefore, for example, in addition) to connect ideas between sentences",
-  run: (item) => {
+  run: (item, context) => {
     const wordCount = countWords(item.body);
     if (wordCount < TRANSITION_MIN_WORDS) return [];
-    const locale = item.locale ?? "en";
+    const locale = item.locale ?? context.defaultLocale ?? "en";
     const analysis = analyzeTransitionWords(item.body, locale);
     if (analysis.totalSentences < 5) return [];
     if (analysis.ratio < TRANSITION_ERROR_THRESHOLD) {
@@ -15550,10 +15582,10 @@ var consecutiveStarts = {
   severity: "warning",
   category: "content",
   fixStrategy: "Vary sentence openings \u2014 use transition words, prepositional phrases, or reversed structures",
-  run: (item) => {
+  run: (item, context) => {
     const wordCount = countWords(item.body);
     if (wordCount < CONSECUTIVE_STARTS_MIN_WORDS) return [];
-    const locale = item.locale ?? "en";
+    const locale = item.locale ?? context.defaultLocale ?? "en";
     const analysis = analyzeSentenceBeginnings(item.body, locale);
     if (analysis.groups.length === 0) return [];
     const worst = analysis.groups.reduce((a, b) => a.count > b.count ? a : b);
@@ -15801,7 +15833,8 @@ async function lint(options = {}) {
     validSlugs: buildSlugRegistry(contentItems, config.staticRoutes, config.contentPaths),
     validImages: buildImageRegistry(config.imageDirectories),
     thresholds: config.thresholds,
-    geoEnabledContentTypes: config.geo.enabledContentTypes ?? ["blog"]
+    geoEnabledContentTypes: config.geo.enabledContentTypes ?? ["blog"],
+    defaultLocale: config.i18n.defaultLocale
   };
   if (isPretty) {
     printProgress(`Found ${context.validSlugs.size} valid URLs, ${context.validImages.size} images`);