apisurf/lib/commands/inspect.js

Analyze API surface changes between npm package versions to catch breaking changes

import { Command } from 'commander';
import chalk from 'chalk';
import { analyzeInspect } from '../analyzers/analyzeInspect.js';
import { formatInspectOutput } from '../utilities/formatInspectOutput.js';
export const inspectCommand = new Command('inspect')
    .description('Inspect the public API surface of an npm package')
    .argument('<package>', 'NPM package name with optional version (e.g., lodash or lodash@4.17.21)')
    .option('--format <format>', 'Output format: console, json, markdown, html, report', 'report')
    .option('--registry <url>', 'NPM registry URL (defaults to public npm, respects .npmrc)')
    .option('--verbose', 'Enable verbose output including npm notices')
    .action(async (packageSpec, options) => {
    try {
        // Parse package name and version
        const atIndex = packageSpec.lastIndexOf('@');
        let packageName;
        let version = 'latest';
        // Handle scoped packages like @angular/core
        if (packageSpec.startsWith('@')) {
            const secondAtIndex = packageSpec.indexOf('@', 1);
            if (secondAtIndex > 0) {
                packageName = packageSpec.substring(0, secondAtIndex);
                version = packageSpec.substring(secondAtIndex + 1);
            }
            else {
                packageName = packageSpec;
            }
        }
        else if (atIndex > 0) {
            packageName = packageSpec.substring(0, atIndex);
            version = packageSpec.substring(atIndex + 1);
        }
        else {
            packageName = packageSpec;
        }
        // Show progress for console and report formats
        if (options.format === 'console' || options.format === 'report') {
            console.log(`Inspecting ${chalk.cyan(packageName)}@${chalk.yellow(version)} API surface...`);
            console.log();
        }
        const result = await analyzeInspect({
            packageName,
            version,
            registry: options.registry,
            verbose: options.verbose,
            format: options.format
        });
        const output = formatInspectOutput(result, options.format, options.verbose);
        // For markdown, json, and html formats, output directly without any additional formatting
        if (options.format === 'markdown' || options.format === 'json' || options.format === 'html') {
            process.stdout.write(output + '\n');
        }
        else {
            console.log(output);
        }
        if (!result.success) {
            process.exit(1);
        }
    }
    catch (error) {
        console.error('Error during inspect analysis:', error instanceof Error ? error.message : String(error));
        process.exit(1);
    }
});