ts-dependency-analysis

A CLI and library tool for analysing dependencies to specific entities (interfaces, types, classes, enums, etc.) defined in target TypeScript files. This tool helps you understand how and where your API surface or generated code is referenced throughout your codebase.

Features

• Configurable Target Files: Specify which files/entities to analyze using glob patterns.
• Reference Analysis: Find all references to exported interfaces, types, classes, enums, properties, and methods in your target files.
• Exclusion Support: Exclude files (e.g., tests) from analysis using glob patterns.
• CLI and Programmatic API: Use as a command-line tool or as a library in your own scripts.
• JSON Output: Get machine-readable output for further processing.

Installation

npm install -g ts-dependency-analysis

Or as a dev dependency:

npm install --save-dev ts-dependency-analysis

Usage

CLI

ts-dependency-analysis --tsconfig=./tsconfig.json --output=./analysis.json [--targets=pattern] [--exclude=pattern]

Options

• --tsconfig (required): Path to the TypeScript configuration file.
• --output (required): Path to the output file (JSON).
• --targets (optional, repeatable): Glob patterns for target files (default: generated/api files).
• --exclude (optional, repeatable): Glob patterns to exclude files (default: **/*.spec.ts).
• --help (optional): Show help message.

Example

ts-dependency-analysis --tsconfig=./tsconfig.json --output=./deps.json --targets=src/api.generated.ts --exclude=**/test/**

Programmatic API

You can use the analysis in your own scripts:

import { analyseDependencies } from "ts-dependency-analysis";

const dependencies = analyseDependencies(
  "./tsconfig.json",
  ["src/api.generated.ts"], // target globs
  ["**/*.spec.ts"] // exclude globs
);
console.log(dependencies);

Output Format

The output is a JSON array of dependency objects:

[
  {
    "name": "MyInterface",
    "kind": "interface",
    "parents": [],
    "originPath": "src/api.generated.ts",
    "references": [
      {
        "filePath": "src/consumer.ts",
        "line": 42,
        "proof": "...code excerpt..."
      }
    ]
  }
  // ...more dependencies
]

• name: Name of the exported entity.
• kind: Type of entity (interface, class, type, enum, etc.).
• parents: Parent namespaces/types (for nested members).
• originPath: File where the entity is defined.
• references: List of references with file, line, and code excerpt.

Typical Use Cases

• API Surface Analysis: Find all usages of your generated API types.
• Refactoring: Identify where breaking changes will have impact.
• Documentation: Generate reports of how and where your types are used.

Requirements

• Node.js >= 16
• TypeScript >= 5.8