TypeScript Definition Change Analyzer

A command-line tool that analyzes changes between TypeScript definition files (.d.ts) to automatically determine the appropriate semantic version increment based on the nature of the changes.

Features

• Analyzes changes between two TypeScript definition files
• Determines appropriate semantic version bump (MAJOR, MINOR, PATCH)
• Detects various types of changes:
  • Interface modifications
  • Type changes (including union types and conditional types)
  • Function signature changes
  • Export additions/removals
  • Conditional type analysis (new in v0.3.0)
  • Mapped type changes
• Provides detailed change reports in JSON format
• Includes location information for each change
• Supports CI/CD integration
• Configurable rules and behavior
• Plugin system for custom rules

Installation

1npm install -g ts-semver-detector

Usage

Basic usage:

1ts-semver-detector --old oldFile.d.ts --new newFile.d.ts

With options:

1ts-semver-detector --old oldFile.d.ts --new newFile.d.ts --output report.json --config ./config.js

Options

• --old <file>: Path to the old .d.ts file (required)
• --new <file>: Path to the new .d.ts file (required)
• --format <type>: Output format (json) (default: "json")
• --output <file>: Output file path
• --verbose: Show detailed information about changes
• --config <file>: Path to config file
• --ignore-private: Ignore private members (default: true)
• --ignore-internal: Ignore internal members (default: false)
• --treat-missing-as-undefined: Treat missing types as undefined (default: false)
• --treat-undefined-as-any: Treat undefined as any (default: false)

Configuration

The tool can be configured using a configuration file. It supports the following formats:

• JavaScript file (ts-semver-detector.config.js)
• JSON file (ts-semver-detector.config.json)
• RC file (.ts-semver-detectorrc, .ts-semver-detectorrc.json, .ts-semver-detectorrc.js)

Example configuration file:

1module.exports = {
2  // Patterns to ignore when analyzing files
3  ignorePatterns: [
4    "**/node_modules/**",
5    "**/dist/**",
6    "**/build/**",
7    "**/*.test.d.ts",
8  ],
9
10  // Override rule severities
11  ruleOverrides: [
12    {
13      id: "interface-change",
14      severity: "major", // Always treat interface changes as major
15    },
16    {
17      id: "type-change",
18      enabled: false, // Disable type change detection
19    },
20  ],
21
22  // General options
23  ignorePrivateMembers: true,
24  ignoreInternalMembers: true,
25  treatMissingAsUndefined: false,
26  treatUndefinedAsAny: false,
27
28  // Custom rules can be added here
29  customRules: [],
30};

Configuration Options

General Options

• ignorePatterns: Array of glob patterns to ignore when analyzing files
• ignorePrivateMembers: Whether to ignore private class members (default: true)
• ignoreInternalMembers: Whether to ignore internal declarations (default: false)
• treatMissingAsUndefined: Whether to treat missing types as undefined (default: false)
• treatUndefinedAsAny: Whether to treat undefined as any (default: false)

Rule Overrides

Rule overrides allow you to customize the behavior of built-in rules:

1ruleOverrides: [
2  {
3    id: "rule-id", // Rule identifier
4    severity: "major", // Override severity (major, minor, patch)
5    enabled: true, // Enable/disable the rule
6  },
7];

Available rules:

• interface-change: Detects changes in interface declarations
• type-change: Detects changes in type aliases
• function-change: Detects changes in function signatures
• class-change: Detects changes in class declarations
• conditional-type-change: Detects changes in conditional types (v0.3.0+)
• mapped-type-change: Detects changes in mapped types

Custom Rules

You can add custom rules by implementing the Rule interface:

1interface Rule {
2  id: string;
3  description: string;
4  analyze(oldNode: ts.Node, newNode: ts.Node): Change | null;
5}

Example custom rule:

1class CustomRule implements Rule {
2  id = "custom-rule";
3  description = "Custom rule description";
4
5  analyze(oldNode: ts.Node, newNode: ts.Node): Change | null {
6    // Implement your rule logic here
7    return {
8      type: "other",
9      name: "custom",
10      change: this.id,
11      severity: "major",
12      description: "Custom change detected",
13    };
14  }
15}
16
17// Add to configuration
18module.exports = {
19  customRules: [new CustomRule()],
20};

Change Classification

The tool classifies changes according to semantic versioning principles:

MAJOR Version Bump (Breaking Changes)

• Removing exported declarations
• Narrowing type definitions
• Adding required properties to interfaces
• Incompatible function signature changes
• Removing implemented interfaces
• Changing public members to private/protected

MINOR Version Bump (Backwards-Compatible Additions)

• Adding new exports
• Adding optional properties
• Broadening type definitions
• Adding optional parameters
• Adding new public members
• Adding implemented interfaces

PATCH Version Bump

• Documentation changes
• Formatting changes
• No functional changes
• Equivalent type reformatting

Conditional Type Analysis (New in v0.3.0)

The tool now provides comprehensive analysis of conditional type changes, which are critical for maintaining type safety in complex TypeScript libraries.

Conditional Type Changes

Conditional types follow the pattern T extends U ? X : Y and changes to them are classified as follows:

MAJOR Changes (Breaking)

• Narrowed conditions: Making the condition more restrictive

  1// Old: More permissive condition
  2type IsString<T> = T extends string | number ? true : false;
  3
  4// New: More restrictive condition (MAJOR)
  5type IsString<T> = T extends string ? true : false;

• Changed default branch to never: Making the fallback case more restrictive

  1// Old: Fallback returns the original type
  2type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
  3
  4// New: Fallback returns never (MAJOR)
  5type UnwrapPromise<T> = T extends Promise<infer U> ? U : never;

MINOR Changes (Backwards-Compatible)

• Broadened conditions: Making the condition more permissive

  1// Old: More restrictive condition
  2type IsString<T> = T extends string ? true : false;
  3
  4// New: More permissive condition (MINOR)
  5type IsString<T> = T extends string | number ? true : false;

• Enhanced true/false branches: Adding more specific return types

  1// Old: Simple boolean return
  2type IsString<T> = T extends string ? true : false;
  3
  4// New: More specific return types (MINOR)
  5type IsString<T> = T extends string ? "string" : "not-string";

The analyzer automatically detects these patterns and classifies them appropriately, helping you maintain semantic versioning compliance when working with complex conditional types.

Output Formats

Text Output

TypeScript Definition Changes Analysis

Recommended Version Bump:
MAJOR

Changes:
MAJOR interface: Added required property 'language' to interface 'UserSettings'
MINOR interface: Added optional property 'age' to interface 'User'
...

Summary:
Major Changes: 1
Minor Changes: 1
Patch Changes: 0

JSON Output

1{
2  "recommendedVersionBump": "major",
3  "changes": [
4    {
5      "type": "interface",
6      "name": "UserSettings",
7      "change": "added-required-property",
8      "severity": "major",
9      "description": "Added required property 'language'",
10      "location": {
11        "newFile": { "line": 5, "column": 3 }
12      }
13    }
14  ],
15  "summary": {
16    "majorChanges": 1,
17    "minorChanges": 1,
18    "patchChanges": 0
19  }
20}

CI Integration

GitHub Actions Example

1name: API Version Check
2
3on:
4  pull_request:
5    paths:
6      - "**/*.d.ts"
7
8jobs:
9  check-version:
10    runs-on: ubuntu-latest
11    steps:
12      - uses: actions/checkout@v2
13      - name: Setup Node.js
14        uses: actions/setup-node@v2
15        with:
16          node-version: "16"
17      - name: Install ts-semver-detector
18        run: npm install -g ts-semver-detector
19      - name: Check TypeScript API changes
20        run: |
21          ts-semver-detector \
22            --old ${{ github.event.pull_request.base.sha }}:types/index.d.ts \
23            --new ${{ github.event.pull_request.head.sha }}:types/index.d.ts \
24            --format json \
25            --output report.json

GitLab CI Example

1api-version-check:
2  script:
3    - npm install -g ts-semver-detector
4    - ts-semver-detector \
5      --old ${CI_MERGE_REQUEST_DIFF_BASE_SHA}:types/index.d.ts \
6      --new ${CI_MERGE_REQUEST_TARGET_BRANCH_SHA}:types/index.d.ts \
7      --format json \
8      --output changes.json
9  only:
10    - merge_requests
11  changes:
12    - "**/*.d.ts"

Development

Setup

1git clone https://github.com/yourusername/ts-semver-detector.git
2cd ts-semver-detector
3npm install

Running Tests

1npm test

Building

1npm run build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT