Skip to content

CLAUDE.md

Latest commit

 

History

History
143 lines (112 loc) · 4.16 KB

CLAUDE.md

File metadata and controls

143 lines (112 loc) · 4.16 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository contains a personal collection of Nushell scripts, modules, custom commands, aliases, and data processing pipelines. The codebase follows Nushell's module system conventions and best practices.

Development Commands

Testing

# Run all tests
nu tests/mod.nu

# Run specific test file
nu tests/test_<module_name>.nu

# Test individual modules during development
nu -c "use src/modules/<module>.nu; <test_command>"

Module Development

# Test module loading
nu -c "use src/modules/<module>.nu *; help commands | where name =~ <pattern>"

# Validate module syntax
nu --check src/modules/<module>.nu

# Load module interactively for testing
nu -c "use src/modules/<module>.nu"

Script Execution

# Run standalone scripts
nu src/scripts/<script>.nu

# Source commands into session
source src/commands/<commands>.nu

Architecture and Structure

Module Organization

  • File-form modules: src/modules/<name>.nu - Single file modules
  • Directory-form modules: src/modules/<name>/mod.nu - Multi-file modules with submodules
  • Entry points: src/modules/mod.nu and src/commands/mod.nu export collections

Export Patterns

All modules follow Nushell's export conventions:

  • export def - Custom commands
  • export const - Constants and configuration
  • export alias - Command aliases
  • export use - Re-export from submodules
  • export-env - Environment setup

Naming Conventions

  • Module files: snake_case (e.g., data_utils.nu)
  • Commands: kebab-case with optional namespacing (e.g., str-reverse, data process)
  • Constants: UPPER_SNAKE_CASE (e.g., DEFAULT_TIMEOUT)
  • Parameters: snake_case with type annotations

Testing Strategy

  • Test files mirror source structure: tests/test_<module>.nu
  • Use std/assert for assertions
  • Export test functions with test- prefix for nupm compatibility
  • Include integration tests for complex pipelines

Code Patterns

Module Template

# Module documentation
# Description of module purpose and usage

# Dependencies
use std/assert

# Constants
export const VERSION = "1.0.0"

# Main functions
export def main-command [
    param: string          # Required parameter with type
    --flag (-f): bool = false  # Optional flag with default
]: list -> table {        # Input/output type signature
    # Implementation
}

# Helper functions (not exported)
def private-helper []: nothing -> string {
    "internal use only"
}

Command Definition Patterns

  • Always include type annotations for parameters and return types
  • Use pipeline input/output signatures (list -> table)
  • Document commands with comments above function definition
  • Prefer functional pipeline operations over imperative loops
  • Handle errors explicitly with try/catch or error propagation

Testing Patterns

use std/assert
use <module_to_test>.nu

export def test-function-name [] {
    let result = (function-under-test "input")
    assert equal $result "expected" "descriptive error message"
}

Development Guidelines

Module Creation

  1. Start with file-form modules in src/modules/
  2. Use directory-form for complex modules with submodules
  3. Always include module documentation at the top
  4. Export only public interface functions
  5. Keep private helpers unexported

Command Design

  • Design commands to work well in pipelines
  • Use structured data (tables, records) over plain text when possible
  • Include comprehensive parameter validation
  • Provide helpful error messages with context
  • Support common flags like --help, --verbose when appropriate

Testing Requirements

  • Write tests for all exported functions
  • Test edge cases and error conditions
  • Use descriptive test names that explain what is being tested
  • Include integration tests for multi-step pipelines
  • Test both success and failure scenarios

Performance Considerations

  • Use Nushell's built-in commands when possible (they're optimized)
  • Avoid excessive data copying in pipelines
  • Prefer streaming operations for large datasets
  • Profile performance-critical operations