nodehunter

Appearance

SDK exports and stability ​

@nodehunter/core publishes a large programmatic surface. nodehunter classifies every export by stability tier so SDK users know what is safe to depend on — and what may move without a major-version apology.

Where to import from ​

Import pathStabilityUse in your app
@nodehunter/corestableYes — primary SDK (runScan, runSize, runFind, envelopes, …)
@nodehunter/core/sharedstableYes — scanner helpers, constants, shared utilities
@nodehunter/core/advancedadvancedSparingly — low-level run emitters; review release notes before upgrading
@nodehunter/core/internalinternalNo — CLI host wiring only; can change in any release
typescript
// Recommended
import { runFind, runInspect, buildAnalysisCommandEnvelope } from '@nodehunter/core';

// Shared helpers when you compose your own walk/sizing
import { walkForNodeModules, DEFAULT_IGNORES } from '@nodehunter/core/shared';

// Avoid in application code
// import { getRunOptions } from '@nodehunter/core/internal';

The root barrel currently exposes 200+ stable flat exports plus namespaces (scan, size, suggestions). Advanced and internal symbols are isolated on subpaths so they do not pollute the default import.

Stability tiers ​

TierMeaning for SDK users
stableSupported public contract — run* ops, host context types, JSON envelope builders, workspace query helpers used by CLI
advancedUseful but lower-level — may evolve as presentation and emitter plumbing changes
internalHost-only — global run options, CLI session glue; not semver-guaranteed for external apps
unclassifiedCannot ship — blocked by pnpm exports:validate in the repository

Tiers are assigned via an allowlist and naming rules in the repo, with optional @sdkTier JSDoc tags on declarations. See the export governance README on GitHub for maintainer commands and tier tagging.

Why this exists ​

nodehunter grew a rich workspace layer (find, why, inspect, buildWorkspaceIndex, cache ports, presentation builders). Export governance keeps that power auditable:

  • New symbols must be classified before release
  • exports:diff shows what changed between tags or local edits
  • exports:validate fails CI if tsconfig paths drift from package.json exports or unclassified symbols appear

That discipline is what lets the CLI ship a self-contained binary while still publishing @nodehunter/core as its own package — you get a reviewed surface, not an accidental dump of every internal helper.

Reports SDK users should care about ​

If you pin @nodehunter/core and upgrade between nodehunter releases, these commands (run from a clone of the repository) explain API drift:

bash
pnpm exports:inventory          # tier counts for current barrel
pnpm exports:diff v0.0.1        # what changed since a tag
pnpm exports:validate           # strict pass/fail

How to read them ​

CommandWhat to look for
exports:inventorystable / advanced / internal counts; use -v to list every symbol and tier
exports:diffAdded / removed symbols when upgrading — scan for APIs you import
exports:validateExit 0 = barrel rules satisfied; failures mean the release is not ready

Diff output is the upgrade guide: if a symbol you rely on moved to internal or was removed, pin the previous version or adjust imports before deploying.

Inventory verbose (-v) shows targetSubpath — confirms whether a name lives on the root barrel or a subpath.

Full operator manual: scripts/exports/README.md (commands, cache, flags, examples).

Namespaces on the root barrel ​

The root package also exports grouped namespaces:

typescript
import { scan, size, suggestions } from '@nodehunter/core';

These mirror sub-areas of the engine. Prefer direct named imports (runScan) unless you want a prefixed API (scan.runScan).

Before you depend on a symbol ​

  1. Import from @nodehunter/core or @nodehunter/core/shared first.
  2. Avoid @nodehunter/core/internal in libraries, services, and CI jobs.
  3. Treat @nodehunter/core/advanced like a power-user escape hatch — pin versions and read exports:diff on upgrade.
  4. For JSON integrations, prefer stable envelope builders documented in JSON output.