be62c8701a
- Add `show-arguments` recipe documenting all version update commands - Add `complete-update-interactive` recipe for manual confirmations - Maintain `complete-update` as automatic mode (no prompts) - Update `update-help` to reference new recipes and modes - Document 7-step workflow and step-by-step differences Changes: - complete-update: Automatic mode (recommended for CI/CD) - complete-update-interactive: Interactive mode (with confirmations) - show-arguments: Complete documentation of all commands and modes - Both modes share same 7-step workflow with different behavior in Step 4
430 lines
13 KiB
Plaintext
430 lines
13 KiB
Plaintext
#!/usr/bin/env nu
|
|
|
|
# Detect Breaking Changes Script
|
|
# Detects API changes and breaking changes between Nushell versions
|
|
#
|
|
# Usage:
|
|
# detect_breaking_changes.nu 0.107.1 0.108.0 # Compare two versions
|
|
# detect_breaking_changes.nu --scan-plugins # Scan plugins for usage of breaking APIs
|
|
# detect_breaking_changes.nu --export # Export breaking changes report
|
|
|
|
use lib/common_lib.nu *
|
|
|
|
# Known breaking changes database
|
|
const BREAKING_CHANGES = {
|
|
"0.108.0": [
|
|
{
|
|
type: "command_rename"
|
|
old_name: "into value"
|
|
new_name: "detect type"
|
|
description: "Command renamed and behavior changed - doesn't operate on cells anymore"
|
|
impact: "high"
|
|
migration: "Replace 'into value' with 'detect type' and review usage for cell operations"
|
|
},
|
|
{
|
|
type: "behavior_change"
|
|
component: "stream_error_handling"
|
|
description: "Collecting a stream that contains errors now raises an error itself"
|
|
impact: "medium"
|
|
migration: "Add explicit error handling when collecting streams that might contain errors"
|
|
},
|
|
{
|
|
type: "feature_addition"
|
|
feature: "mcp"
|
|
description: "MCP (Model Context Protocol) feature added as optional feature"
|
|
impact: "none"
|
|
migration: "Enable with: cargo build --features mcp"
|
|
}
|
|
]
|
|
}
|
|
|
|
# Main entry point
|
|
def main [
|
|
from_version?: string # Source version (e.g., "0.107.1")
|
|
to_version?: string # Target version (e.g., "0.108.0")
|
|
--scan-plugins # Scan plugins for breaking API usage
|
|
--export # Export breaking changes report
|
|
] {
|
|
log_info "Nushell Breaking Changes Detector"
|
|
|
|
# If versions provided, show breaking changes between them
|
|
if ($from_version | is-not-empty) and ($to_version | is-not-empty) {
|
|
show_breaking_changes $from_version $to_version
|
|
} else if $scan_plugins {
|
|
scan_plugins_for_breaking_changes
|
|
} else {
|
|
# Show all known breaking changes
|
|
show_all_breaking_changes
|
|
}
|
|
|
|
if $export {
|
|
export_breaking_changes_report
|
|
}
|
|
}
|
|
|
|
# Show breaking changes between two versions
|
|
def show_breaking_changes [
|
|
from_version: string
|
|
to_version: string
|
|
] {
|
|
log_info $"Analyzing breaking changes: [$from_version] → [$to_version]"
|
|
|
|
# Get breaking changes for target version
|
|
let changes = get_breaking_changes_for_version $to_version
|
|
|
|
if ($changes | is-empty) {
|
|
log_success $"No known breaking changes between [$from_version] and [$to_version]"
|
|
return
|
|
}
|
|
|
|
log_warn $"Found ($changes | length) breaking changes in version [$to_version]"
|
|
|
|
# Display by impact level
|
|
display_breaking_changes_by_impact $changes
|
|
}
|
|
|
|
# Get breaking changes for a specific version
|
|
def get_breaking_changes_for_version [
|
|
version: string
|
|
]: nothing -> list<record> {
|
|
$BREAKING_CHANGES | get -i $version | default []
|
|
}
|
|
|
|
# Display breaking changes organized by impact
|
|
def display_breaking_changes_by_impact [
|
|
changes: list<record>
|
|
] {
|
|
# Group by impact
|
|
let high_impact = $changes | where impact == "high"
|
|
let medium_impact = $changes | where impact == "medium"
|
|
let low_impact = $changes | where impact == "low" or impact == "none"
|
|
|
|
if ($high_impact | length) > 0 {
|
|
log_error "\n=== HIGH IMPACT CHANGES ==="
|
|
display_change_list $high_impact
|
|
}
|
|
|
|
if ($medium_impact | length) > 0 {
|
|
log_warn "\n=== MEDIUM IMPACT CHANGES ==="
|
|
display_change_list $medium_impact
|
|
}
|
|
|
|
if ($low_impact | length) > 0 {
|
|
log_info "\n=== LOW/NO IMPACT CHANGES ==="
|
|
display_change_list $low_impact
|
|
}
|
|
}
|
|
|
|
# Display list of changes
|
|
def display_change_list [
|
|
changes: list<record>
|
|
] {
|
|
$changes | each {|change|
|
|
let type_badge = match $change.type {
|
|
"command_rename" => "🔄 RENAME",
|
|
"behavior_change" => "⚠️ BEHAVIOR",
|
|
"api_removal" => "❌ REMOVAL",
|
|
"feature_addition" => "✨ FEATURE",
|
|
_ => "📝 CHANGE"
|
|
}
|
|
|
|
print $"\n ($type_badge)"
|
|
|
|
if ($change | get -i old_name | is-not-empty) {
|
|
print $" Old: ($change.old_name) → New: ($change.new_name)"
|
|
}
|
|
|
|
if ($change | get -i component | is-not-empty) {
|
|
print $" Component: ($change.component)"
|
|
}
|
|
|
|
if ($change | get -i feature | is-not-empty) {
|
|
print $" Feature: ($change.feature)"
|
|
}
|
|
|
|
print $" Description: ($change.description)"
|
|
print $" Migration: ($change.migration)"
|
|
}
|
|
}
|
|
|
|
# Show all known breaking changes
|
|
def show_all_breaking_changes [] {
|
|
log_info "All Known Breaking Changes"
|
|
|
|
let all_versions = $BREAKING_CHANGES | columns | sort
|
|
|
|
$all_versions | each {|version|
|
|
let changes = $BREAKING_CHANGES | get $version
|
|
log_info $"\n=== Version ($version) - ($changes | length) changes ==="
|
|
display_breaking_changes_by_impact $changes
|
|
}
|
|
}
|
|
|
|
# Scan plugins for usage of breaking APIs
|
|
def scan_plugins_for_breaking_changes [] {
|
|
log_info "Scanning plugins for breaking API usage..."
|
|
|
|
let plugin_dirs = get_plugin_directories
|
|
|
|
log_info $"Scanning ($plugin_dirs | length) custom plugins"
|
|
|
|
mut findings = []
|
|
|
|
for plugin_dir in $plugin_dirs {
|
|
let plugin_name = get_plugin_name $plugin_dir
|
|
log_info $"Scanning: [$plugin_name]..."
|
|
|
|
let plugin_findings = scan_plugin_directory $plugin_dir
|
|
|
|
if ($plugin_findings | length) > 0 {
|
|
$findings = ($findings | append {
|
|
plugin: $plugin_name
|
|
findings: $plugin_findings
|
|
})
|
|
}
|
|
}
|
|
|
|
# Display results
|
|
if ($findings | length) > 0 {
|
|
log_warn $"\n=== Breaking API Usage Found ==="
|
|
$findings | each {|result|
|
|
log_warn $"\n[$result.plugin]"
|
|
$result.findings | each {|finding|
|
|
print $" • ($finding.pattern) in ($finding.file):($finding.line)"
|
|
print $" Context: ($finding.context)"
|
|
}
|
|
}
|
|
|
|
log_info "\nReview these findings and update code accordingly"
|
|
} else {
|
|
log_success "No breaking API usage detected!"
|
|
}
|
|
}
|
|
|
|
# Scan a plugin directory for breaking API usage
|
|
def scan_plugin_directory [
|
|
plugin_dir: string
|
|
]: nothing -> list<record> {
|
|
mut findings = []
|
|
|
|
# Get all Rust source files
|
|
let rust_files = glob $"($plugin_dir)/src/**/*.rs"
|
|
|
|
for file in $rust_files {
|
|
# Check for "into value" usage (breaking in 0.108.0)
|
|
let into_value_matches = try {
|
|
open $file
|
|
| lines
|
|
| enumerate
|
|
| where {|row| $row.item =~ "into value"}
|
|
} catch {
|
|
[]
|
|
}
|
|
|
|
if ($into_value_matches | length) > 0 {
|
|
for match in $into_value_matches {
|
|
$findings = ($findings | append {
|
|
pattern: "into value (renamed to 'detect type')"
|
|
file: $file
|
|
line: ($match.index + 1)
|
|
context: ($match.item | str trim)
|
|
})
|
|
}
|
|
}
|
|
|
|
# Check for stream collection patterns (behavior changed in 0.108.0)
|
|
let collect_matches = try {
|
|
open $file
|
|
| lines
|
|
| enumerate
|
|
| where {|row| $row.item =~ "collect\(\)" and $row.item =~ "stream"}
|
|
} catch {
|
|
[]
|
|
}
|
|
|
|
if ($collect_matches | length) > 0 {
|
|
for match in $collect_matches {
|
|
$findings = ($findings | append {
|
|
pattern: "stream.collect() (error behavior changed)"
|
|
file: $file
|
|
line: ($match.index + 1)
|
|
context: ($match.item | str trim)
|
|
})
|
|
}
|
|
}
|
|
}
|
|
|
|
$findings
|
|
}
|
|
|
|
# Export breaking changes report
|
|
def export_breaking_changes_report [] {
|
|
let output_file = "./tmp/breaking_changes_report.json"
|
|
ensure_dir "./tmp"
|
|
|
|
let report = {
|
|
generated_at: (date now | format date "%Y-%m-%d %H:%M:%S")
|
|
breaking_changes_database: $BREAKING_CHANGES
|
|
versions: ($BREAKING_CHANGES | columns)
|
|
}
|
|
|
|
$report | to json | save -f $output_file
|
|
log_success $"Breaking changes report exported to: ($output_file)"
|
|
}
|
|
|
|
# Check if code is affected by breaking changes
|
|
def "main check-code" [
|
|
code_snippet: string # Code to check
|
|
] {
|
|
log_info "Checking code for breaking API usage..."
|
|
|
|
mut issues = []
|
|
|
|
# Check for "into value"
|
|
if ($code_snippet =~ "into value") {
|
|
$issues = ($issues | append {
|
|
pattern: "into value"
|
|
severity: "high"
|
|
suggestion: "Replace with 'detect type' (note: behavior changed)"
|
|
})
|
|
}
|
|
|
|
# Check for direct stream collection
|
|
if ($code_snippet =~ "\.collect\(\)") {
|
|
$issues = ($issues | append {
|
|
pattern: "stream.collect()"
|
|
severity: "medium"
|
|
suggestion: "Add explicit error handling for stream errors"
|
|
})
|
|
}
|
|
|
|
# Display results
|
|
if ($issues | length) > 0 {
|
|
log_warn "Potential breaking API usage detected:"
|
|
$issues | each {|issue|
|
|
let severity_color = if $issue.severity == "high" { "red" } else { "yellow" }
|
|
print $" (ansi $severity_color)• ($issue.pattern)(ansi reset)"
|
|
print $" → ($issue.suggestion)"
|
|
}
|
|
} else {
|
|
log_success "No breaking API usage detected in code snippet"
|
|
}
|
|
}
|
|
|
|
# Generate migration guide for a specific version
|
|
def "main migration-guide" [
|
|
version: string # Version to generate guide for
|
|
] {
|
|
log_info $"Generating migration guide for version [$version]"
|
|
|
|
let changes = get_breaking_changes_for_version $version
|
|
|
|
if ($changes | is-empty) {
|
|
log_info $"No breaking changes documented for version [$version]"
|
|
return
|
|
}
|
|
|
|
# Generate markdown migration guide
|
|
let guide = generate_migration_markdown $version $changes
|
|
|
|
let output_file = $"./tmp/MIGRATION_($version).md"
|
|
ensure_dir "./tmp"
|
|
|
|
$guide | save -f $output_file
|
|
log_success $"Migration guide generated: ($output_file)"
|
|
}
|
|
|
|
# Generate migration guide in markdown format
|
|
def generate_migration_markdown [
|
|
version: string
|
|
changes: list<record>
|
|
]: nothing -> string {
|
|
mut content = $"# Migration Guide to Nushell ($version)\n\n"
|
|
$content = $"($content)Generated: (date now | format date '%Y-%m-%d %H:%M:%S')\n\n"
|
|
|
|
$content = $"($content)## Breaking Changes\n\n"
|
|
$content = $"($content)This guide covers ($changes | length) breaking changes in Nushell ($version).\n\n"
|
|
|
|
# Group by impact
|
|
let high_impact = $changes | where impact == "high"
|
|
let medium_impact = $changes | where impact == "medium"
|
|
let low_impact = $changes | where impact == "low" or impact == "none"
|
|
|
|
if ($high_impact | length) > 0 {
|
|
$content = $"($content)### ⚠️ High Impact Changes\n\n"
|
|
for change in $high_impact {
|
|
$content = ($content + (format_change_markdown $change) + "\n")
|
|
}
|
|
}
|
|
|
|
if ($medium_impact | length) > 0 {
|
|
$content = $"($content)### 📝 Medium Impact Changes\n\n"
|
|
for change in $medium_impact {
|
|
$content = ($content + (format_change_markdown $change) + "\n")
|
|
}
|
|
}
|
|
|
|
if ($low_impact | length) > 0 {
|
|
$content = $"($content)### ✨ Low/No Impact Changes\n\n"
|
|
for change in $low_impact {
|
|
$content = ($content + (format_change_markdown $change) + "\n")
|
|
}
|
|
}
|
|
|
|
$content
|
|
}
|
|
|
|
# Format single change as markdown
|
|
def format_change_markdown [
|
|
change: record
|
|
]: nothing -> string {
|
|
mut content = $"#### ($change.type | str title-case)\n\n"
|
|
|
|
if ($change | get -i old_name | is-not-empty) {
|
|
$content = $"($content)**Old**: `($change.old_name)` → **New**: `($change.new_name)`\n\n"
|
|
}
|
|
|
|
$content = $"($content)**Description**: ($change.description)\n\n"
|
|
$content = $"($content)**Migration**: ($change.migration)\n\n"
|
|
|
|
$content
|
|
}
|
|
|
|
# Add a new breaking change to the database
|
|
def "main add" [
|
|
version: string # Version this applies to
|
|
type: string # Type of change
|
|
description: string # Description
|
|
impact: string # Impact level (high/medium/low/none)
|
|
migration: string # Migration instructions
|
|
--old-name: string # Old name (for renames)
|
|
--new-name: string # New name (for renames)
|
|
] {
|
|
log_info "This command would add a new breaking change to the database"
|
|
log_warn "Note: The database is currently hardcoded in the script"
|
|
log_info "For production use, consider storing in external TOML/JSON file"
|
|
|
|
let new_change = {
|
|
type: $type
|
|
description: $description
|
|
impact: $impact
|
|
migration: $migration
|
|
}
|
|
|
|
# Add optional fields
|
|
let new_change = if ($old_name | is-not-empty) {
|
|
$new_change | merge {old_name: $old_name}
|
|
} else {
|
|
$new_change
|
|
}
|
|
|
|
let new_change = if ($new_name | is-not-empty) {
|
|
$new_change | merge {new_name: $new_name}
|
|
} else {
|
|
$new_change
|
|
}
|
|
|
|
log_info "New change to add:"
|
|
print ($new_change | to json)
|
|
}
|