CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-jsii-diff

Assembly comparison for jsii that detects breaking changes and compatibility violations between library versions

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

cli.mddocs/

Command Line Interface

Full-featured CLI tool for comparing jsii assemblies with support for local files, directories, NPM packages, and comprehensive configuration options for CI/CD integration.

Basic Usage

jsii-diff <original> [updated] [options]

Arguments

  • <original> - Original assembly (required)

    • File path to .jsii file
    • Directory path to jsii package
    • NPM package specifier: npm:<package>[@version]

  • [updated] - Updated assembly (optional, defaults to current directory)

    • Same format options as original
    • Defaults to . (current directory)

Input Formats

Local Files and Directories

# Compare two local jsii files
jsii-diff ./v1/assembly.jsii ./v2/assembly.jsii

# Compare two local package directories
jsii-diff ./packages/my-lib-v1 ./packages/my-lib-v2

# Compare current directory against previous version
jsii-diff ./packages/my-lib-v1

NPM Package Specifiers

# Compare current directory against latest published version
jsii-diff npm:

# Compare current directory against specific version
jsii-diff npm:my-package@1.0.0

# Compare two NPM versions
jsii-diff npm:my-package@1.0.0 npm:my-package@2.0.0

# Compare against latest version (auto-detected from current directory)
jsii-diff npm:my-package

Configuration Options

Error Classification

Control which types of API changes are treated as errors versus warnings.

# Default: Only stable and deprecated API changes cause errors
jsii-diff old new --error-on=prod

# Include external APIs as errors  
jsii-diff old new --error-on=non-experimental

# Treat all API changes as errors
jsii-diff old new --error-on=all

Stability Handling

Configure how unmarked APIs are treated.

# Treat unmarked APIs as stable (default)
jsii-diff old new --default-stability=stable

# Treat unmarked APIs as experimental (more lenient)
jsii-diff old new --default-stability=experimental

Diagnostic Suppression

Suppress specific violations using filter files.

# Suppress violations listed in ignore file
jsii-diff old new --ignore-file=./jsii-diff-ignore.txt

# Show suppression keys for creating ignore files
jsii-diff old new --keys

Validation and Verbosity

# Validate assemblies during loading
jsii-diff old new --validate

# Increase verbosity (can be repeated: -v, -vv, -vvv)
jsii-diff old new --verbose
jsii-diff old new -vv

Complete Options Reference

jsii-diff <original> [updated] [options]

Arguments:
  original  Original assembly (file, package or "npm:package@version")
  updated   New assembly (file, package or "npm:package@version") [default: "."]

Options:
  --verbose, -v              Increase the verbosity of output [count]
  --default-stability, -s    Treat unmarked APIs as [choices: "experimental", "stable"] [default: "stable"]
  --error-on                 Which type of API changes should be treated as an error [choices: "prod", "non-experimental", "all"] [default: "prod"]
  --ignore-file, -i         Ignore API changes with keys from file (file may be missing) [string]
  --keys, -k                Show diagnostic suppression keys [boolean] [default: false]
  --validate, -d            Validate the assemblies that are being loaded [boolean] [default: false]
  --experimental-errors, -e  Error on experimental API changes (deprecated, use --error-on) [boolean] [default: false]
  --help                    Show help [boolean]
  --version                 Show version number [boolean]

Environment Variables

Configuration can also be provided via environment variables with the JSII_DIFF_ prefix:

# Set default options via environment
export JSII_DIFF_ERROR_ON=all
export JSII_DIFF_VERBOSE=2
export JSII_DIFF_IGNORE_FILE=./ignore.txt

jsii-diff old new

Exit Codes

  • 0: No compatibility issues or only warnings
  • 1: Compatibility errors found (based on --error-on setting)
  • 100: Tool error (invalid arguments, file not found, etc.)

Usage Examples

CI/CD Integration

#!/bin/bash
# Check for breaking changes in CI

# Compare current branch against main branch package
git checkout main
npm run build
cp -r ./dist ./dist-main

git checkout feature/my-changes  
npm run build

# Compare with strict settings
jsii-diff ./dist-main ./dist --error-on=all --validate

if [ $? -ne 0 ]; then
    echo "Breaking changes detected! Please review API changes."
    exit 1
fi

Development Workflow

# Check compatibility during development
jsii-diff npm:my-package@latest . --keys > violations.txt

# Create ignore file for acceptable changes
cat > jsii-diff-ignore.txt << EOF
# Acceptable breaking changes for v2.0.0
class-removed:OldDeprecatedClass
method-removed:MyClass.deprecatedMethod  
EOF

# Verify only expected changes remain
jsii-diff npm:my-package@latest . --ignore-file=jsii-diff-ignore.txt

NPM Package Validation

# Before publishing, check against all previous versions
jsii-diff npm:my-package@$(npm view my-package version) .

# Check experimental API evolution
jsii-diff npm:my-package@1.0.0 npm:my-package@2.0.0 --error-on=non-experimental

# Validate a specific version compatibility
jsii-diff npm:my-package@1.5.0 npm:my-package@1.6.0 --validate --verbose

Error Output Format

Diagnostic messages follow a consistent format:

{level} - {element_type} {fully_qualified_name}: {message} [{suppression_key}]

Examples:

err  - CLASS MyClass: has been removed [class-removed:MyClass]
warn - METHOD MyClass.method: parameter 'old' has been removed [method-parameter-removed:MyClass.method.old]  
skip - PROP MyInterface.value: type changed from string to number [property-type-changed:MyInterface.value]

Troubleshooting

Common Issues

"Could not load assembly"

  • Verify file paths exist and are valid jsii assemblies
  • For NPM packages, ensure they are published and accessible
  • Use --validate flag to check assembly format

"NPM package does not exist"

  • Check package name spelling and version availability
  • Verify NPM registry access and authentication
  • Try with explicit version: npm:package@specific-version

"Look like different assemblies"

  • Assemblies have different names - comparison may not be meaningful
  • Ensure you're comparing versions of the same package

Debug Mode

Use verbose logging to diagnose issues:

# Maximum verbosity for troubleshooting
jsii-diff old new -vvv --validate

docs

assembly-comparison.md

cli.md

diagnostics.md

index.md

stability.md

utilities.md

tile.json