syntaxis/.claude/guidelines/nushell/AUDIT_REPORT.md

Nushell 0.109 Compatibility Audit Report

Generated: 2025-12-01 Nushell Version: 0.109.0 Project: syntaxis Status: ⚠️ CRITICAL ISSUES FOUND

---

Executive Summary

A comprehensive audit of all Nushell scripts in the syntaxis project has revealed critical compatibility issues with Nushell 0.109. The primary issue is the use of deprecated return type annotation syntax that prevents all affected scripts from running.

Key Findings

Category	Count	Severity
Scripts Audited	32	-
Scripts with Issues	5	-
Total Issues	15	-
Critical Issues	15	🔴 CRITICAL
Warnings	0	-
Info	0	-

---

Critical Issues

Issue #1: Deprecated Return Type Annotation Syntax

Severity: 🔴 CRITICAL Impact: Scripts fail to parse and cannot execute Affected Scripts: 5 files, 15 functions

Problem Description

Nushell 0.109 introduced a breaking change to the return type annotation syntax. The old syntax using ] -> type { is no longer valid and has been replaced with ]: input_type -> output_type {.

Old Syntax (broken):

export def find-config [filename: string] -> string {
    # ...
}

New Syntax (required):

export def find-config [filename: string]: nothing -> string {
    # ...
}

Affected Files and Functions

1. scripts/common/find-config.nu (3 functions)

   • Line 25: export def find-config [filename: string] -> string
   • Line 44: export def find-config-or [filename: string, default: string] -> string
   • Line 56: export def find-db-path [filename: string] -> string

2. scripts/manifest.nu (2 functions)

   • Line 11: export def load-manifest [] -> record
   • Line 49: def manifest_to_toml [manifest: record] -> string

3. scripts/provisioning/detect-provctl.nu (3 functions)

   • Line 34: def detect_provctl [] -> record
   • Line 133: def detect_available_backends [] -> list
   • Line 163: def command_exists [cmd: string] -> bool

4. scripts/provisioning/install-with-presets.nu (5 functions)

   • Line 183: def generate_installation_config [preset: string, config: record] -> string
   • Line 208: def detect_provctl_availability [] -> record
   • Line 223: def select_preset_interactive [config: record] -> string
   • Line 258: def get_binaries_for_preset [preset: string, config: record] -> list
   • Line 481: def run_preflight_checks [preset: string] -> bool

5. scripts/provisioning/provctl-services.nu (2 functions)

   • Line 250: def get_services_for_preset [preset: string = "local"] -> string
   • Line 285: def check_provctl_available [] -> bool

Migration Guide

For each function, update the syntax as follows:

# BEFORE
def function_name [param: type] -> return_type {
    # body
}

# AFTER
def function_name [param: type]: nothing -> return_type {
    # body
}

Note: Use nothing as the input type for functions that don't accept pipeline input. Use any, string, list, etc. for functions that process pipeline input.

---

Additional Findings

Best Practice Recommendations

While auditing the scripts, the following non-critical observations were made:

1. Type Annotations: Most scripts have good type annotations on function parameters
2. Error Handling: Good use of try-catch blocks throughout
3. Documentation: Most public functions have helpful comments
4. Module Structure: Proper use of export def for public APIs

Scripts Without Issues

The following scripts are compatible with Nushell 0.109 (no return type annotations used):

• scripts/core/install-syntaxis-api.nu
• scripts/core/install-all-targets.nu
• scripts/core/install.nu
• scripts/core/build-dashboard.nu
• scripts/syntaxis-cli.nu
• scripts/syntaxis-tui.nu
• scripts/syntaxis-api.nu
• scripts/syntaxis-lib.nu
• scripts/install-syntaxis.nu
• scripts/fix_clippy_warnings.nu
• scripts/provisioning/common/validate.nu
• scripts/provisioning/common/platform.nu
• scripts/provisioning/common/manifest.nu
• scripts/provisioning/pack.nu
• scripts/provisioning/deploy.nu
• scripts/provisioning/install.nu
• scripts/provisioning/provctl.nu
• scripts/provisioning/unpack.nu
• scripts/provisioning/service-catalog.nu
• scripts/provisioning/test-catalog.nu
• scripts/test-installation.nu
• tests/provisioning/test-detect-provctl.nu
• tests/provisioning/test-presets.nu
• tests/provisioning/test-all.nu
• provctl/scripts/export-config.nu

---

Recommendations

Immediate Actions (CRITICAL)

1. ✅ Update Guidelines: Create comprehensive Nushell 0.109 guidelines

   • Status: COMPLETED
   • Location: .claude/guidelines/nushell/NUSHELL_0.109_GUIDELINES.md

2. ⏭️ Fix All Scripts: Update return type annotations in 5 affected scripts

   • Priority: HIGH
   • Estimated effort: 30 minutes
   • Risk: LOW (simple syntax change)

3. ⏭️ Test All Scripts: Run all updated scripts to verify functionality

   • Priority: HIGH
   • Required after fixes

Future Improvements

1. Automated Linting: Consider adding a pre-commit hook to check Nushell syntax
2. Type Annotations: Add return type annotations to remaining scripts (23 scripts without them)
3. Testing: Add more #[test] functions to critical utility scripts
4. Documentation: Add usage examples to all public functions

---

Migration Priority

Phase 1: Critical Infrastructure (IMMEDIATE)

• scripts/common/find-config.nu - Used by many other scripts
• scripts/manifest.nu - Used by installation scripts

Phase 2: Provisioning Scripts (HIGH)

• scripts/provisioning/detect-provctl.nu
• scripts/provisioning/install-with-presets.nu
• scripts/provisioning/provctl-services.nu

Phase 3: Verification (HIGH)

• Run all installation and provisioning workflows
• Test TUI, CLI, and API scripts
• Verify documentation examples

---

Automated Fix Script

A script can be created to automatically fix the syntax:

# Example automated fix
def fix_return_types [file: string] {
    let content = open --raw $file
    let fixed = $content | str replace --all --regex '(\] )-> (\w+) \{' '$1: nothing -> $2 {'
    $fixed | save --force $file
}

Note: Manual review is recommended after automated fixes to ensure correct input types.

---

Testing Plan

After applying fixes:

1. Unit Tests:

   nu scripts/common/find-config.nu
   nu scripts/manifest.nu
   

2. Integration Tests:

   nu scripts/provisioning/install-with-presets.nu --list-presets
   nu scripts/provisioning/detect-provctl.nu --verbose
   

3. Full Workflow:

   nu scripts/provisioning/install-with-presets.nu --preset local
   

---

Conclusion

The syntaxis project requires immediate updates to be compatible with Nushell 0.109. The changes are straightforward but critical - all 15 affected function definitions must be updated to use the new return type annotation syntax.

Estimated Total Effort: 30-45 minutes Risk Level: LOW (mechanical syntax change) Business Impact: HIGH (scripts currently non-functional)

---

References

• Nushell 0.109 Guidelines
• Nushell Type Signatures Documentation
• Nushell 0.109.0 Release Notes

---

Generated by syntaxis Nushell Audit Tool For questions or assistance, see .claude/guidelines/nushell/