@writechoice/mint-scope

CLI para mapear sites de documentação e gerar relatórios de escopo para migração para Mintlify.

O mintscope rastreia páginas de documentação, identifica páginas válidas de docs, detecta sinais de plataforma/framework, cataloga componentes e gera relatórios em texto ou JSON. A CLI agora aceita múltiplas flags --scope-prefix, permitindo restringir o crawl a mais de um prefixo ao mesmo tempo.

Instalação

Instalação global:

npm install -g @writechoice/mint-scope

Instalação local no projeto:

npm install --save-dev @writechoice/mint-scope

Uso local com npx:

npx mintscope scope https://docs.example.com

Configuração Rápida

Análise básica:

mintscope scope https://docs.example.com

Análise com múltiplos prefixos de escopo:

mintscope scope https://www.cockroachlabs.com/docs/ \
  --scope-prefix https://www.cockroachlabs.com/docs/v25.4/ \
  --scope-prefix https://www.cockroachlabs.com/docs/v26.1/

Saída JSON com relatório completo:

mintscope scope https://docs.example.com \
  --format json \
  --output report.json

Descoberta rápida de URLs com crawl superficial:

mintscope sitemap https://docs.example.com --shallow

Comandos CLI

mintscope scope

Analisa uma ou mais URLs de documentação e gera um relatório de escopo com classificação de páginas, métricas de conteúdo e resumo por site.

mintscope scope [options] <urls...>

| Opção | Descrição | Padrão | |--------|-------------|---------| | -c, --concurrency <number> | Máximo de páginas analisadas em paralelo | 20 | | -m, --max-pages <number> | Máximo de páginas analisadas por site (0 = sem limite) | 0 | | -o, --output [path] | Caminho do arquivo de saída | report.txt | | -f, --format <format> | Formato de saída: json ou text | text | | --content-selector <selector> | Seletor CSS da área principal de conteúdo | - | | --scope-prefix <prefix> | Restringe o crawl a prefixos de URL permitidos. Repita a flag para aceitar vários prefixos. Uma URL permanece em escopo quando corresponde a qualquer prefixo configurado. | - | | --auth <credentials> | Credenciais HTTP no formato user:pass | - | | --no-headless | Executa o navegador em modo visível | - | | -v, --verbose | Ativa logs detalhados | false | | -q, --quiet | Minimiza a saída no terminal | false |

mintscope sitemap

Descobre URLs de documentação sem fazer a análise completa de cada página.

mintscope sitemap [options] <urls...>

| Opção | Descrição | Padrão | |--------|-------------|---------| | -c, --concurrency <number> | Máximo de páginas buscadas em paralelo | 100 | | -m, --max-pages <number> | Máximo de páginas buscadas durante a descoberta (0 = sem limite) | 0 | | -o, --output [path] | Caminho do arquivo de saída | - | | -f, --format <format> | Formato de saída: json ou text | text | | --shallow | Usa apenas sitemap, navegação e homepage, sem expansão recursiva | false | | --scope-prefix <prefix> | Restringe a descoberta a prefixos de URL permitidos. Repita a flag para aceitar vários prefixos. Uma URL permanece em escopo quando corresponde a qualquer prefixo configurado. | - | | --auth <credentials> | Credenciais HTTP no formato user:pass | - | | --no-headless | Executa o navegador em modo visível | - | | -v, --verbose | Ativa logs detalhados | false | | -q, --quiet | Minimiza a saída no terminal | false |

mintscope update

Atualiza a CLI instalada globalmente ou a dependência local do projeto.

mintscope update [options]

| Opção | Descrição | Padrão | |--------|-------------|---------| | --local | Instala a nova versão no projeto atual em vez de atualizar globalmente | false | | --to <target> | Dist-tag do npm ou versão explícita para instalar | latest |

Como usar múltiplas flags --scope-prefix

--scope-prefix é uma opção repetível. Cada ocorrência adiciona um prefixo permitido à lista de escopo do crawl.

Comportamento:

• sem --scope-prefix, todo URL descoberto dentro do domínio analisado pode entrar no crawl
• com um único --scope-prefix, o crawl fica restrito a um único prefixo
• com múltiplos --scope-prefix, o crawl aceita URLs que comecem com qualquer um dos prefixos informados
• prefixos vazios são ignorados e prefixos repetidos são deduplicados internamente
• a checagem é feita sobre URLs normalizadas, o que evita diferenças irrelevantes como barra final ou index.html

Prefixo único:

mintscope scope https://www.cockroachlabs.com/docs/ \
  --scope-prefix https://www.cockroachlabs.com/docs/v26.1/

Múltiplos prefixos:

mintscope scope https://www.cockroachlabs.com/docs/ \
  --scope-prefix https://www.cockroachlabs.com/docs/v25.4/ \
  --scope-prefix https://www.cockroachlabs.com/docs/v26.1/

Múltiplos prefixos combinados com saída JSON:

mintscope scope https://www.cockroachlabs.com/docs/ \
  --max-pages 25 \
  --format json \
  --output report.json \
  --scope-prefix https://www.cockroachlabs.com/docs/v25.4/ \
  --scope-prefix https://www.cockroachlabs.com/docs/v26.1/

Descoberta de sitemap com múltiplos prefixos:

mintscope sitemap https://www.cockroachlabs.com/docs/ \
  --shallow \
  --format json \
  --output sitemap.json \
  --scope-prefix https://www.cockroachlabs.com/docs/v25.4/ \
  --scope-prefix https://www.cockroachlabs.com/docs/v26.1/

Campo validatedDocUrls no JSON

Quando você executa mintscope scope --format json, cada item em report.sites inclui validatedDocUrls.

Esse campo contém:

• a lista deduplicada de URLs efetivamente analisadas
• apenas URLs classificadas como páginas válidas de documentação
• URLs ordenadas alfabeticamente para facilitar diff e revisão

Exemplo:

{
  "sites": [
    {
      "url": "https://www.cockroachlabs.com/docs/",
      "label": "www.cockroachlabs.com/docs",
      "totalPages": 3,
      "validatedDocUrls": [
        "https://www.cockroachlabs.com/docs/v25.4/build-a-python-app-with-cockroachdb",
        "https://www.cockroachlabs.com/docs/v25.4/build-a-typescript-app-with-cockroachdb",
        "https://www.cockroachlabs.com/docs/v26.1/build-a-python-app-with-cockroachdb"
      ],
      "categories": [
        {
          "name": "Guides",
          "count": 3
        }
      ],
      "homepage": "https://www.cockroachlabs.com/docs/"
    }
  ]
}

Exemplos de uso real

Crawler com múltiplos prefixos de escopo:

mintscope scope https://www.cockroachlabs.com/docs/ \
  --max-pages 40 \
  --scope-prefix https://www.cockroachlabs.com/docs/v25.4/ \
  --scope-prefix https://www.cockroachlabs.com/docs/v26.1/

Saída JSON com validatedDocUrls populado:

mintscope scope https://www.cockroachlabs.com/docs/ \
  --max-pages 20 \
  --format json \
  --output report.json \
  --scope-prefix https://www.cockroachlabs.com/docs/v25.4/ \
  --scope-prefix https://www.cockroachlabs.com/docs/v26.1/
cat report.json

Comparação entre prefixo único e múltiplos prefixos:

# Apenas uma versão
mintscope sitemap https://www.cockroachlabs.com/docs/ \
  --shallow \
  --scope-prefix https://www.cockroachlabs.com/docs/v26.1/

# Duas versões em uma única execução
mintscope sitemap https://www.cockroachlabs.com/docs/ \
  --shallow \
  --scope-prefix https://www.cockroachlabs.com/docs/v25.4/ \
  --scope-prefix https://www.cockroachlabs.com/docs/v26.1/

Múltiplos sites:

mintscope scope https://docs.example.com https://docs.another.com

Autenticação e logs detalhados:

mintscope scope https://docs.example.com --auth user:pass --verbose

Atualização global da CLI:

mintscope update

Atualização local para uma versão específica:

mintscope update --local --to 0.1.7

Saídas adicionais do relatório

O relatório também inclui um contrato completo de preenchimento rápido de Typeform (Q1–Q20) com:

• identificador e rótulo da pergunta
• valor inferido
• nível de confiança (high, medium, low)
• origem da inferência
• indicador de revisão manual

License

MIT