Nushell Script Review Checklist
Comprehensive checklist for reviewing Nushell scripts. Check items in order of priority.
---
1. Security (Critical)
Code injection
- [ ] No
nu -c $variablewith untrusted input - [ ] No
source $variablewith runtime paths (must beconst) - [ ] No
runof untrusted.nuscript paths;runtargets must be parse-time constants - [ ] No
^sh -c,^bash -c, or^cmd.exe /Cwith interpolated user input - [ ] No
run-externalwith user-controlled command names
Path safety
- [ ] Existing user-provided paths validated with strict expansion +
path relative-to; no string-prefix containment checks - [ ] No raw
open $user_inputwithout path traversal guard - [ ]
..sequences in user paths detected and rejected - [ ] Base directory enforcement for file operations
Credential handling
- [ ] No hardcoded secrets in source code
- [ ] Credentials scoped with
with-env, not set on$envdirectly - [ ] Secrets read from files/stdin, not passed as command-line arguments
- [ ] No credentials logged via
printor written to non-secure files
Destructive operations
- [ ]
rmoperations validate target path (not/, not$nu.home-dir) - [ ] Glob patterns from user input are validated (no unintended expansion)
- [ ]
--depthlimits onglobto prevent DoS on large trees
Temp files
- [ ] Temp files created with built-in
mktemp, not predictable paths - [ ] Temp files cleaned up in
try/catchor equivalent - [ ] Temp directories use
mktemp --directory
Environment safety
- [ ]
$env.PATHnot modifiable by untrusted input - [ ] Dangerous env vars (
LD_PRELOAD,DYLD_INSERT_LIBRARIES) cleared before running untrusted commands - [ ]
with-envused for scoped environment changes in security-sensitive contexts
---
2. Correctness
Type safety
- [ ] All exported commands have type annotations on parameters
- [ ] I/O pipeline signatures (
]: type -> type {) match actual behavior - [ ] Complex types use proper syntax:
record<name: string>,list<int>,table<col: type> - [ ] Optional parameters use
?suffix:name?: string - [ ] Optional params and typed named options without defaults are handled as
oneof<T, nothing>; boolean switch flags remainbool - [ ] Rest parameters typed:
...args: string - [ ] Runtime assignment annotations are valid under Nu 0.114's default
enforce-runtime-annotations
Error handling
- [ ] Fallible operations wrapped in
try/catch - [ ] External commands checked with
completewhen exit code matters - [ ] Tests do not assert raw nested-Nu diagnostics without normalizing ANSI, PTY wrapping, and
|gutters - [ ]
catchblocks include meaningful error context (not empty) - [ ]
finallyused for cleanup side effects, not as the returned value - [ ]
catchblocks read$err.detailsfor structured diagnostics, not removed$err.json - [ ] Custom errors include
labelwithspanfor good error messages - [ ] No bare
error make {msg: '...'}without span when metadata is available
Null safety
- [ ] Optional record fields accessed with
?:$rec.field? - [ ]
defaultused for fallback values:$val | default 'N/A' - [ ] No bare field access on records from external/untrusted sources
- [ ]
$incaptured early withletwhen used multiple times
Logic correctness
- [ ]
fornot used as final expression (returns null, useeach) - [ ]
mutvariables not captured in closures (will error) - [ ]
source/usepaths areconst, notlet - [ ] Long
if/else ifchains on one value prefermatchunlessifis clearer - [ ]
if/matchexpressions haveelse/_fallbacks when a non-null output is required - [ ]
eachnot used on single records (useitemsortranspose) - [ ]
parsegetslinesfirst when line-by-line parsing of stream input is intended - [ ] Correct operator:
>in non-pipeline context is comparison, not redirect - [ ] Multiline custom command calls with named flags are one-line or wrapped in parentheses
- [ ] SemVer logic uses
into semver/into semver-range/semver bump, not string surgery
External commands
- [ ] External commands prefixed with
^when name conflicts with builtins - [ ]
find(Nushell builtin) vs^find(Unix) distinction maintained - [ ]
sort(Nushell builtin) vs^sort(Unix) distinction maintained - [ ] Arguments to external commands separated (not concatenated strings)
- [ ] Format strings passed to external commands use double quotes for simple escapes, or
char tab/char nlwhen interpolation is needed
---
3. Style & Idiom
Naming
- [ ] Commands:
kebab-case(fetch-user, notfetchUserorfetch_user) - [ ] Variables/params:
snake_case($user_id, not$userId) - [ ] Env vars:
SCREAMING_SNAKE_CASE($env.APP_VERSION) - [ ] Flags:
kebab-case(--output-dir, not--output_dir) - [ ] Full words preferred (
$user_name, not$usr_nm)
String format priority
- [ ] Bare words in arrays:
[foo bar]not["foo" "bar"] - [ ] Single quotes for simple strings:
'hello'not"hello" - [ ] Single-quoted interpolation preferred:
$'val: ($x)'not$"val: ($x)" - [ ] Strings needing a literal
(use$"...\(...", never$'...'— in
$'...' the paren always opens an expression and \( does not escape it
- [ ] Double quotes only when escape sequences needed:
"\n","\t" - [ ] Raw strings for regex:
r#'pattern'# - [ ]
str uppercase/str lowercaseused instead of deprecatedstr upcase/str downcase
Pipeline & functional style
- [ ] Pipelines preferred over imperative loops
- [ ]
$items | get price | math suminstead ofmut total; for ... - [ ]
ls | where size > 1mbinstead of manual filtering - [ ]
enumerateinstead of manual index counters - [ ]
reduceinstead ofmutaccumulator +for - [ ]
matchpreferred for multi-branch dispatch on a single value
Formatting
- [ ] No space before
|params|in closures:{|x| ...}not{ |x| ...} - [ ] Spaces around pipe:
cmd | cmdnotcmd|cmd - [ ] Commas omitted in lists:
[1 2 3]not[1, 2, 3] - [ ] One space after
:in records:{x: 1}not{x:1} - [ ] Multi-line format for expressions >80 chars
Documentation
- [ ] Exported commands have
#comment abovedef - [ ] Parameter descriptions as inline
#comments - [ ]
@exampleattributes for non-trivial commands - [ ]
@categoryfor organization when applicable
Modules
- [ ] Only necessary definitions are
export-ed - [ ]
export def mainused when command matches module name - [ ] Submodules are re-exported explicitly when callers need the submodule namespace in Nu 0.114+
- [ ] Private helpers are not exported
- [ ]
export-envfor environment setup blocks
---
4. Performance
Parallelism
- [ ]
par-eachused for I/O-bound work (file reads, HTTP requests) - [ ]
par-eachused for CPU-bound work (data processing) - [ ]
--threadsspecified when controlling concurrency matters - [ ]
eachused only when order matters or list is tiny
Streaming & memory
- [ ]
each --flattenfor streaming nested results - [ ] Large files not loaded entirely when streaming suffices
- [ ]
lines+ pipeline for line-by-line processing of large files - [ ]
peekused for stream metadata/sample inspection instead of collecting - [ ]
first N/take whileto limit processing early
Caching & computation
- [ ] Expensive results cached in
letbindings, not recomputed - [ ]
globwith--depthto avoid scanning huge trees - [ ] Built-in commands preferred over external for small data
- [ ] External tools (
^rg,^jq) used for large-scale operations
---
5. Robustness
Input validation
- [ ] Parameter types annotated (catches misuse at parse time)
- [ ] Range/value checks at function entry for critical params
- [ ] User-facing commands validate inputs before processing
- [ ] Consistent return types (don't mix null and value unexpectedly)
File operations
- [ ]
path existschecked beforeopenwhen file may not exist - [ ]
save --forceused intentionally (overwrites without warning) - [ ] File encoding handled appropriately (
open --rawfor binary) - [ ]
from xlsx/from odsoutput handled as a record of sheet tables - [ ] Spreadsheet imports use
--noheaders,--first-row, or--prefer-integersinstead of removed--header-row - [ ]
mkdir -v/mv -v/rm -voutputs treated as tables, not parsed text - [ ]
rm/mkdirpartial-success behavior considered when multiple paths are passed
Process management
- [ ] Long-running external processes have timeouts or cancellation
- [ ] Background jobs (
job spawn) tracked and cleaned up - [ ] Exit codes checked for critical external commands
---
Review Workflow
1. Skim the entire script — Understand purpose, entry points, data flow 2. Security pass — Check Section 1 items systematically 3. Correctness pass — Verify types, error handling, null safety 4. Style pass — Naming, strings, formatting, documentation 5. Performance pass — Parallelism, streaming, caching opportunities 6. Robustness pass — Input validation, file safety, process management 7. Summarize findings — Group by severity, highlight security issues first