Platforms and sizing

nodehunter targets Windows, macOS, and Linux (including WSL). The CLI and @nodehunter/core share the same engines — hosts supply platform context; core never reads process.platform directly.

Supported environments

Environment	Typical sizing	Permission tips
Linux	du -sb when probe succeeds	sudo chown / ls -la
macOS	du -sb when probe succeeds; otherwise Node walk	same as Linux
WSL	Same as Linux inside the guest	POSIX paths and tips
Windows (native)	Node.js directory walk (no du)	Explorer / icacls

WSL is treated as POSIX — you get GNU du when it is on PATH, not Windows-native sizing.

How disk sizing works

nodehunter measures physical on-disk bytes for each node_modules directory. The sizing engine picks a SizeProvider at runtime:

--no-du passed?
  yes → NodeSizeProvider (portable walk)
  no  → probe `du -sb` on a temp dir
          ok   → DuSizeProvider (native du per path)
          fail → NodeSizeProvider + notice

This is a capability probe, not a hard-coded OS switch. Any machine without a working du -sb uses the Node walk — including Windows, minimal containers, or BSD du builds that do not support -sb.

du provider (preferred)

When available, nodehunter shells out to:

du -sb <path>

GNU coreutils on Linux usually pass the probe. This path is fast for large trees and matches familiar disk-usage semantics.

JSON and human output record the provider as sizeProvider: "du" on sized matches.

Node.js provider (portable fallback)

NodeSizeProvider walks the directory in Node and sums apparent file sizes (inode-aware, du-aligned, does not follow symlink entries).

Used when:

• You are on Windows (no standard du)
• du -sb is missing or fails the startup probe
• You pass --no-du (see below)

JSON records sizeProvider: "node". A notice may appear in human mode when fallback happens automatically.

Opt out of du (--no-du)

nodehunter size ~/work --no-du
nodehunter delete ~/work --no-du

--no-du forces the portable Node walk even when du is available. Use it when:

• You need consistent behavior across CI images with and without GNU du
• du is blocked or behaves differently in a sandbox
• You are debugging size discrepancies between providers

Trade-off: Node walk can be slower on very large node_modules trees than native du.

In the SDK, set scan.noDu: true on HostOperationContext (same flag surface as the CLI).

Discovery vs sizing symlinks

Stage	--follow-symlinks (-L)
Discovery (scan, walk)	Optional — may find more node_modules paths
Sizing (size, delete preview)	Symlink directories are not followed (du-aligned)

A notice is emitted if you discover with -L but sizes ignore symlink traversal.

Parallel sizing

size and delete accept --concurrency <n> (default 8, max 32) for parallel size lookups when many matches exist.

Host responsibilities

The CLI passes runtime.platform and scan flags into core. SDK and automation hosts must do the same:

import {
  createSuggestionHostContext,
  resolveHostPlatform,
  runSize,
} from 'nodehunter/core';

const ctx = {
  runtime: {
    cwd: '/path/to/workspace',
    platform: resolveHostPlatform(process.platform),
  },
  scan: { path: '/path/to/workspace', noDu: false },
  suggestions: createSuggestionHostContext(process.platform),
  // … session, list, query
};

Permission-fix copy (chown vs Explorer) comes from createSuggestionHostContext(platform) — see Safety model.

Related

• size command — CLI flags including --no-du and --concurrency
• SDK — programmatic runSize, hooks, and HostOperationContext
• Global flags