geolint

ESLint para busca por IA — audita o acesso de rastreadores de IA em 51 tokens de bot, llms.txt, dados estruturados e citabilidade. 51 regras, relatório com pontuação, SARIF, GitHub Action.

GitHubExperimente este MCPPatrocinado

Documentação

geolint

ESLint para busca por IA. Audite seu site para prontidão para IA — acesso de crawlers de IA, llms.txt, dados estruturados e citabilidade.

geolint terminal demo

Início rápido em 30 segundos

Sem instalação, sem configuração:

npx @iliasabk/geolint check yoursite.com

geolint busca a página, seu robots.txt e llms.txt, avalia 51 tokens conhecidos de crawlers de IA contra seu robots.txt, executa 51 regras de auditoria e imprime um relatório pontuado com uma correção concreta para cada achado.

Por quê

Respostas de IA são a nova primeira página. ChatGPT, Perplexity, Claude, Copilot e Google AI Overviews enviam tráfego — ou não — com base em se seus crawlers conseguem buscar e citar suas páginas.
A maioria dos sites bloqueia ou confunde crawlers de IA acidentalmente. Um Disallow: / desatualizado, um noindex deixado do staging, uma página renderizada no cliente que parece vazia para um bot que não executa JavaScript.
Ferramentas existentes são listas de bloqueio ou aplicativos web apenas com pontuação. Elas dizem para bloquear tudo, ou dão um número sem um caminho para melhorá-lo. geolint é o linter: achados concretos, correções concretas, executável em CI em cada PR.

O que ele verifica

51 regras em 5 categorias — geolint rules lista todas, e docs/rules.md documenta o que cada regra verifica, por que importa e como corrigir violações.

Categoria	Regras	Exemplos
Acesso de Crawler 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`
Dados Estruturados	6	`schema/no-jsonld`, `schema/invalid-jsonld`, `schema/missing-article-fields`
Citabilidade	9	`content/thin-content`, `content/no-h1`, `content/missing-dates`, `content/no-question-headings`
Fundação Técnica	10	`technical/client-rendered`, `technical/https`, `technical/slow-response`, `technical/sitemap-missing`

Como é um relatório

Saída real, auditando o site de demonstração incluído (examples/demo-site, que deliberadamente bloqueia dois bots) — reduzido para largura:

$ 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 achado carrega um ID de regra, uma severidade, a evidência que o geolint encontrou e uma correção. Compare duas páginas ou dois concorrentes lado a lado:

geolint check a.com --compare b.com

Comandos

Comando	O que faz	Principais flags
`geolint check <url>`	Audita uma única URL	`--format`, `--fail-under`, `--only`/`--ignore`/`--category`, `--compare`, `--baseline`, `--badge`, `--verbose`
`geolint crawl <url>`	Rastreia páginas de mesma origem e audita o site inteiro	`--max-pages`, `--max-depth`, `--concurrency`, `--fail-under`
`geolint init <url>`	Rastreia o site e gera um `llms.txt`	`-o`, `--max-pages`
`geolint diff <old.json> <new.json>`	Compara dois relatórios JSON: delta de pontuação, achados adicionados/resolvidos	—
`geolint rules`	Lista as 51 regras de auditoria	`--category`, `--format table\|json\|markdown`
`geolint bots`	Lista os 51 crawlers de IA conhecidos e o impacto de bloquear cada um	`--format table\|json`
`geolint mcp`	Executa um servidor MCP em stdio para assistentes de IA	`--timeout`

Referência completa de flags: docs/configuration.md.

Execute no CI

GitHub Action

- 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 }}

A action produz saídas de etapa de pontuação/nota, um relatório SARIF para varredura de código do GitHub e um relatório em markdown para resumos de jobs e comentários em PRs. Receitas completas — upload de SARIF, atualização de um único comentário em PR, detecção de desvio de baseline — em docs/github-action.md.

Qualquer outro CI

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

O código de saída é 1 quando a pontuação cai abaixo do limite (ou os achados regridem em relação a --baseline), 0 caso contrário — funciona em GitLab CI, CircleCI, scripts npm, hooks de pré-deploy.

Mostre sua pontuação como um badge no README

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

Faça commit do SVG, ou regenere um JSON de endpoint de shields no CI (--badge-endpoint) para um badge que nunca fica desatualizado.

Formatos de saída

-f pretty (padrão) renderiza o relatório de terminal acima. Os formatos de máquina:

-f json — o ScanReport completo: achados, pontuações por categoria, matriz de acesso de bots
-f sarif — SARIF 2.1.0, envie direto para a varredura de código do GitHub
-f markdown — tabelas prontas para comentários em PR/resumos de jobs
-f html — um relatório interativo autônomo (anel de pontuação, filtro de achados, matriz de bots) que você pode compartilhar ou hospedar em qualquer lugar

Adicione -o report.json para escrever em um arquivo; o stdout permanece limpo para pipes.

geolint na web real

O repositório usa a si mesmo: um workflow noturno re-audita oito sites conhecidos e faz commit das pontuações de volta, e o site de demonstração publica os relatórios interativos completos — github.com, anthropic.com, stripe.com e mais, regenerados a cada push para 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) retorna um ScanReport tipado. Também exportado: o registro de bots (AI_BOTS, botsByPurpose), o registro de regras (allRules, ruleById), parsers de robots.txt/llms.txt, geradores de badges, pontuadores e todos os quatro relatores.

Use com assistentes de IA (MCP)

geolint mcp fala o Model Context Protocol via stdio — Claude Desktop, Cursor, VS Code e Windsurf podem auditar sites, gerar llms.txt e comparar URLs como ferramentas nativas:

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

Cinco ferramentas: audit_url, generate_llms_txt, compare_urls, list_rules, list_ai_bots — todas somente leitura, com saída estruturada e timeouts por chamada. Configuração para cada cliente: docs/mcp.md.

O registro de bots é o ponto central

geolint bots lista 51 tokens de crawlers de IA com uma avaliação de impacto consciente do propósito — porque "devo bloquear este bot?" tem uma resposta diferente para cada um:

Propósito	Exemplos	Se você bloquear
`training`	GPTBot, ClaudeBot, CCBot	ausente dos dados de treinamento futuros
`search`	OAI-SearchBot, PerplexityBot, Claude-SearchBot	invisível nas respostas de IA agora
`user-fetch`	ChatGPT-User, Claude-User	invisível nas respostas de IA agora
`mixed`	Bytespider, Amazonbot, Diffbot	ambos

E duas nuances que outras ferramentas ignoram:

Alguns buscadores ignoram robots.txt. OpenAI, Perplexity e Meta documentam que seus buscadores acionados por usuário (ChatGPT-User, Perplexity-User, Meta-ExternalFetcher) podem não honrar robots.txt. ai-crawler/user-fetch-bypass informa quando um Disallow não funcionará — aplique na camada de WAF/auth em vez disso.
Tokens desatualizados. anthropic-ai, Claude-Web, FacebookBot estão aposentados. ai-crawler/stale-tokens os sinaliza e nomeia o token substituto — uma regra de User-agent: anthropic-ai não faz nada hoje.

Tokens somente de controle como Google-Extended e Applebot-Extended nunca buscam nada — eles apenas definem uma preferência — e o geolint os trata de acordo.

Sobre o que o geolint é honesto

llms.txt é uma proposta, não um padrão. Nenhum grande fornecedor de IA se comprometeu a lê-lo — então os achados de llms-txt/* são ponderados como avisos e dicas, não erros. O geolint ainda o verifica (e geolint init o gera) porque a adoção está crescendo e o custo é um arquivo.
Correlação ≠ causalidade. As regras de citabilidade são baseadas em pesquisas publicadas de GEO (citações/estatísticas/referências aumentam mensuravelmente a participação de resposta; crawlers de IA além de Googlebot e Applebot não executam JavaScript), mas sinais como títulos em formato de pergunta são dicas, não fatos — eles têm severidade info e o geolint diz isso.
Cada regra mostra seu raciocínio. docs/rules.md documenta por que cada regra existe; as fontes de pesquisa estão em docs/research-notes.md, incluindo a documentação dos fornecedores por trás da postura de robots.txt de cada bot.

Comparado às alternativas

	Registro de bots consciente do propósito	Postura de robots.txt por fornecedor	Executa em CI	Correção por achado	Gera llms.txt	Gratuito / OSS
geolint	✅	✅	✅	✅	✅	✅
Listas de bloqueio estilo ai.robots.txt	❌	❌	n/a	❌	❌	✅
Skills de otimizador GEO / pacotes de prompt	❌	❌	❌	❌	❌	varia
Validadores de llms.txt	❌	❌	alguns	parcial	alguns	✅
Aplicativos web hospedados de auditoria GEO	parcial	❌	❌	parcial	❌	❌

Detalhes e o raciocínio por trás de cada coluna: docs/comparison.md. O geolint também inclui um servidor MCP, um badge de pontuação e baselines de regressão.

Roadmap

Planejado para v0.4+:

geolint watch — re-auditoria em deploys/alterações de arquivos
API de regras personalizadas para verificações específicas de projeto
Cobertura de schema mais profunda (mais validadores de @type)
Fórmula Homebrew
Localização de relatórios além do inglês

Contribuindo

Issues e PRs são bem-vindos — veja CONTRIBUTING.md. Novas regras são a melhor contribuição: cada uma precisa de um check(ctx), achados com fix, um teste e uma entrada na documentação.

Licença

MIT · changelog · segurança

Se o geolint ajudou, uma ⭐ ajuda outros a encontrá-lo.