> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corgea.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Escaneo de dependencias (CLI)

> Crea inventarios offline, grafos de dependencias, SBOM y comprobaciones de políticas con corgea deps

## Resumen

`corgea deps` crea un inventario offline de dependencias a partir de manifiestos y lockfiles de npm, Python y Java. Permite inspeccionar grafos de dependencias, explicar por qué está presente un paquete, comparar cambios, generar un SBOM CycloneDX y evaluar políticas de dependencias.

`corgea deps` no requiere una cuenta de Corgea, un token ni acceso a la red.

## Inventario

Ejecuta un escaneo de dependencias offline desde la raíz del proyecto:

```bash theme={null}
corgea deps scan
```

Comandos comunes:

```bash theme={null}
corgea deps scan --format human
corgea deps scan --format json
corgea deps scan --format quiet --fail-on high
corgea deps scan --out-format sarif --out-file deps.sarif
corgea deps graph --format json
corgea deps explain lodash --format human
corgea deps diff --base origin/main --format json
corgea deps sbom --format cyclonedx --out bom.json
corgea deps policy init --exist-ok
```

Utiliza `--format human`, `agent`, `json` o `quiet` para controlar la salida de terminal de `scan`, `graph`, `explain`, `diff` y `policy init`. En entornos con agentes detectados, `corgea deps` utiliza de forma predeterminada el formato compacto `agent`; pasa `--format human` para forzar la salida normal.

Para exportar un informe con `corgea deps scan`, utiliza `--out-format table`, `json` o `sarif` y, si lo necesitas, `--out-file`. No combines `--format` y `--out-format` en el mismo comando `deps scan`.

## Política

Inicializa `.corgea/deps.yml`:

```bash theme={null}
corgea deps policy init
```

La política generada controla si los lockfiles son obligatorios, si su ausencia o desactualización provoca un fallo y si se notifican dependencias directas que utilizan comodines, `latest` o rangos semver.

```yaml theme={null}
dependency_policy:
  require_lockfile: true
  fail_on_missing_lockfile: true
  fail_on_stale_lockfile: true
  direct_dependencies:
    fail_on_wildcard: true
    fail_on_latest: true
    warn_on_semver_range: true
```

<h2 id="ci-integration">
  Integración de CI
</h2>

Copia este flujo de trabajo en `.github/workflows/dependencies.yml`.

```yaml theme={null}
name: Dependency inventory
on:
  pull_request:
  push:
    branches: [main]

jobs:
  corgea-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @corgea/cli
      - name: Check dependency policy
        run: corgea deps scan --format quiet --fail-on high
```

Para fallar solo cuando una pull request añade hallazgos nuevos de dependencias de gravedad alta:

```bash theme={null}
corgea deps diff --base origin/main --fail-on-new high --format quiet
```

## Referencia

### Comandos

| Comando                                 | Finalidad                                                                       | Opciones principales                                  |
| --------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `corgea deps scan [PATH]`               | Escanear manifiestos y archivos de bloqueo, crear inventario, evaluar políticas | `--fail-on`, `--format`, `--out-format`, `--out-file` |
| `corgea deps graph [PATH]`              | Imprimir el grafo de dependencias                                               | `--format`                                            |
| `corgea deps explain <PACKAGE> [PATH]`  | Explica por qué hay un paquete presente                                         | `--format`                                            |
| `corgea deps diff --base <BASE> [PATH]` | Comparar un grafo de dependencias con una referencia git                        | `--base`, `--fail-on-new`, `--format`                 |
| `corgea deps sbom [PATH]`               | Generar un SBOM CycloneDX                                                       | `--format`, `--out`                                   |
| `corgea deps policy init [PATH]`        | Crea un archivo inicial de políticas `.corgea/deps.yml`                         | `--exist-ok`, `--format`                              |

### Formatos

| Opción         | Valores                           | Comandos                                          |
| -------------- | --------------------------------- | ------------------------------------------------- |
| `--format`     | `human`, `agent`, `json`, `quiet` | `scan`, `graph`, `explain`, `diff`, `policy init` |
| `--out-format` | `table`, `json`, `sarif`          | `scan` solo                                       |
| `--format`     | `cyclonedx`                       | `sbom` solo                                       |

### Códigos de salida

| Salida | Estado                                                                                                                                        |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **0**  | El comando finalizó sin superar ningún umbral de política                                                                                     |
| **1**  | `deps scan --fail-on` o `deps diff --fail-on-new` encontró hallazgos que cumplían el criterio                                                 |
| **2**  | Argumentos inválidos, formatos no compatibles, valores de severidad incorrectos, paquetes ausentes para `explain`, u otros errores de comando |

### Valores de severidad

`--fail-on` y `--fail-on-new` aceptan `info`, `low`, `medium`, `high` o `critical`.

## Resolución de problemas

### Conflicto de formatos

`deps scan` rechaza comandos que combinan `--format` con `--out-format`.

```text theme={null}
deps failed: --format cannot be used with --out-format; choose one output selector
```

Utiliza `--format` para la salida de terminal y `--out-format` para exportar informes de escaneo.

### Paquete no encontrado

`deps explain` finaliza con el código **2** cuando el paquete no está presente en el grafo de dependencias analizado.

```text theme={null}
deps failed: package not found: package-name
```