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 expgov validate in the repository

Tiers are assigned via expgov.config.ts allowlists and naming rules, with optional @sdkTier JSDoc tags on declarations. Maintainers use the expgov CLI (expgov inventory, expgov diff, expgov validate).

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
  • expgov diff shows what changed between tags or local edits
  • expgov 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 exec expgov inventory    # tier counts for current barrel
pnpm exec expgov diff v1.0.0  # what changed since a published tag
pnpm exec expgov validate     # strict pass/fail

Pass any prior git tag to expgov diff (the current release tag after publishing, or an older tag when upgrading). Site sync fills the example tag from the root package version — see apps/docs/README.md.

How to read them ​

CommandWhat to look for
expgov inventorystable / advanced / internal counts; use -v to list every symbol and tier
expgov diffAdded / removed symbols when upgrading — scan for APIs you import
expgov 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: expgov (commands, config, cache, flags).

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 expgov diff on upgrade.
  4. For JSON integrations, prefer stable envelope builders documented in JSON output.