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

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

Or run directly via npx (no install required):

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

🚀 Quick Start

1️⃣ Initialize a sample config

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

This creates:

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

2️⃣ Edit the YAML config

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

npx @klazapp/typescript-package-scan

4️⃣ View results

Example output:

Matches found (exact versions or any-version rules):
 - [email protected] :: root > [email protected] [Deprecated vulnerable versions]

Packages present but at different versions than listed:
 - [email protected] :: root > [email protected] (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:

{
  "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):

- 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:

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)

{
  "found": [
    { "package": "koa2-swagger-ui", "version": "5.11.2", "path": "root > [email protected]" }
  ],
  "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