geolint

ESLint para búsqueda con IA: audita el acceso de rastreadores de IA en 51 tokens de bots, llms.txt, datos estructurados y citabilidad. 51 reglas, informe con puntuación, SARIF, GitHub Action.

GitHub

Prueba este MCPPatrocinado

Documentación

geolint

ESLint para búsqueda con IA. Audita tu sitio web para prepararlo para la búsqueda con IA: acceso de rastreadores de IA, llms.txt, datos estructurados y citabilidad.

geolint terminal demo

Inicio rápido en 30 segundos

Sin instalación, sin configuración:

npx @iliasabk/geolint check yoursite.com

geolint obtiene la página, su robots.txt y llms.txt, evalúa 51 tokens de rastreadores de IA conocidos contra tu robots.txt, ejecuta 51 reglas de auditoría e imprime un informe puntuado con una solución concreta para cada hallazgo.

Por qué

Las respuestas de IA son la nueva portada. ChatGPT, Perplexity, Claude, Copilot y Google AI Overviews envían tráfico — o no — según si sus rastreadores pueden obtener y citar tus páginas.
La mayoría de los sitios bloquean o confunden accidentalmente a los rastreadores de IA. Un Disallow: / obsoleto, un noindex sobrante de staging, una página renderizada en el cliente que parece vacía para un bot que no ejecuta JavaScript.
Las herramientas existentes son listas de bloqueo o aplicaciones web solo con puntuación. Te dicen que bloquees todo, o te dan un número sin un camino para mejorarlo. geolint es el linter: hallazgos concretos, soluciones concretas, ejecutable en CI en cada PR.

Qué comprueba

51 reglas en 5 categorías — geolint rules las enumera todas, y docs/rules.md documenta qué comprueba cada regla, por qué importa y cómo corregir las violaciones.

Categoría	Reglas	Ejemplos
Acceso de rastreadores de IA	10	`ai-crawler/search-bots-blocked`, `ai-crawler/wildcard-block-all`, `ai-crawler/user-fetch-bypass`, `ai-crawler/stale-tokens`
llms.txt	10	`llms-txt/missing`, `llms-txt/invalid-structure`, `llms-txt/broken-links`, `llms-txt/relative-links`
Datos estructurados	6	`schema/no-jsonld`, `schema/invalid-jsonld`, `schema/missing-article-fields`
Citabilidad	9	`content/thin-content`, `content/no-h1`, `content/missing-dates`, `content/no-question-headings`
Base técnica	10	`technical/client-rendered`, `technical/https`, `technical/slow-response`, `technical/sitemap-missing`

Cómo se ve un informe

Salida real, auditando el sitio de demostración incluido (examples/demo-site, que bloquea deliberadamente dos bots) — recortado para el ancho:

$ geolint check localhost:4173 --ignore technical/https

  geolint v0.2.1 — AI-search readiness
  http://localhost:4173/
  200 OK · text/html · TTFB 113ms · robots 200 · llms.txt 404

  ██████████████████████████░░░░  86/100  Grade B

  CATEGORIES
    AI Crawler Access     ███████░░░   70  ✗ 2 errors
    llms.txt              █████████░   92  ⚠ 1 warning · 1 hint
    Structured Data       █████████░   88  ⚠ 1 warning · 3 hints
    Citability            ████████░░   82  ⚠ 2 warnings · 3 hints
    Technical Foundation  ██████████  100  ✓ clean

  AI CRAWLER ACCESS — 49/51 allowed · 2 blocked
    OpenAI
      GPTBot                        ✓  training
      OAI-SearchBot                 ✓  search
      ChatGPT-User                  ✓  user-fetch
    Perplexity
      PerplexityBot                 ✗  search
      Perplexity-User               ✓  user-fetch
    Google
      Googlebot                     ✓  search
      Google-Extended               ✓  training
    … 51 tokens total, grouped by vendor …

  FINDINGS
    AI Crawler Access
      ✗ ai-crawler/search-bots-blocked  PerplexityBot is blocked by robots.txt — Perplexity cannot use your pages as AI answer sources
          fix: Remove the Disallow covering PerplexityBot in robots.txt, or add an explicit "Allow: /" for it.
          evidence: Disallow: / (matched by PerplexityBot)
    llms.txt
      ⚠ llms-txt/missing                No llms.txt found
          fix: Create /llms.txt at the site root: an H1 title, a short blockquote summary, and ## sections linking to your key content.
          evidence: http://localhost:4173/llms.txt → HTTP 404

  ────────────────────────────────────────────────────────────────────
  2 errors · 4 warnings · 7 hints · 32/44 checks passed

Cada hallazgo lleva un id de regla, una severidad, la evidencia que geolint coincidió y una solución. Compara dos páginas o dos competidores cara a cara:

geolint check a.com --compare b.com

Comandos

Comando	Qué hace	Banderas clave
`geolint check <url>`	Audita una URL individual	`--format`, `--fail-under`, `--only`/`--ignore`/`--category`, `--compare`, `--baseline`, `--badge`, `--verbose`
`geolint crawl <url>`	Rastrea páginas del mismo origen y audita todo el sitio	`--max-pages`, `--max-depth`, `--concurrency`, `--fail-under`
`geolint init <url>`	Rastrea el sitio y genera un `llms.txt`	`-o`, `--max-pages`
`geolint diff <old.json> <new.json>`	Compara dos informes JSON: delta de puntuación, hallazgos añadidos/resueltos	—
`geolint rules`	Lista las 51 reglas de auditoría	`--category`, `--format table\|json\|markdown`
`geolint bots`	Lista los 51 rastreadores de IA conocidos y el impacto de bloquear cada uno	`--format table\|json`
`geolint mcp`	Ejecuta un servidor MCP en stdio para asistentes de IA	`--timeout`

Referencia completa de banderas: docs/configuration.md.

Ejecútalo en CI

Acción de GitHub

- uses: iliasabk/geolint@v1
  id: geolint
  with:
    url: https://example.com
    fail-under: 80

- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: ${{ steps.geolint.outputs.sarif-file }}

La acción produce salidas de pasos de puntuación/calificación, un informe SARIF para el escaneo de código de GitHub, y un informe markdown para resúmenes de trabajos y comentarios de PR. Recetas completas — carga de SARIF, actualización de un solo comentario de PR, detección de deriva de línea base — en docs/github-action.md.

Cualquier otro CI

npx @iliasabk/geolint check https://example.com --fail-under 80

El código de salida es 1 cuando la puntuación cae por debajo del umbral (o los hallazgos retroceden contra --baseline), 0 en caso contrario — funciona en GitLab CI, CircleCI, scripts npm, ganchos de pre-despliegue.

Muestra tu puntuación como una insignia de README

npx @iliasabk/geolint check https://example.com --badge
# → writes geolint-badge.svg + prints the markdown snippet to paste

Confirma el SVG, o regenera un JSON de endpoint de shields en CI (--badge-endpoint) para una insignia que nunca se vuelve obsoleta.

Formatos de salida

-f pretty (predeterminado) renderiza el informe de terminal anterior. Los formatos de máquina:

-f json — el ScanReport completo: hallazgos, puntuaciones por categoría, matriz de acceso de bots
-f sarif — SARIF 2.1.0, súbelo directamente al escaneo de código de GitHub
-f markdown — tablas listas para comentarios de PR/resúmenes de trabajos
-f html — un informe interactivo autónomo (anillo de puntuación, filtro de hallazgos, matriz de bots) que puedes compartir o alojar en cualquier lugar

Añade -o report.json para escribir en un archivo; stdout permanece limpio para tuberías.

geolint en la web real

El repositorio se usa a sí mismo: un flujo de trabajo nocturno re-audita ocho sitios conocidos y confirma las puntuaciones de vuelta, y el sitio de demostración publica los informes interactivos completos — github.com, anthropic.com, stripe.com y más, regenerados en cada push a main.

API programática

import { scan } from '@iliasabk/geolint';

const report = await scan('https://example.com', {
  ignore: ['technical/https'],
  timeout: 10_000,
});

console.log(report.score, report.grade);          // e.g. 86 'B'
for (const f of report.findings) {
  console.log(f.severity, f.ruleId, f.message, f.fix);
}

scan(url, options) devuelve un ScanReport tipado. También se exportan: el registro de bots (AI_BOTS, botsByPurpose), el registro de reglas (allRules, ruleById), analizadores de robots.txt/llms.txt, generadores de insignias, puntuadores y los cuatro reportadores.

Úsalo desde asistentes de IA (MCP)

geolint mcp habla el Protocolo de Contexto de Modelo sobre stdio — Claude Desktop, Cursor, VS Code y Windsurf pueden auditar sitios, generar llms.txt y comparar URLs como herramientas nativas:

// claude_desktop_config.json / ~/.cursor/mcp.json
{
  "mcpServers": {
    "geolint": {
      "command": "npx",
      "args": ["-y", "@iliasabk/geolint", "mcp"]
    }
  }
}

Cinco herramientas: audit_url, generate_llms_txt, compare_urls, list_rules, list_ai_bots — todas de solo lectura, con salida estructurada y tiempos de espera por llamada. Configuración para cada cliente: docs/mcp.md.

El registro de bots es el punto

geolint bots lista 51 tokens de rastreadores de IA con una evaluación de impacto consciente del propósito — porque "¿debería bloquear este bot?" tiene una respuesta diferente para cada uno:

Propósito	Ejemplos	Si lo bloqueas
`training`	GPTBot, ClaudeBot, CCBot	ausente de los datos de entrenamiento futuros
`search`	OAI-SearchBot, PerplexityBot, Claude-SearchBot	invisible en las respuestas de IA ahora
`user-fetch`	ChatGPT-User, Claude-User	invisible en las respuestas de IA ahora
`mixed`	Bytespider, Amazonbot, Diffbot	ambos

Y dos matices que otras herramientas pasan por alto:

Algunos buscadores ignoran robots.txt. OpenAI, Perplexity y Meta documentan que sus buscadores activados por usuario (ChatGPT-User, Perplexity-User, Meta-ExternalFetcher) pueden no respetar robots.txt. ai-crawler/user-fetch-bypass te dice cuándo un Disallow no funcionará — aplica en la capa de WAF/auth en su lugar.
Tokens obsoletos. anthropic-ai, Claude-Web, FacebookBot están retirados. ai-crawler/stale-tokens los marca y nombra el token de reemplazo — una regla de User-agent: anthropic-ai no hace nada hoy.

Los tokens solo de control como Google-Extended y Applebot-Extended nunca buscan en absoluto — solo establecen una preferencia — y geolint los trata en consecuencia.

De qué es honesto geolint

llms.txt es una propuesta, no un estándar. Ningún proveedor importante de IA se ha comprometido a leerlo — por lo que los hallazgos de llms-txt/* se ponderan como advertencias y sugerencias, no errores. geolint aún lo comprueba (y geolint init lo genera) porque la adopción está creciendo y el costo es un archivo.
Correlación ≠ causalidad. Las reglas de citabilidad se basan en investigación GEO publicada (citas/estadísticas/referencias elevan mediblemente la cuota de respuesta; los rastreadores de IA que no son Googlebot y Applebot no ejecutan JavaScript), pero señales como encabezados en forma de pregunta son sugerencias, no hechos — son de severidad info y geolint lo dice.
Cada regla muestra su razonamiento. docs/rules.md documenta por qué existe cada regla; las fuentes de investigación están en docs/research-notes.md, incluyendo los documentos de proveedores detrás de la postura de robots.txt de cada bot.

Comparado con las alternativas

	Registro de bots consciente del propósito	Postura de robots.txt por proveedor	Se ejecuta en CI	Solución por hallazgo	Genera llms.txt	Gratis / OSS
geolint	✅	✅	✅	✅	✅	✅
Listas de bloqueo estilo ai.robots.txt	❌	❌	n/a	❌	❌	✅
Habilidades / paquetes de prompts de optimizador GEO	❌	❌	❌	❌	❌	varía
Validadores de llms.txt	❌	❌	algunos	parcial	algunos	✅
Aplicaciones web de auditoría GEO alojadas	parcial	❌	❌	parcial	❌	❌

Detalles y el razonamiento detrás de cada columna: docs/comparison.md. geolint también incluye un servidor MCP, una insignia de puntuación y líneas base de regresión.

Hoja de ruta

Planeado para v0.4+:

geolint watch — re-auditar en despliegues/cambios de archivos
API de reglas personalizadas para comprobaciones específicas del proyecto
Cobertura de esquema más profunda (más validadores de @type)
Fórmula de Homebrew
Localización de informes más allá del inglés

Contribuir

Los problemas y PRs son bienvenidos — ver CONTRIBUTING.md. Las nuevas reglas son la mejor contribución: cada una necesita un check(ctx), hallazgos con fix, una prueba y una entrada de documentación.

Licencia

MIT · registro de cambios · seguridad

Si geolint ayudó, una ⭐ ayuda a otros a encontrarlo.