Change detector

This hybrid package (CLI / library) analyzes a pair of declaration file rollups generated by @microsoft/api-extractor and provides a detailed report of the degree of change found between them. The intended use of this tool is to provide library authors with detailed guidance (and actionable explanations) around how they should represent a given change using Semantic Versioning.

Version comparison example

In a given git repo, a developer is working on a publishing a new version of their library. For now, let's ignore how we obtain them, but we end up with .d.ts rollups for

• The public version of their library at v1.1.0
• The public version of their library at a yet-to-be-versioned next release they're currently preparing.

If, through analysis of the old and new .d.ts rollups, we found

// old
/**
 * Greet a planet!
 * @public
 */
export function greet(planet: 'earth' | 'mars'): string

and

// new
/**
 * Greet a planet!
 * @public
 */
export function greet(planet: 'earth' | 'mars', prefix?: string): string

We could regard recommend this change as compatible with a MINOR release. New functionality has been added and so the API signature changed, but it should not interfere with established use of the library. We'd recommend a version of 1.2.0

But if instead in the new rollup we found

// new
/**
 * Greet a planet!
 * @public
 */
export function greet(planet: 'earth' | 'mars', prefix: string): string

The fact that the new parameter is not optional means this should be modeled as a MAJOR release. Established users who engage with this function must change their code to align with the new contract.

These comparisons should be made using the TypeScript compiler API, through performing a type equivalence check on a per-exported-symbol basis.

Ultimately this tool should generate a very clear report, describing what the overall recommendation of what the version expression of the yet-to-be-published version of the library should be, and a clear list of the changes that were identified and how they were incorporated into arriving at the recommendation.