0
# Command Line Interface
1

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

4
## Basic Usage
5

6
```bash
7
jsii-diff <original> [updated] [options]
8
```
9

10
### Arguments
11

12
- **`<original>`** - Original assembly (required)
13
  - File path to `.jsii` file
14
  - Directory path to jsii package
15
  - NPM package specifier: `npm:<package>[@version]`
16

17
- **`[updated]`** - Updated assembly (optional, defaults to current directory)
18
  - Same format options as original
19
  - Defaults to `.` (current directory)
20

21
## Input Formats
22

23
### Local Files and Directories
24

25
```bash
26
# Compare two local jsii files
27
jsii-diff ./v1/assembly.jsii ./v2/assembly.jsii
28

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

32
# Compare current directory against previous version
33
jsii-diff ./packages/my-lib-v1
34
```
35

36
### NPM Package Specifiers
37

38
```bash
39
# Compare current directory against latest published version
40
jsii-diff npm:
41

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

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

48
# Compare against latest version (auto-detected from current directory)
49
jsii-diff npm:my-package
50
```
51

52
## Configuration Options
53

54
### Error Classification
55

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

58
```bash
59
# Default: Only stable and deprecated API changes cause errors
60
jsii-diff old new --error-on=prod
61

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

65
# Treat all API changes as errors
66
jsii-diff old new --error-on=all
67
```
68

69
### Stability Handling
70

71
Configure how unmarked APIs are treated.
72

73
```bash
74
# Treat unmarked APIs as stable (default)
75
jsii-diff old new --default-stability=stable
76

77
# Treat unmarked APIs as experimental (more lenient)
78
jsii-diff old new --default-stability=experimental
79
```
80

81
### Diagnostic Suppression
82

83
Suppress specific violations using filter files.
84

85
```bash
86
# Suppress violations listed in ignore file
87
jsii-diff old new --ignore-file=./jsii-diff-ignore.txt
88

89
# Show suppression keys for creating ignore files
90
jsii-diff old new --keys
91
```
92

93
### Validation and Verbosity
94

95
```bash
96
# Validate assemblies during loading
97
jsii-diff old new --validate
98

99
# Increase verbosity (can be repeated: -v, -vv, -vvv)
100
jsii-diff old new --verbose
101
jsii-diff old new -vv
102
```
103

104
## Complete Options Reference
105

106
```bash
107
jsii-diff <original> [updated] [options]
108

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

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

125
## Environment Variables
126

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

129
```bash
130
# Set default options via environment
131
export JSII_DIFF_ERROR_ON=all
132
export JSII_DIFF_VERBOSE=2
133
export JSII_DIFF_IGNORE_FILE=./ignore.txt
134

135
jsii-diff old new
136
```
137

138
## Exit Codes
139

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

144
## Usage Examples
145

146
### CI/CD Integration
147

148
```bash
149
#!/bin/bash
150
# Check for breaking changes in CI
151

152
# Compare current branch against main branch package
153
git checkout main
154
npm run build
155
cp -r ./dist ./dist-main
156

157
git checkout feature/my-changes  
158
npm run build
159

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

163
if [ $? -ne 0 ]; then
164
    echo "Breaking changes detected! Please review API changes."
165
    exit 1
166
fi
167
```
168

169
### Development Workflow
170

171
```bash
172
# Check compatibility during development
173
jsii-diff npm:my-package@latest . --keys > violations.txt
174

175
# Create ignore file for acceptable changes
176
cat > jsii-diff-ignore.txt << EOF
177
# Acceptable breaking changes for v2.0.0
178
class-removed:OldDeprecatedClass
179
method-removed:MyClass.deprecatedMethod  
180
EOF
181

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

186
### NPM Package Validation
187

188
```bash
189
# Before publishing, check against all previous versions
190
jsii-diff npm:my-package@$(npm view my-package version) .
191

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

195
# Validate a specific version compatibility
196
jsii-diff npm:my-package@1.5.0 npm:my-package@1.6.0 --validate --verbose
197
```
198

199
## Error Output Format
200

201
Diagnostic messages follow a consistent format:
202

203
```
204
{level} - {element_type} {fully_qualified_name}: {message} [{suppression_key}]
205
```
206

207
Examples:
208
```
209
err  - CLASS MyClass: has been removed [class-removed:MyClass]
210
warn - METHOD MyClass.method: parameter 'old' has been removed [method-parameter-removed:MyClass.method.old]  
211
skip - PROP MyInterface.value: type changed from string to number [property-type-changed:MyInterface.value]
212
```
213

214
## Troubleshooting
215

216
### Common Issues
217

218
**"Could not load assembly"**
219
- Verify file paths exist and are valid jsii assemblies
220
- For NPM packages, ensure they are published and accessible  
221
- Use `--validate` flag to check assembly format
222

223
**"NPM package does not exist"**  
224
- Check package name spelling and version availability
225
- Verify NPM registry access and authentication
226
- Try with explicit version: `npm:package@specific-version`
227

228
**"Look like different assemblies"**
229
- Assemblies have different names - comparison may not be meaningful
230
- Ensure you're comparing versions of the same package
231

232
### Debug Mode
233

234
Use verbose logging to diagnose issues:
235

236
```bash
237
# Maximum verbosity for troubleshooting
238
jsii-diff old new -vvv --validate
239
```