PkgDiet

🥗 PkgDiet

Política de dependências para desenvolvimento assistido por IA em JavaScript e TypeScript.
Coloque seu node_modules em uma dieta.

O Problema: Agentes de codificação com IA podem propor pacotes inexistentes, descontinuados, não aprovados ou inadequados. As equipes precisam de uma forma consistente de avaliar essas escolhas antes e depois das mudanças de dependências.

A Solução: PkgDiet é uma proteção determinística de dependências. Ele verifica as dependências propostas em relação à saúde do registro, status de descontinuação e sua política local do projeto antes de serem instaladas, forçando os agentes a migrarem para alternativas modernas.

---

🔄 O Loop de Política em 3 Fases

O PkgDiet garante que uma dependência seja avaliada de forma idêntica em todas as etapas do seu ciclo de vida de desenvolvimento usando um mecanismo central compartilhado (@pkgdiet/core).

1. Política do Repositório: Um único arquivo .pkgdietrc.json determina o que é permitido, alertado ou bloqueado para o seu projeto.
2. Orientação do Agente (MCP): Clientes de IA se conectam ao PkgDiet via Model Context Protocol (npx pkgdiet mcp). Antes de escrever npm install, o agente pergunta ao PkgDiet se um pacote está em conformidade. Se bloqueado, o PkgDiet fornece alternativas modernas selecionadas.
3. Aplicação no Merge (CI): O PkgDiet roda em GitHub Actions (npx pkgdiet ci --base origin/main). Ele compara package.json para isolar novas dependências diretas solicitadas. Se um pacote bloqueado contornou o agente e chegou ao PR, a CI falha e interrompe o merge.

---

🚀 Início Rápido

Inicialize o PkgDiet no seu repositório. Este comando interativo cria sua política .pkgdietrc.json, configura seu fluxo de trabalho de CI no GitHub Actions e configura seus agentes de IA locais (Cursor, Windsurf, Cline) de uma só vez:

npx pkgdiet init

Audite seu projeto existente para ver como suas node_modules atuais se comparam à sua nova política:

npx pkgdiet audit

---

🛠️ Comandos CLI

Usage: pkgdiet [options] [command]

Dependency policy for AI-assisted development — audit, check, and enforce npm dependency rules

Options:
  -v, --version                  output the version number
  -h, --help                     display help for command

Commands:
  audit [options]                Audit existing dependencies for policy, health, size, and unused-package signals
  check [options] <packages...>  Evaluate npm packages against this repository’s dependency policy
  mcp [args...]                  Start the MCP JSON-RPC server over stdio for MCP-compatible AI coding agents
  ci [options]                   Enforce policy for dependency changes introduced by this branch
  alternatives                   Browse the PkgDiet alternatives dataset
  drift [options]                Scan project for dependency health drift over time
  setup                          Create a starter .pkgdietrc.json policy
  agent-setup [options]          Configure PkgDiet for AI coding agents
  init [options]                 Set up PkgDiet in this project — creates policy, CI workflow, and all AI agent configs
  pr [options]                   Generate a reviewer-ready pull request for adding PkgDiet to any GitHub repo
  policy-check [options]         Validate the repository’s .pkgdietrc.json policy

---

⚙️ Configuração (.pkgdietrc.json)

A configuração da política suporta sobreposições de ambiente, listas de bloqueio explícitas e limites rígidos de falha.

{
  "minHealthScore": 60,
  "warnHealthScore": 80,
  "blockDeprecated": true,
  "maxAddedSizeMB": 5.0,
  "failOn": ["BLOCK", "UNKNOWN"],
  
  "blockedPackages": {
    "moment": "Deprecated. Use date-fns instead.",
    "request": "Deprecated. Use native fetch."
  },

  "environments": {
    "ci": {
      "failOn": ["BLOCK", "UNKNOWN", "WARN"]
    }
  },

  "exceptions": {
    "lodash": {
      "allow": ["HEALTH_SCORE_MIN", "PACKAGE_OVERSIZE"],
      "expires": "2027-01-01",
      "reason": "Legacy dependency; migration planned for Q1."
    }
  }
}

Nota: As exceções são estritamente limitadas. Elas não podem contornar PACKAGE_NOT_FOUND (alucinações), timeouts do registro (UNKNOWN) ou entradas explícitas em blockedPackages.

---

🤖 Integração MCP

O PkgDiet atua como um servidor local de Model Context Protocol (MCP).

Quando seu agente de codificação com IA se conecta ao PkgDiet, ele ganha acesso a:

• check_dependency: Avalia um pacote npm em relação à sua política local .pkgdietrc.json e retorna veredictos estruturados de ALLOW, WARN ou BLOCK.
• suggest_alternative: Consulta o conjunto de dados selecionado do PkgDiet para encontrar alternativas modernas, mais leves e mantidas para pacotes bloqueados.

Para configurar seu agente automaticamente, execute:

npx pkgdiet agent-setup --detect

---

🔗 Documentação e Suporte

• Repositório GitHub: om-tajne/pkgdiet
• Reportar um Problema: Rastreador de Problemas
• Licença: MIT