Rastreador de Adoção de SDK

Pegue um nome de SDK. Pesquise no GitHub por repositórios públicos que o importam. Pontue cada repositório por sinal de empresa, atividade e indicadores de ruído. Enriqueça repositórios de alto sinal com dados de proprietário e contribuidores. Gere um relatório de adoção ranqueado com contexto de prospecção para adotantes empresariais.

Regra crítica: Todo repositório na saída deve existir na resposta da API de pesquisa de código do GitHub. Todo nome de empresa deve vir do campo company ou name da API de usuário ou organização do GitHub. Todo identificador de contribuidor deve vir da resposta da API de contribuidores do GitHub. Se algum campo estiver vazio na API, escreva "não listado" -- não infira, adivinhe ou extrapole.

Erros Comuns

O agente vai querer...	Por que isso está errado
Executar pesquisa de código sem GITHUB_TOKEN	A pesquisa de código não autenticada atinge um limite secundário de 3 requisições/minuto e falha em qualquer varredura significativa. O GITHUB_TOKEN é obrigatório. Pare no Passo 1 com um erro claro se estiver faltando.
Incluir forks do próprio SDK	Repositórios que bifurcam o SDK são contribuidores ou espelhos, não adotantes. Filtre repositórios onde `fork == true` E o nome do repositório corresponde ao nome do SDK.
Enviar todos os 500 resultados brutos da pesquisa para a IA	A pesquisa de código pode retornar até 500 resultados, a maioria dos quais é ruído. Filtre e pontue localmente primeiro. Envie apenas os 20 principais repositórios de alto sinal para a etapa de análise da IA.
Relatar repositórios de tutorial e exemplo como adotantes	Repositórios com "example", "tutorial", "demo", "learn", "sample", "playground", "starter" no nome ou descrição não são usuários de produção. Marque como tutorial_noise e exclua dos briefs de lead.
Inventar nomes de empresas ou contatos	Todo nome de empresa deve vir do campo `company` ou do nome da organização do GitHub. Todo identificador de contribuidor deve vir da resposta da API de contribuidores. Se um campo estiver vazio, escreva "não listado".
Usar um único padrão de importação para todos os ecossistemas	`require('sdk')` não encontrará usuários Python. Detecte automaticamente o ecossistema a partir do nome do SDK e construa padrões específicos do ecossistema. Pergunte ao usuário se a detecção automática for ambígua.

Passo 1: Verificação de Configuração

if [ -z "$GITHUB_TOKEN" ]; then
  echo "ERROR: GITHUB_TOKEN is required for code search."
  echo "Add a token at github.com/settings/tokens (no scopes needed for public repos)."
  echo "Without it, GitHub code search hits a 3 req/min secondary rate limit and fails."
  exit 1
fi
echo "GITHUB_TOKEN: set"
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
     -H "Accept: application/vnd.github+json" \
     "https://api.github.com/rate_limit" | python3 -c "
import json, sys
d = json.load(sys.stdin)
search = d['resources']['search']
core = d['resources']['core']
print(f'Search rate: {search[\"remaining\"]}/{search[\"limit\"]} remaining')
print(f'Core rate:   {core[\"remaining\"]}/{core[\"limit\"]} remaining')
"

Se o saldo de pesquisa for 0: pare. Informe ao usuário o horário de redefinição do X-RateLimit-Reset.

Passo 2: Coletar Entrada

Colete da conversa:

Nome do SDK (ex.: @company/my-sdk, requests, github.com/org/go-sdk)
Opcional: substituição de ecossistema (npm, python, go, gem) -- detectado automaticamente se não fornecido
Opcional: organização/usuário para excluir dos resultados (os próprios repositórios do proprietário do SDK)
Opcional: string de contexto do produto (usada para personalizar mensagens de prospecção)

Detecção automática de ecossistema:

Começa com @ ou contém -: npm
snake_case sem / ou -: python
Contém github.com/: go
Caso contrário: pergunte ao usuário

Se nenhum nome de SDK for fornecido: Pergunte: "Qual SDK ou biblioteca você gostaria de rastrear? Forneça o nome do pacote como aparece nas declarações de importação (ex.: stripe, @clerk/nextjs, requests)."

python3 << 'PYEOF'
import json, sys, re

sdk_name = "SDK_NAME_HERE"
ecosystem_override = ""  # deixe vazio para detecção automática
exclude_owner = ""       # opcional: nome do proprietário a ser excluído (geralmente o publicador do SDK)
product_context = ""     # opcional: o que seu produto faz

# Detecção automática de ecossistema
if ecosystem_override:
    ecosystem = ecosystem_override
elif sdk_name.startswith("@") or "-" in sdk_name:
    ecosystem = "npm"
elif re.match(r'^[a-z][a-z0-9_]*$', sdk_name):
    ecosystem = "python"
elif "github.com/" in sdk_name:
    ecosystem = "go"
else:
    ecosystem = "generic"

print(f"SDK: {sdk_name}")
print(f"Ecosystem: {ecosystem}")
print(f"Exclude owner: {exclude_owner or '(none)'}")

with open("/tmp/sat-input.json", "w") as f:
    json.dump({
        "sdk_name": sdk_name,
        "ecosystem": ecosystem,
        "exclude_owner": exclude_owner,
        "product_context": product_context
    }, f)
PYEOF

Passo 3: Pesquisar Código no GitHub

Verifique primeiro se há um script autônomo – ele lida com os Passos 3-5 em uma única chamada.

ls scripts/fetch.py 2>/dev/null && echo "script available" || echo "script not found"

Se o script estiver disponível, execute-o e pule para o Passo 6:

python3 scripts/fetch.py "$(python3 -c "import json; d=json.load(open('/tmp/sat-input.json')); print(d['sdk_name'])")" \
  --ecosystem "$(python3 -c "import json; d=json.load(open('/tmp/sat-input.json')); print(d['ecosystem'])")" \
  --exclude "$(python3 -c "import json; d=json.load(open('/tmp/sat-input.json')); print(d.get('exclude_owner',''))")" \
  --output /tmp/sat-script-out.json

Em seguida, carregue no formato de arquivo temporário esperado nos Passos 6-8:

python3 << 'PYEOF'
import json

out = json.load(open("/tmp/sat-script-out.json"))
json.dump(out["raw_results"], open("/tmp/sat-raw-results.json", "w"), indent=2)
json.dump(out["scored"], open("/tmp/sat-scored.json", "w"), indent=2)
json.dump(out["enriched"], open("/tmp/sat-enriched.json", "w"), indent=2)
print(f"Loaded: {len(out['raw_results'])} raw | {len(out['scored'])} scored | {len(out['enriched'])} enriched")
PYEOF

Se o script não estiver disponível, execute o código embutido abaixo.

Construa padrões de importação e pesquise código no GitHub para cada um:

python3 << 'PYEOF'
import json, urllib.request, ssl, time, os
from datetime import datetime, timezone

ctx = ssl._create_unverified_context()
token = os.environ["GITHUB_TOKEN"]
headers = {
    "Accept": "application/vnd.github+json",
    "Authorization": f"Bearer {token}",
    "User-Agent": "sdk-adoption-tracker/1.0"
}

data = json.load(open("/tmp/sat-input.json"))
sdk_name = data["sdk_name"]
ecosystem = data["ecosystem"]

# Construir padrões de consulta por ecossistema
if ecosystem == "npm":
    # Use o nome do SDK sem o prefixo @ para pesquisas simples
    bare = sdk_name.lstrip("@").replace("/", "/")
    queries = [
        f'require("{sdk_name}")',
        f"require('{sdk_name}')",
        f'from "{sdk_name}"',
        f"from '{sdk_name}'",
    ]
elif ecosystem == "python":
    queries = [
        f"import {sdk_name}",
        f"from {sdk_name} import",
        f"from {sdk_name}.",
    ]
elif ecosystem == "go":
    queries = [f'"{sdk_name}"']
else:
    queries = [sdk_name]

print(f"Building queries for {sdk_name} ({ecosystem}):")
for q in queries:
    print(f"  {q}")

seen_repos = {}  # full_name -> first match
search_rate_remaining = 30
flags = []

for i, query in enumerate(queries):
    if search_rate_remaining <= 2:
        flags.append(f"Code search rate limit low ({search_rate_remaining}) -- skipped remaining patterns")
        print(f"  Rate limit low ({search_rate_remaining}), stopping early")
        break

    url = f"https://api.github.com/search/code?q={urllib.parse.quote(query)}&per_page=100"
    req = urllib.request.Request(url, headers=headers)

    try:
        with urllib.request.urlopen(req, timeout=20, context=ctx) as resp:
            search_rate_remaining = int(resp.headers.get("X-RateLimit-Remaining", 10))
            raw = json.loads(resp.read())

        items = raw.get("items", [])
        total = raw.get("total_count", 0)
        print(f"  Pattern '{query}': {total} total, {len(items)} fetched | rate_remaining={search_rate_remaining}")

        for item in items:
            repo = item.get("repository", {})
            full_name = repo.get("full_name", "")
            if full_name and full_name not in seen_repos:
                seen_repos[full_name] = {
                    "full_name": full_name,
                    "name": repo.get("name", ""),
                    "owner_login": repo.get("owner", {}).get("login", ""),
                    "owner_type": repo.get("owner", {}).get("type", ""),
                    "file_path": item.get("path", ""),
                    "matched_pattern": query,
                    "html_url": repo.get("html_url", ""),
                    "description": repo.get("description") or "",
                }

    except urllib.error.HTTPError as e:
        if e.code == 403:
            flags.append(f"Code search rate limit hit on pattern '{query}'")
            print(f"  Rate limit hit (403) on '{query}'")
            break
        else:
            print(f"  HTTP {e.code} on '{query}'")
    except Exception as e:
        print(f"  Error on '{query}': {e}")

    # Respeitar o limite de 10 requisições/minuto da pesquisa de código
    if i < len(queries) - 1:
        time.sleep(6)

results = list(seen_repos.values())
json.dump(results, open("/tmp/sat-raw-results.json", "w"), indent=2)
print(f"\nTotal unique repos found: {len(results)}")
if flags:
    print("Flags:", flags)

import urllib.parse  # garantir importação
PYEOF

Se 0 resultados: Informe ao usuário: "Nenhum repositório encontrado importando {sdk_name}. A indexação da pesquisa de código do GitHub leva de 1 a 4 semanas para pacotes novos. Se o SDK for estabelecido, verifique os padrões de importação em references/import-patterns.md."

Passo 4: Pontuar e Classificar Repositórios

Nenhuma chamada de API. Python puro. Filtrar ruído, calcular pontuação de adoção, classificar cada repositório.

python3 << 'PYEOF'
import json
from datetime import datetime, timezone

data = json.load(open("/tmp/sat-input.json"))
exclude_owner = data.get("exclude_owner", "").lower()
sdk_name = data["sdk_name"].lower().split("/")[-1].replace("@", "")

results = json.load(open("/tmp/sat-raw-results.json"))

TUTORIAL_WORDS = {"example", "tutorial", "demo", "learn", "sample", "starter",
                  "boilerplate", "template", "playground", "test", "course", "workshop"}

scored = []
now = datetime.now(tz=timezone.utc)

for repo in results:
    full_name = repo["full_name"]
    owner_login = repo.get("owner_login", "").lower()
    repo_name = repo.get("name", "").lower()
    description = (repo.get("description") or "").lower()
    owner_type = repo.get("owner_type", "User")

    # Excluir repositórios do próprio proprietário do SDK
    if exclude_owner and owner_login == exclude_owner.lower():
        continue

    # Detectar ruído de tutorial
    name_words = set(repo_name.replace("-", " ").replace("_", " ").split())
    desc_words = set(description.split())
    is_tutorial = bool((name_words | desc_words) & TUTORIAL_WORDS)
    # Também excluir se o nome do repositório for o nome do SDK (provavelmente um fork)
    if repo_name == sdk_name or repo_name.startswith(sdk_name + "-"):
        is_tutorial = True  # tratar como ruído

    # Nível de classificação
    if is_tutorial:
        tier = "tutorial_noise"
    elif owner_type == "Organization":
        tier = "company_org"
    else:
        tier = "solo_dev"  # será atualizado para affiliated_dev no Passo 5 se o campo da empresa for preenchido

    # Pontuação de adoção (preenchida com dados parciais agora, enriquecida no Passo 5)
    score = 0
    if owner_type == "Organization": score += 50
    if not is_tutorial:              score += 20
    # stars, days_since_push, is_fork, is_archived adicionados no Passo 5

    scored.append({
        **repo,
        "tier": tier,
        "is_tutorial": is_tutorial,
        "adoption_score": score,
        "enriched": False
    })

# Ordenar: company_org primeiro, depois por nível
tier_order = {"company_org": 0, "affiliated_dev": 1, "solo_dev": 2, "tutorial_noise": 3}
scored.sort(key=lambda x: (tier_order.get(x["tier"], 9), -x["adoption_score"]))

json.dump(scored, open("/tmp/sat-scored.json", "w"), indent=2)

tiers = {}
for r in scored:
    tiers[r["tier"]] = tiers.get(r["tier"], 0) + 1

print(f"Classification:")
for tier, count in sorted(tiers.items(), key=lambda x: tier_order.get(x[0], 9)):
    print(f"  {tier}: {count}")
print(f"Total: {len(scored)} repos")

non_noise = [r for r in scored if r["tier"] != "tutorial_noise"]
print(f"\nTop repos for enrichment (non-noise): {len(non_noise)}")
for r in non_noise[:5]:
    print(f"  {r['full_name']} ({r['tier']}) -- {r.get('description','')[:60]}")
PYEOF

Se todos os repositórios forem tutorial_noise: Pare. Informe ao usuário: "Todos os repositórios encontrados parecem ser tutoriais ou exemplos. Nenhum adotante de produção detectado no GitHub público. O SDK pode ser muito novo, ou o nome do pacote é genérico o suficiente para que os resultados da pesquisa sejam dominados por exemplos."

Passo 5: Enriquecer Repositórios de Alto Sinal

Busque metadados completos do repositório, perfil do proprietário e principais contribuidores para repositórios sem ruído. Pule repositórios tutorial_noise completamente.

python3 << 'PYEOF'
import json, urllib.request, ssl, os, time
from datetime import datetime, timezone

ctx = ssl._create_unverified_context()
token = os.environ["GITHUB_TOKEN"]
headers = {
    "Accept": "application/vnd.github+json",
    "Authorization": f"Bearer {token}",
    "User-Agent": "sdk-adoption-tracker/1.0"
}

scored = json.load(open("/tmp/sat-scored.json"))
core_remaining = 5000
flags = []

def gh_get(path):
    global core_remaining
    req = urllib.request.Request(f"https://api.github.com{path}", headers=headers)
    try:
        with urllib.request.urlopen(req, timeout=15, context=ctx) as resp:
            remaining = resp.headers.get("X-RateLimit-Remaining")
            if remaining:
                core_remaining = int(remaining)
            return json.loads(resp.read())
    except urllib.error.HTTPError as e:
        if e.code == 404:
            return None
        raise
    except Exception:
        return None

target = [r for r in scored if r["tier"] != "tutorial_noise"]
print(f"Enriching {len(target)} repos (skipping tutorial_noise)...")

enriched = []

for item in target:
    full_name = item["full_name"]
    owner_login = item["owner_login"]
    owner_ty

[...truncado para tradução]

Varnan-Tech/opendirectory

O que é opendirectory?

Perguntar na sua IA favorita

Documentação