geo-checker 0.3.1 → 0.3.2

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { CheerioAPI } from 'cheerio';
 
 type Status = 'pass' | 'warn' | 'fail' | 'skip';
-type Category = 'crawler' | 'structured-data' | 'citation' | 'content';
+type Category = 'crawler' | 'structured-data' | 'citation' | 'content' | 'aeo';
 interface RobotsRuleGroup {
     userAgent: string;
     allow: string[];
@@ -46,6 +46,8 @@ interface AuditContext {
     renderMode: 'static' | 'rendered';
     fetchedAt: string;
     warnings: string[];
+    skillMd: string | null;
+    agentPermissions: unknown | null;
 }
 type Impact = 'critical' | 'high' | 'medium' | 'low';
 type Effort = 'low' | 'medium' | 'high';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { CheerioAPI } from 'cheerio';
 
 type Status = 'pass' | 'warn' | 'fail' | 'skip';
-type Category = 'crawler' | 'structured-data' | 'citation' | 'content';
+type Category = 'crawler' | 'structured-data' | 'citation' | 'content' | 'aeo';
 interface RobotsRuleGroup {
     userAgent: string;
     allow: string[];
@@ -46,6 +46,8 @@ interface AuditContext {
     renderMode: 'static' | 'rendered';
     fetchedAt: string;
     warnings: string[];
+    skillMd: string | null;
+    agentPermissions: unknown | null;
 }
 type Impact = 'critical' | 'high' | 'medium' | 'low';
 type Effort = 'low' | 'medium' | 'high';

package/dist/index.js

@@ -255,10 +255,12 @@ async function buildContext(url, opts = {}) {
       "Site appears to be JS-rendered (sparse body + SPA root element). Re-run with --render for accurate results."
     );
   }
-  const [robotsRaw, llmsRaw, llmsFullRaw] = await Promise.all([
+  const [robotsRaw, llmsRaw, llmsFullRaw, skillMdRaw, agentPermissionsRaw] = await Promise.all([
     fetchText(`${origin}/robots.txt`, opts),
     fetchText(`${origin}/llms.txt`, opts),
-    fetchText(`${origin}/llms-full.txt`, opts)
+    fetchText(`${origin}/llms-full.txt`, opts),
+    fetchText(`${origin}/skill.md`, opts),
+    fetchText(`${origin}/agent-permissions.json`, opts)
   ]);
   let sitemapUrl = null;
   const robots = robotsRaw ? parseRobots(robotsRaw) : null;
@@ -266,6 +268,13 @@ async function buildContext(url, opts = {}) {
   if (!sitemapUrl) sitemapUrl = `${origin}/sitemap.xml`;
   const sitemapRaw = await fetchText(sitemapUrl, opts);
   const sitemap = sitemapRaw ? parseSitemap(sitemapRaw) : null;
+  let agentPermissions = null;
+  if (agentPermissionsRaw && agentPermissionsRaw.trim().length > 0) {
+    try {
+      agentPermissions = JSON.parse(agentPermissionsRaw);
+    } catch {
+    }
+  }
   return {
     url,
     finalUrl,
@@ -280,7 +289,9 @@ async function buildContext(url, opts = {}) {
     jsonLd: extractJsonLd($),
     renderMode,
     fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    warnings
+    warnings,
+    skillMd: skillMdRaw && skillMdRaw.trim().length > 0 ? skillMdRaw : null,
+    agentPermissions
   };
 }
 
@@ -289,10 +300,11 @@ function defineRule(rule) {
   return rule;
 }
 var CATEGORY_WEIGHTS = {
-  crawler: 25,
-  "structured-data": 30,
-  citation: 25,
-  content: 20
+  crawler: 20,
+  "structured-data": 25,
+  citation: 20,
+  content: 15,
+  aeo: 20
 };
 
 // src/engine.ts
@@ -306,7 +318,8 @@ async function runRules(ctx, rules, opts = {}) {
     crawler: { score: 0, weight: weights.crawler, results: [] },
     "structured-data": { score: 0, weight: weights["structured-data"], results: [] },
     citation: { score: 0, weight: weights.citation, results: [] },
-    content: { score: 0, weight: weights.content, results: [] }
+    content: { score: 0, weight: weights.content, results: [] },
+    aeo: { score: 0, weight: weights.aeo, results: [] }
   };
   for (const rule of rules) {
     if (onlySet && !onlySet.has(rule.id) && (!rule.stableId || !onlySet.has(rule.stableId))) continue;
@@ -1896,12 +1909,130 @@ var contentRules = [
   externalCitationsRule
 ];
 
+// src/rules/aeo/skill-md.ts
+var aeoSkillMdRule = defineRule({
+  id: "aeo.skill-md",
+  stableId: "aeo.skill-md",
+  category: "aeo",
+  group: "opportunity",
+  weight: 3,
+  impact: "high",
+  effort: "low",
+  docsUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md#aeoskill-md",
+  title: "skill.md is present",
+  title_ko: "skill.md \uD30C\uC77C \uC874\uC7AC \uC5EC\uBD80",
+  description: "A /skill.md file describes site capabilities so AI agents know what this site can do for them.",
+  run(ctx) {
+    if (ctx.skillMd !== null) {
+      return {
+        status: "pass",
+        score: 1,
+        rationale: "skill.md found at site root.",
+        rationale_ko: "skill.md\uAC00 \uC0AC\uC774\uD2B8 \uB8E8\uD2B8\uC5D0 \uC874\uC7AC\uD569\uB2C8\uB2E4."
+      };
+    }
+    return {
+      status: "warn",
+      score: 0,
+      rationale: "No /skill.md found. Add one to describe your site capabilities to AI agents.",
+      rationale_ko: "/skill.md\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4. AI \uC5D0\uC774\uC804\uD2B8\uAC00 \uC0AC\uC774\uD2B8 \uAE30\uB2A5\uC744 \uD30C\uC545\uD560 \uC218 \uC788\uB3C4\uB85D \uCD94\uAC00\uD558\uC138\uC694.",
+      fixHint: "Create /skill.md listing what services, products, and capabilities this site offers."
+    };
+  }
+});
+
+// src/rules/aeo/agent-permissions.ts
+var aeoAgentPermissionsRule = defineRule({
+  id: "aeo.agent-permissions",
+  stableId: "aeo.agent-permissions",
+  category: "aeo",
+  group: "opportunity",
+  weight: 3,
+  impact: "medium",
+  effort: "low",
+  docsUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md#aeoagent-permissions",
+  title: "agent-permissions.json is present",
+  title_ko: "agent-permissions.json \uD30C\uC77C \uC874\uC7AC \uC5EC\uBD80",
+  description: "Declares explicit read/summarize/cite/train permissions for AI agents.",
+  run(ctx) {
+    if (ctx.agentPermissions !== null) {
+      return {
+        status: "pass",
+        score: 1,
+        rationale: "agent-permissions.json found at site root.",
+        rationale_ko: "agent-permissions.json\uC774 \uC0AC\uC774\uD2B8 \uB8E8\uD2B8\uC5D0 \uC874\uC7AC\uD569\uB2C8\uB2E4.",
+        evidence: ctx.agentPermissions
+      };
+    }
+    return {
+      status: "warn",
+      score: 0,
+      rationale: "No /agent-permissions.json found. Add one to declare AI agent access policy.",
+      rationale_ko: "/agent-permissions.json\uC774 \uC5C6\uC2B5\uB2C8\uB2E4. AI \uC5D0\uC774\uC804\uD2B8 \uC811\uADFC \uC815\uCC45\uC744 \uBA85\uC2DC\uD558\uB824\uBA74 \uCD94\uAC00\uD558\uC138\uC694.",
+      fixHint: "Create /agent-permissions.json with read, summarize, cite, and train permission flags."
+    };
+  }
+});
+
+// src/rules/aeo/token-length.ts
+var THRESHOLD_OPTIMAL = 15e3;
+var THRESHOLD_MAX = 25e3;
+var aeoTokenLengthRule = defineRule({
+  id: "aeo.token-length",
+  stableId: "aeo.token-length",
+  category: "aeo",
+  group: "diagnostic",
+  weight: 4,
+  impact: "medium",
+  effort: "medium",
+  docsUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md#aeotoken-length",
+  title: "Content token length within AI agent limits",
+  title_ko: "\uCF58\uD150\uCE20 \uD1A0\uD070 \uC218 AI \uC5D0\uC774\uC804\uD2B8 \uAD8C\uC7A5 \uBC94\uC704",
+  description: "Pages under 15K tokens are optimal for AI agents (per Addy Osmani's AEO guidance).",
+  run(ctx) {
+    const text = ctx.$("body").text();
+    const tokenEstimate = Math.round(text.length / 3);
+    const evidence = { tokenEstimate, thresholds: { optimal: THRESHOLD_OPTIMAL, max: THRESHOLD_MAX } };
+    if (tokenEstimate <= THRESHOLD_OPTIMAL) {
+      return {
+        status: "pass",
+        score: 1,
+        rationale: `Estimated ~${tokenEstimate.toLocaleString()} tokens \u2014 within optimal range.`,
+        rationale_ko: `\uC608\uC0C1 \uD1A0\uD070 \uC218 ~${tokenEstimate.toLocaleString()} \u2014 \uAD8C\uC7A5 \uBC94\uC704(15K) \uC774\uB0B4\uC785\uB2C8\uB2E4.`,
+        evidence
+      };
+    }
+    if (tokenEstimate <= THRESHOLD_MAX) {
+      return {
+        status: "warn",
+        score: 0.5,
+        rationale: `Estimated ~${tokenEstimate.toLocaleString()} tokens \u2014 exceeds 15K recommendation.`,
+        rationale_ko: `\uC608\uC0C1 \uD1A0\uD070 \uC218 ~${tokenEstimate.toLocaleString()} \u2014 15K \uAD8C\uC7A5\uCE58\uB97C \uCD08\uACFC\uD569\uB2C8\uB2E4.`,
+        fixHint: "Consider splitting content into shorter, focused pages.",
+        evidence
+      };
+    }
+    return {
+      status: "fail",
+      score: 0,
+      rationale: `Estimated ~${tokenEstimate.toLocaleString()} tokens \u2014 exceeds 25K agent processing limit.`,
+      rationale_ko: `\uC608\uC0C1 \uD1A0\uD070 \uC218 ~${tokenEstimate.toLocaleString()} \u2014 AI \uC5D0\uC774\uC804\uD2B8 \uCC98\uB9AC \uD55C\uACC4(25K)\uB97C \uCD08\uACFC\uD569\uB2C8\uB2E4.`,
+      fixHint: "Split this page into multiple focused pages under 15K tokens.",
+      evidence
+    };
+  }
+});
+
+// src/rules/aeo/index.ts
+var aeoRules = [aeoSkillMdRule, aeoAgentPermissionsRule, aeoTokenLengthRule];
+
 // src/rules/index.ts
 var defaultRules = [
   ...crawlerRules,
   ...structuredDataRules,
   ...citationRules,
-  ...contentRules
+  ...contentRules,
+  ...aeoRules
 ];
 
 // src/config.ts
@@ -2097,7 +2228,8 @@ var CATEGORY_LABELS = {
   crawler: "AI Crawler Access",
   "structured-data": "Structured Data",
   citation: "Citation Signals",
-  content: "Content Structure"
+  content: "Content Structure",
+  aeo: "AEO Stack"
 };
 function scoreBadge(score) {
   const color = score >= 85 ? "brightgreen" : score >= 60 ? "yellow" : "red";