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):**
```nushell
export def find-config [filename: string] -> string {
    # ...
}
```

**New Syntax (required):**
```nushell
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:

```nushell
# 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:

```nushell
# 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**:
   ```bash
   nu scripts/common/find-config.nu
   nu scripts/manifest.nu
   ```

2. **Integration Tests**:
   ```bash
   nu scripts/provisioning/install-with-presets.nu --list-presets
   nu scripts/provisioning/detect-provctl.nu --verbose
   ```

3. **Full Workflow**:
   ```bash
   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](./.claude/guidelines/nushell/NUSHELL_0.109_GUIDELINES.md)
- [Nushell Type Signatures Documentation](https://www.nushell.sh/lang-guide/chapters/types/type_signatures.html)
- [Nushell 0.109.0 Release Notes](https://www.nushell.sh/blog/2025-11-29-nushell_v0_109_0.html)

---

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