npm package: @klazapp/typescript-package-scan
Description: Scan your dependency tree for specific packages/versions defined in a YAML list.
Latest version: 0.0.2

# Klazapp TypeScript Package Scan

A **TypeScript-based CLI and library** that scans your project’s dependency tree for **specific npm packages or versions** defined in a simple YAML or JSON configuration.
Ideal for detecting **deprecated**, **vulnerable**, or **disallowed** dependencies — or simply verifying if certain libraries exist in a project.

---

## ⭐ Why use this?

Package ecosystems evolve rapidly. Sometimes teams must:

* Detect **malicious packages** published under trusted names
* Verify that **specific versions** of dependencies are or aren’t installed
* Audit for **license compliance**, **security risk**, or **organizational policy**
* Monitor whether an internal or third-party library is **in use across projects**

**TypeScript Package Scan** provides a lightweight, flexible way to perform those checks — both interactively and in CI.

---

## 🔍 Comparison

| Aspect               | Manual Inspection (`npm ls`, grep) | TypeScript Package Scan |
| -------------------- | ---------------------------------- | ----------------------- |
| **Ease of use**      | Verbose tree dumps                 | Simple YAML config      |
| **Version matching** | Requires manual filtering          | Exact or wildcard match |
| **CI Integration**   | Hard to automate cleanly           | Built-in exit codes     |
| **Report formats**   | None                               | JSON + CSV exports      |
| **Safety**           | No awareness of known bad packages | Customizable scan list  |

---

## ✅ Key Features

* **YAML or JSON config** – declaratively list target packages and optional versions
* **Version-aware scanning** – match specific versions or “any version”
* **Recursive detection** – traverses the entire dependency tree via `npm ls`
* **Clear output** – separates *found*, *different-version*, and *not found* results
* **CSV / JSON reports** – ready for CI pipelines or audits
* **Automatic default location** – `.pkgtools/<package-name>/scan-packages.yaml`
* **Config generator** – `--init` creates a starter config automatically

---

## 📦 Installation

### From npm

```bash
npm i -D @klazapp/typescript-package-scan
```

Or run directly via **npx** (no install required):

```bash
npx @klazapp/typescript-package-scan --help
```

---

## 🚀 Quick Start

### 1️⃣ Initialize a sample config

```bash
npx @klazapp/typescript-package-scan --init
```

This creates:

```
.pkgtools/typescript-package-scan/scan-packages.yaml
```

### 2️⃣ Edit the YAML config

```yaml
packages:
  - name: "koa2-swagger-ui"
    versions: ["5.11.1", "5.11.2"]
    reason: "Deprecated vulnerable versions"
  - name: "ngx-toastr"
    versions: ["19.0.2"]
  - name: "@ctrl/ngx-csv"
    reason: "Check if package exists at all"
```

### 3️⃣ Run the scan

```bash
npx @klazapp/typescript-package-scan
```

### 4️⃣ View results

Example output:

```
Matches found (exact versions or any-version rules):
 - koa2-swagger-ui@5.11.2 :: root > koa2-swagger-ui@5.11.2 [Deprecated vulnerable versions]

Packages present but at different versions than listed:
 - ngx-toastr@19.0.3 :: root > ngx-toastr@19.0.3 (expected 19.0.2)

Not found:
 - @ctrl/ngx-csv (expected (any))
```

---

## 🧰 CLI Options

| Flag                  | Description                                                                       |
| --------------------- | --------------------------------------------------------------------------------- |
| `--list=PATH`         | Custom path to YAML/JSON config (default auto-detected)                           |
| `--manager=NAME`      | Force specific package manager (`npm`, `pnpm`, `yarn`)                            |
| `--json=FILE`         | Export JSON report to given path                                                  |
| `--csv-prefix=PREFIX` | Export CSV reports with prefix (e.g. `reports/scan_*.csv`)                        |
| `--fail-on-found`     | Exit code `1` if any listed packages found                                        |
| `--fail-on-different` | Also fail if versions differ from expected                                        |
| `--init[=yaml]`       | Generate a sample configuration file                                              |
| `--dir=PATH`          | Target folder for generated config (default: `.pkgtools/typescript-package-scan`) |
| `--name=FILENAME`     | Output file name (default: `scan-packages.yaml`)                                  |
| `--force`             | Overwrite existing file during init                                               |
| `--help`              | Display help text                                                                 |

---

## 🧪 Example CI Integration

Add to `package.json` scripts:

```json
{
  "scripts": {
    "scan:init": "typescript-package-scan --init",
    "scan": "typescript-package-scan --fail-on-found --json=reports/scan.json --csv-prefix=reports/scan"
  }
}
```

Then in CI (e.g. GitHub Actions):

```yaml
- name: Scan for disallowed dependencies
  run: npm run scan
```

If matches are found, the process exits with code `1`, making it CI-friendly.

---

## 🗂 Default Folder Structure

```
.pkgtools/
  typescript-package-scan/
    scan-packages.yaml
    scan-results.json
    scan-results_found.csv
    scan-results_notfound.csv
```

This convention is consistent with other future Klazapp tooling.

---

## ⚙️ Use as a Library (optional)

For programmatic usage:

```ts
import { scanPackages } from "@klazapp/typescript-package-scan";

const result = await scanPackages({ listPath: ".pkgtools/typescript-package-scan/scan-packages.yaml" });

console.log(result.found);
```

---

## 🧾 Example Output Files

**JSON report (`scan.json`)**

```json
{
  "found": [
    { "package": "koa2-swagger-ui", "version": "5.11.2", "path": "root > koa2-swagger-ui@5.11.2" }
  ],
  "presentDifferent": [
    { "package": "ngx-toastr", "presentVersion": "19.0.3", "expectedVersions": "19.0.2" }
  ],
  "notFound": [
    { "package": "@ctrl/ngx-csv", "expectedVersions": "(any)" }
  ]
}
```

---

## 🧩 Use Cases

* Detect specific malicious or deprecated packages
* Enforce dependency policy across multiple repositories
* Verify that migration away from a library is complete
* Generate internal dependency audit reports

---

## 🧱 Folder Naming Convention

All Klazapp dev tools share a single hidden root folder:

```
.pkgtools/
  <tool-name>/
    ...
```

Example:

```
.pkgtools/typescript-package-scan/
.pkgtools/guard-kit/
.pkgtools/release-scripts/
```

This keeps all internal tooling self-contained and versioned per project.

---

## 📖 Roadmap

* [ ] Add regex / wildcard support for version patterns
* [ ] Support for nested monorepo workspaces
* [ ] Integrate npm audit results (CVE awareness)
* [ ] Add summary badges for CI dashboards

---

## 📜 License

MIT © Klazapp