npm package: @idirdev/depsec
Description: Analyze npm dependencies for known security patterns and outdated packages
Author: idirdev
Latest version: 1.0.0

# depsec

> **[EN]** A CLI tool to audit npm dependencies for known security vulnerabilities and check for outdated packages, wrapping npm audit and npm outdated with a clean summary output.
> **[FR]** Un outil CLI pour auditer les dépendances npm à la recherche de vulnérabilités de sécurité connues et vérifier les paquets obsolètes, en encapsulant npm audit et npm outdated avec une sortie de résumé claire.

---

## Features / Fonctionnalités

**[EN]**
- Run npm security audit and summarize vulnerabilities by severity level
- Severity breakdown: critical, high, moderate, low
- Check for outdated packages and display current vs latest versions
- Parse package-lock.json and dependency tree programmatically
- JSON output mode for integration with dashboards and CI systems
- Exit code 1 when critical or high vulnerabilities are detected

**[FR]**
- Lancer l'audit de sécurité npm et résumer les vulnérabilités par niveau de gravité
- Détail par gravité : critique, élevée, modérée, faible
- Vérifier les paquets obsolètes et afficher les versions actuelles vs les dernières
- Analyser package-lock.json et l'arbre de dépendances par programmation
- Mode de sortie JSON pour l'intégration avec les tableaux de bord et les systèmes CI
- Code de sortie 1 quand des vulnérabilités critiques ou élevées sont détectées

---

## Installation

```bash
npm install -g @idirdev/depsec
```

---

## CLI Usage / Utilisation CLI

```bash
# Audit current directory for vulnerabilities
# Auditer le répertoire courant pour les vulnérabilités
depsec

# Audit a specific project
# Auditer un projet spécifique
depsec /path/to/project

# Output audit summary as JSON
# Sortir le résumé de l'audit en JSON
depsec /path/to/project --json

# Check for outdated packages
# Vérifier les paquets obsolètes
depsec /path/to/project --outdated

# Show help / Afficher l'aide
depsec --help
```

### Example Output / Exemple de sortie

```
$ depsec /path/to/project
Vulnerabilities: 5
  Critical: 1
  High: 2
  Moderate: 2

$ depsec /path/to/project --outdated
express: 4.18.2 -> 4.21.0
dotenv: 16.0.3 -> 16.4.5
jest: 29.5.0 -> 29.7.0
chalk: 5.2.0 -> 5.3.0

$ depsec /path/to/safe-project
Vulnerabilities: 0

$ depsec /path/to/project --json
{
  "total": 5,
  "critical": 1,
  "high": 2,
  "moderate": 2,
  "low": 0
}
```

---

## API (Programmatic) / API (Programmation)

**[EN]** Use depsec as a library to integrate vulnerability checks into your release automation.
**[FR]** Utilisez depsec comme bibliothèque pour intégrer les vérifications de vulnérabilités dans votre automatisation de release.

```javascript
const {
  runNpmAudit,
  parseLockfile,
  getDependencyTree,
  checkOutdated,
  summarizeAudit,
} = require('@idirdev/depsec');

const dir = '/path/to/project';

// Run npm audit and get raw JSON result
// Lancer npm audit et obtenir le résultat JSON brut
const audit = runNpmAudit(dir);

// Get a concise vulnerability summary
// Obtenir un résumé concis des vulnérabilités
const summary = summarizeAudit(audit);
console.log(summary);
// { total: 5, critical: 1, high: 2, moderate: 2, low: 0 }

if (summary.critical > 0 || summary.high > 0) {
  console.error('Critical/high vulnerabilities detected! Blocking release.');
  process.exit(1);
}

// Parse package-lock.json
// Analyser package-lock.json
const lockfile = parseLockfile(dir);
console.log(lockfile.lockfileVersion); // 3

// Get direct dependencies from package.json
// Obtenir les dépendances directes depuis package.json
const tree = getDependencyTree(dir);
console.log(Object.keys(tree.dependencies));    // ['express', 'dotenv', ...]
console.log(Object.keys(tree.devDependencies)); // ['jest', 'eslint', ...]

// Check for outdated packages
// Vérifier les paquets obsolètes
const outdated = checkOutdated(dir);
Object.entries(outdated).forEach(([name, info]) => {
  console.log(`${name}: ${info.current} -> ${info.latest}`);
});
```

### API Reference

| Function | Parameters | Returns |
|----------|-----------|---------|
| `runNpmAudit(dir?)` | project path | `Object` (npm audit JSON) |
| `summarizeAudit(audit)` | audit object | `{total, critical, high, moderate, low}` |
| `parseLockfile(dir?)` | project path | `Object` (parsed lock) |
| `getDependencyTree(dir?)` | project path | `{dependencies, devDependencies}` |
| `checkOutdated(dir?)` | project path | `{[name]: {current, wanted, latest}}` |

---

## License

MIT - idirdev