geo-ai-search-optimization 2.0.0 → 2.2.0

package/src/index.d.ts

@@ -0,0 +1,492 @@
+// Type declarations for geo-ai-search-optimization
+
+// --- Common types ---
+
+export interface GeoScore {
+  score: number;
+  maxScore: number;
+  checks: Array<{
+    key: string;
+    label: string;
+    passed: boolean;
+    maxPoints: number;
+    pointsAwarded: number;
+  }>;
+}
+
+export interface GeoIssue {
+  severity: string;
+  message: string;
+  field?: string;
+}
+
+// --- Scan ---
+
+export interface ScanSummary {
+  root: string;
+  filesConsidered: number;
+  filesScanned: number;
+  specialFiles: {
+    robotsTxt: string[];
+    sitemap: string[];
+    llmsTxt: string[];
+  };
+  signals: Record<string, { count: number; examples: string[] }>;
+  recommendations: string[];
+}
+
+export function scanProject(rootInput: string, options?: { maxFileSize?: number; maxExamples?: number }): Promise<ScanSummary>;
+export function renderScanMarkdown(summary: ScanSummary): string;
+export function writeScanOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Audit ---
+
+export interface AuditReport {
+  kind: "geo-audit";
+  summary: string;
+  score: number;
+  maxScore: number;
+  scoreLabel: string;
+  areas: Array<{ key: string; title: string; owner: string; issues: string[]; severity: string; status: string; summary: string; recommendation: string }>;
+  groups: { blockers: string[]; highImpactFixes: string[]; supportFixes: string[]; experiments: string[] };
+  actionPlan: Array<{ priority: string; owner: string; area: string; action: string }>;
+  checks: GeoScore["checks"];
+  scanSummary: ScanSummary;
+}
+
+export function auditProject(rootInput: string, options?: { maxFileSize?: number; maxExamples?: number }): Promise<AuditReport>;
+export function renderAuditMarkdown(report: AuditReport): string;
+export function writeAuditOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Page Audit ---
+
+export interface PageAuditReport {
+  kind: "geo-page-audit";
+  input: string;
+  sourceType: "url" | "file";
+  reference: string;
+  fetchStatus: number | null;
+  metadata: { title: string | null; metaDescription: string | null; canonical: string | null };
+  directAnswerCandidate: string | null;
+  headingStats: { totalHeadingCount: number; questionHeadingCount: number };
+  headings: Array<{ level: number; text: string }>;
+  signals: Record<string, { count: number; examples: string[] }>;
+  score: GeoScore;
+  scoreLabel: string;
+  problemAreas: Array<{ area: string; severity: string; issues: string[]; whyItMatters: string }>;
+  recommendedBlocks: string[];
+  rewriteBrief: Record<string, unknown>;
+  summary: string;
+  agentPrompt: string;
+}
+
+export function auditPage(input: string, options?: { maxHeadings?: number }): Promise<PageAuditReport>;
+export function renderPageAuditMarkdown(report: PageAuditReport): string;
+export function writePageAuditOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Full Page Audit ---
+
+export interface FullPageAuditReport {
+  kind: "geo-full-page-audit";
+  input: string;
+  source: string;
+  compositeScore: number;
+  compositeLabel: string;
+  dimensions: Record<string, { score: number; label: string; summary: string }>;
+  platformSummary: Array<{ platform: string; score: number; readiness: string }>;
+  topIssues: Array<{ source: string; severity: string; issue: string }>;
+  recommendations: Array<{ source: string; rec: string }>;
+  errors: Array<{ dimension: string; error: string }>;
+  details: Record<string, unknown>;
+  summary: string;
+}
+
+export function fullPageAudit(input: string, options?: { baseUrl?: string }): Promise<FullPageAuditReport>;
+export function renderFullPageAuditMarkdown(report: FullPageAuditReport): string;
+export function writeFullPageAuditOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Full Audit ---
+
+export interface FullAuditReport {
+  kind: "geo-full-audit";
+  root: string;
+  overallScore: number;
+  overallLabel: string;
+  infraScore: number;
+  pageScore: number | null;
+  scores: { base: number; crawlers: number; llmsValidation: number; pageAverage: number | null };
+  baseAudit: AuditReport;
+  crawlers: CrawlerReport | null;
+  llmsValidation: ValidateLlmsReport | null;
+  samplePages: FullPageAuditReport[];
+  actionPlan: Array<{ priority: string; source: string; action: string; owner: string; area: string }>;
+  errors: Array<{ component: string; error: string }>;
+  summary: string;
+}
+
+export function fullAudit(input: string, options?: { sampleUrls?: string[]; concurrency?: number; maxFileSize?: number }): Promise<FullAuditReport>;
+export function renderFullAuditMarkdown(report: FullAuditReport): string;
+export function writeFullAuditOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Crawlers ---
+
+export interface CrawlerReport {
+  kind: "geo-crawlers";
+  source: string;
+  found: boolean;
+  crawlers: Array<{ crawler: string; owner: string; engine: string; purpose: string; status: string; reason: string; matchedAgent: string | null; blockedPaths: string[] }>;
+  score: number;
+  blocked: string[];
+  partial: string[];
+  summary: string;
+  recommendation: string;
+}
+
+export function analyzeCrawlers(input: string, options?: { strategy?: "open" | "selective" | "block-all" }): Promise<CrawlerReport>;
+export function renderCrawlersMarkdown(report: CrawlerReport): string;
+export function writeCrawlersOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Citability ---
+
+export interface CitabilityReport {
+  kind: "geo-citability";
+  source: string;
+  wordCount: number;
+  sentenceCount: number;
+  score: number;
+  scoreLabel: string;
+  claims: { total: number; factualClaims: number; statClaims: number; claimDensity: number; statDensity: number };
+  entities: { namedEntities: string[]; techTerms: string[]; brands: string[]; entityDensity: number };
+  quotableSentences: Array<{ sentence: string; score: number; wordCount: number }>;
+  structure: { hasList: boolean; hasTable: boolean; hasDefinition: boolean; hasHeading: boolean; headingCount: number; structureScore: number };
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzeCitability(input: string, options?: object): Promise<CitabilityReport>;
+export function renderCitabilityMarkdown(report: CitabilityReport): string;
+export function writeCitabilityOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Validate llms.txt ---
+
+export interface ValidateLlmsReport {
+  kind: "geo-validate-llms";
+  source: string;
+  found: boolean;
+  score: number;
+  scoreLabel: string;
+  parsed: { title: string | null; description: string | null; sectionCount: number; sections: string[]; urlCount: number } | null;
+  issues: GeoIssue[];
+  warnings: GeoIssue[];
+  urlValidation: Array<{ url: string; valid: boolean; https: boolean; warning: string | null }>;
+  recommendations: string[];
+  summary: string;
+}
+
+export function validateLlmsTxt(input: string, options?: object): Promise<ValidateLlmsReport>;
+export function renderValidateLlmsMarkdown(report: ValidateLlmsReport): string;
+export function writeValidateLlmsOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Validate Schema ---
+
+export interface ValidateSchemaReport {
+  kind: "geo-validate-schema";
+  source: string;
+  entityCount: number;
+  types: string[];
+  validations: Array<{ type: string; issues: GeoIssue[]; warnings: GeoIssue[]; enhancements: GeoIssue[] }>;
+  score: number;
+  scoreLabel: string;
+  summary: string;
+}
+
+export function validateSchema(input: string, options?: object): Promise<ValidateSchemaReport>;
+export function renderValidateSchemaMarkdown(report: ValidateSchemaReport): string;
+export function writeValidateSchemaOutput(outputPath: string, content: string): Promise<string>;
+
+// --- E-E-A-T ---
+
+export interface EeatReport {
+  kind: "geo-eeat";
+  source: string;
+  wordCount: number;
+  score: number;
+  scoreLabel: string;
+  dimensions: Record<string, { score: number; signals: Array<{ label: string; count: number; examples: string[] }> }>;
+  authorPresence: string[];
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzeEeat(input: string, options?: object): Promise<EeatReport>;
+export function renderEeatMarkdown(report: EeatReport): string;
+export function writeEeatOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Platform Readiness ---
+
+export interface PlatformReadyReport {
+  kind: "geo-platform-ready";
+  source: string;
+  overallScore: number;
+  overallLabel: string;
+  readyPlatforms: number;
+  totalPlatforms: number;
+  platforms: Array<{ key: string; platform: string; score: number; passed: number; total: number; checks: Array<{ key: string; label: string; passed: boolean }>; readiness: string }>;
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzePlatformReadiness(input: string, options?: object): Promise<PlatformReadyReport>;
+export function renderPlatformReadyMarkdown(report: PlatformReadyReport): string;
+export function writePlatformReadyOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Readability ---
+
+export interface ReadabilityReport {
+  kind: "geo-readability";
+  source: string;
+  wordCount: number;
+  sentenceCount: number;
+  readingTime: number;
+  fleschKincaidGrade: number;
+  gradeLabel: string;
+  fleschReadingEase: number;
+  readingEaseLabel: string;
+  passiveVoice: { passiveCount: number; passiveRatio: number };
+  sentenceLength: { avg: number; min: number; max: number; longCount: number; shortCount: number; distribution: Record<string, number> };
+  score: number;
+  scoreLabel: string;
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzeReadability(input: string, options?: object): Promise<ReadabilityReport>;
+export function renderReadabilityMarkdown(report: ReadabilityReport): string;
+export function writeReadabilityOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Heading Structure ---
+
+export interface HeadingStructureReport {
+  kind: "geo-heading-structure";
+  source: string;
+  headingCount: number;
+  headings: Array<{ level: number; text: string }>;
+  hierarchy: { issues: GeoIssue[]; depth: number; levelDistribution: Record<string, number> };
+  semanticCoverage: { categories: Record<string, boolean>; coverageRatio: number; covered: number; total: number };
+  questionHeadings: { count: number; ratio: number; examples: string[] };
+  score: number;
+  scoreLabel: string;
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzeHeadingStructure(input: string, options?: object): Promise<HeadingStructureReport>;
+export function renderHeadingStructureMarkdown(report: HeadingStructureReport): string;
+export function writeHeadingStructureOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Internal Links ---
+
+export interface InternalLinksReport {
+  kind: "geo-internal-links";
+  source: string;
+  internalLinks: { total: number; unique: number; anchorQuality: number; mostLinked: Array<{ url: string; count: number }>; avgDepth: number; maxDepth: number };
+  externalLinks: { total: number; domains: string[] };
+  anchorAnalysis: { total: number; descriptive: number; generic: number; empty: number; qualityRatio: number; issues: GeoIssue[] };
+  score: number;
+  scoreLabel: string;
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzeInternalLinks(input: string, options?: { baseUrl?: string }): Promise<InternalLinksReport>;
+export function renderInternalLinksMarkdown(report: InternalLinksReport): string;
+export function writeInternalLinksOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Social Meta ---
+
+export interface SocialMetaReport {
+  kind: "geo-social-meta";
+  source: string;
+  openGraph: { found: number; total: number; tags: Array<{ tag: string; label: string; required: boolean; found: boolean; value: string | null; issues: GeoIssue[] }> };
+  twitter: { found: number; total: number; tags: Array<{ tag: string; label: string; required: boolean; found: boolean; value: string | null; issues: GeoIssue[] }> };
+  score: number;
+  scoreLabel: string;
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzeSocialMeta(input: string, options?: object): Promise<SocialMetaReport>;
+export function renderSocialMetaMarkdown(report: SocialMetaReport): string;
+export function writeSocialMetaOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Sitemap ---
+
+export interface SitemapReport {
+  kind: "geo-sitemap";
+  source: string;
+  found: boolean;
+  isIndex?: boolean;
+  entryCount: number;
+  urlStats: { total: number; withLastmod: number; lastmodCoverage: number; freshness: Record<string, number> } | null;
+  validation: { issues: GeoIssue[]; warnings: GeoIssue[] };
+  score: number;
+  scoreLabel: string;
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzeSitemap(input: string, options?: { maxEntries?: number }): Promise<SitemapReport>;
+export function renderSitemapMarkdown(report: SitemapReport): string;
+export function writeSitemapOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Security ---
+
+export interface SecurityReport {
+  kind: "geo-security";
+  source: string;
+  isHttps: boolean;
+  score: number;
+  scoreLabel: string;
+  htmlChecks: Array<{ key: string; label: string; passed: boolean; severity: string; detail?: string }>;
+  securityHeaders: Array<{ header: string; key: string; present: boolean; value: string | null; weight: number; critical: boolean }> | null;
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzeSecurity(input: string, options?: object): Promise<SecurityReport>;
+export function renderSecurityMarkdown(report: SecurityReport): string;
+export function writeSecurityOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Freshness ---
+
+export interface FreshnessReport {
+  kind: "geo-freshness";
+  source: string;
+  datesFound: number;
+  dates: Array<{ raw: string; date: string; source: string; timestamp: number }>;
+  age: { publishedDate: string; modifiedDate: string; publishedAgeDays: number; modifiedAgeDays: number; isStale: boolean; isOld: boolean } | null;
+  freshnessSignals: string[];
+  score: number;
+  scoreLabel: string;
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzeFreshness(input: string, options?: object): Promise<FreshnessReport>;
+export function renderFreshnessMarkdown(report: FreshnessReport): string;
+export function writeFreshnessOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Topics ---
+
+export interface TopicsReport {
+  kind: "geo-topics";
+  source: string;
+  wordCount: number;
+  uniqueTerms: number;
+  keywords: Array<{ term: string; count: number; tfidf: number }>;
+  bigrams: Array<{ term: string; count: number }>;
+  trigrams: Array<{ term: string; count: number }>;
+  headingTopics: string[];
+  topicClusters: Array<{ primary: string; related: string[]; totalFreq: number }>;
+  score: number;
+  scoreLabel: string;
+  recommendations: string[];
+  summary: string;
+}
+
+export function analyzeTopics(input: string, options?: object): Promise<TopicsReport>;
+export function renderTopicsMarkdown(report: TopicsReport): string;
+export function writeTopicsOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Auto-Fix ---
+
+export interface AutoFixReport {
+  kind: "geo-auto-fix";
+  input: string;
+  source: string;
+  auditScore: number;
+  metaTags: Array<{ tag: string; html: string; priority: string; condition?: string }>;
+  ogTags: Array<{ tag: string; html: string }>;
+  jsonLdSchemas: Array<{ type: string; json: string }>;
+  robotsTxt: { label: string; content: string };
+  llmsTxt: { label: string; content: string };
+  headingFix: { label: string; content: string } | null;
+  summary: string;
+}
+
+export function generateAutoFix(input: string, options?: object): Promise<AutoFixReport>;
+export function renderAutoFixMarkdown(report: AutoFixReport): string;
+export function writeAutoFixOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Page Snapshot ---
+
+export function savePageSnapshot(pageAuditResult: FullPageAuditReport, options?: { dataDir?: string }): Promise<{ path: string; key: string; snapshot: object }>;
+export function listPageSnapshots(input: string, options?: { dataDir?: string }): Promise<string[]>;
+export function loadPageSnapshot(filePath: string): Promise<object>;
+
+export interface PageTrendReport {
+  kind: "geo-page-trend";
+  input: string;
+  key: string;
+  snapshotCount: number;
+  snapshots: Array<{ timestamp: string; compositeScore: number }>;
+  trend: { firstDate: string; latestDate: string; firstScore: number; latestScore: number; delta: number; direction: string; dimensionTrends: Record<string, { first: number; latest: number; delta: number; direction: string }> } | null;
+  summary: string;
+}
+
+export function buildPageTrend(input: string, options?: { dataDir?: string; last?: number }): Promise<PageTrendReport>;
+export function renderPageTrendMarkdown(report: PageTrendReport): string;
+export function writePageTrendOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Batch ---
+
+export interface BatchFullPageAuditReport {
+  kind: "geo-batch-full-page-audit";
+  totalUrls: number;
+  successful: number;
+  failed: number;
+  avgScore: number;
+  minScore: number;
+  maxScore: number;
+  dimensionAverages: Record<string, number>;
+  results: FullPageAuditReport[];
+  weakest: FullPageAuditReport[];
+  commonIssues: Array<{ issue: string; count: number; percentage: number }>;
+  errors: Array<{ url: string; error: string }>;
+  summary: string;
+}
+
+export function batchFullPageAudit(urls: string[], options?: { concurrency?: number }): Promise<BatchFullPageAuditReport>;
+export function renderBatchFullPageAuditMarkdown(report: BatchFullPageAuditReport): string;
+export function writeBatchFullPageAuditOutput(outputPath: string, content: string): Promise<string>;
+
+// --- Config ---
+
+export function loadConfig(options?: { configPath?: string; startDir?: string }): Promise<Record<string, unknown>>;
+export function initConfig(options?: { targetDir?: string; siteName?: string; siteUrl?: string; overwrite?: boolean; minScore?: number }): Promise<{ outputPath: string; config: object }>;
+export function mergeConfigWithOptions(config: Record<string, unknown>, cliOptions: Record<string, unknown>): Record<string, unknown>;
+
+// --- Plugins ---
+
+export interface PluginApi {
+  addSignal(name: string, config: { pattern: RegExp | string; label?: string; weight?: number }): void;
+  addCheck(name: string, config: { label?: string; maxPoints?: number; passed: (data: unknown) => boolean }): void;
+  addCommand(name: string, config: { description?: string; handler: (args: string[]) => Promise<void> }): void;
+  addScoreRule(name: string, config: { label?: string; maxPoints?: number; passed: (scan: unknown) => boolean }): void;
+}
+
+export function loadPlugins(pluginPaths: string[], options?: { baseDir?: string }): Promise<{ loaded: Array<{ path: string; name: string }>; errors: Array<{ path: string; error: string }> }>;
+export function getPluginRegistry(): Record<string, unknown>;
+export function getPluginSignals(): Record<string, unknown>;
+export function getPluginChecks(): Record<string, unknown>;
+export function getPluginCommands(): Record<string, unknown>;
+export function resetPluginRegistry(): void;
+
+// --- PDF Report ---
+
+export function generatePdfHtml(data: Record<string, unknown>, options?: { title?: string; date?: string }): string;
+export function writePdfReport(inputPath: string, outputPath?: string, options?: { title?: string }): Promise<{ outputPath: string; title: string }>;
+
+// --- CLI ---
+
+export function runCli(args?: string[]): Promise<void>;

package/src/index.js

@@ -62,3 +62,27 @@ export { buildTrend, renderTrendMarkdown, writeTrendOutput } from "./trend.js";
 export { createSharePack, renderSharePackMarkdown, writeSharePackOutput } from "./share-pack.js";
 export { listBundledSkills, renderBundledSkillsMarkdown } from "./skills.js";
 export { analyzeWebsiteUrl, renderWebsiteOnboardingMarkdown, writeWebsiteOnboardingOutput } from "./url-onboarding.js";
+export { analyzeCrawlers, renderCrawlersMarkdown, writeCrawlersOutput } from "./crawlers.js";
+export { analyzeCitability, renderCitabilityMarkdown, writeCitabilityOutput } from "./citability.js";
+export { validateLlmsTxt, renderValidateLlmsMarkdown, writeValidateLlmsOutput } from "./validate-llms.js";
+export { validateSchema, renderValidateSchemaMarkdown, writeValidateSchemaOutput } from "./validate-schema.js";
+export { analyzeEeat, renderEeatMarkdown, writeEeatOutput } from "./eeat.js";
+export { analyzePlatformReadiness, renderPlatformReadyMarkdown, writePlatformReadyOutput } from "./platform-ready.js";
+export { analyzeReadability, renderReadabilityMarkdown, writeReadabilityOutput } from "./readability.js";
+export { analyzeHeadingStructure, renderHeadingStructureMarkdown, writeHeadingStructureOutput } from "./heading-structure.js";
+export { analyzeInternalLinks, renderInternalLinksMarkdown, writeInternalLinksOutput } from "./internal-links.js";
+export { analyzeSocialMeta, renderSocialMetaMarkdown, writeSocialMetaOutput } from "./social-meta.js";
+export { loadConfig, initConfig, mergeConfigWithOptions } from "./config.js";
+export { loadPlugins, getPluginRegistry, getPluginSignals, getPluginChecks, getPluginCommands, resetPluginRegistry } from "./plugins.js";
+export { generatePdfHtml, writePdfReport } from "./pdf-report.js";
+export { fullPageAudit, renderFullPageAuditMarkdown, writeFullPageAuditOutput } from "./full-page-audit.js";
+export { fullAudit, renderFullAuditMarkdown, writeFullAuditOutput } from "./full-audit.js";
+export { analyzeSitemap, renderSitemapMarkdown, writeSitemapOutput } from "./sitemap.js";
+export { analyzeSecurity, renderSecurityMarkdown, writeSecurityOutput } from "./security.js";
+export { analyzeFreshness, renderFreshnessMarkdown, writeFreshnessOutput } from "./freshness.js";
+export { analyzeTopics, renderTopicsMarkdown, writeTopicsOutput } from "./topics.js";
+export { batchFullPageAudit, renderBatchFullPageAuditMarkdown, writeBatchFullPageAuditOutput } from "./batch-full-page-audit.js";
+export { generateAutoFix, renderAutoFixMarkdown, writeAutoFixOutput } from "./auto-fix.js";
+export { diagnose, renderDiagnoseMarkdown, writeDiagnoseOutput } from "./diagnose.js";
+export { comparePages, renderCompareMarkdown, writeCompareOutput } from "./compare.js";
+export { savePageSnapshot, listPageSnapshots, loadPageSnapshot, buildPageTrend, renderPageTrendMarkdown, writePageTrendOutput } from "./page-snapshot.js";