Node.js bindings

Run fallow analyses from your own Node.js code and get typed results. The NAPI bindings need no CLI subprocess or JSON parsing and return the same JSON envelopes as the CLI.

With @fallow-cli/fallow-node, you call the main fallow analyses as async Node.js functions. You do not start a CLI subprocess or parse JSON. The functions use the same analysis layer as the CLI and return the same JSON report envelopes as --format json. The optional detectSimilarCode function verifies and starts its local model companion, which must be the exact matching version.

Use the bindings to embed fallow in code that would otherwise call the CLI:

• another tool
• a Node.js server
• an editor extension
• a custom script

Install

npm install @fallow-cli/fallow-node

The package is a native NAPI-RS addon. It has platform-specific optionalDependencies for these platforms:

• macOS (arm64, x64)
• Linux (gnu and musl on arm64 and x64)
• Windows (x64, arm64)

npm installs the matching binary.

The package requires Node 22 or newer.

Basic usage

import {
  detectDeadCode,
  detectDuplication,
  detectSimilarCode,
  computeHealth,
} from '@fallow-cli/fallow-node';

const deadCode = await detectDeadCode({
  root: process.cwd(),
  explain: true,
});

console.log(deadCode.summary.total_issues);
console.log(deadCode.unused_exports);

const similar = await detectSimilarCode({
  root: process.cwd(),
  threshold: 0.8,
  top: 20,
});

console.log(similar.candidates);

Each function returns a promise. The promise resolves to the same JSON envelope that the CLI prints with --format json. The envelope has:

• a top-level kind discriminator on typed roots
• schema_version
• summary
• relative paths
• injected actions arrays
• a _meta block with docs links, when explain: true

API

All nine functions are async and take an optional options object. The functions ignore unknown fields. Enum-like fields take lowercase CLI-style literals, such as "mild", "cyclomatic", "handle", and "low".

The --circular-deps and --boundary-violations flags of fallow dead-code are deprecated aliases. They select only one issue type, so they stay the exact CLI equivalents here. fallow architecture reports all import cycles, boundary violations and policy violations together. detectArchitecture is the binding for that command. detectCircularDependencies and detectBoundaryViolations continue to return the dead-code report (kind: "dead-code").

Shared options

Every options object extends AnalysisOptions:

Dead-code options

detectDeadCode, detectCircularDependencies, and detectBoundaryViolations take the same options type, DeadCodeOptions. When you set one or more filter booleans below, the report has only those issue types. When you set none, the report has every category, as the CLI does by default.

Architecture options

detectArchitecture takes ArchitectureOptions. It adds these fields to AnalysisOptions:

When you set no selector, the report has all architecture issue types.

Duplication options

DuplicationOptions adds these fields to AnalysisOptions:

Each returned clone group has spread. Near-miss groups also have similarity. ignoreSymlinks: true omits clone instances whose path is a symlink or lies under a symlinked directory. Otherwise, such an instance has is_symlink: true. Duplication stats can have clone_groups_ignored and near_candidates_skipped. The report leaves out these fields when the value is zero.

Similar-code options

SimilarCodeOptions adds these fields for model-based search to AnalysisOptions:

Before it reads any source, the loader finds the fallow-similar-code package of the exact matching version and verifies its native binary. detectSimilarCode never downloads the model. To get the model, run fallow similar-code setup --local once through the CLI, after explicit user approval. The results are unverified. Read Semantic similar code before you use a score to plan a refactor.

Feature flag options

FeatureFlagsOptions adds one field to AnalysisOptions:

Complexity / health options

ComplexityOptions matches the fallow health flags:

Structured errors

A rejected promise throws a FallowNodeError. This is a plain Error with extra fields, and it has the same structured errors as the CLI:

import type { FallowNodeError } from '@fallow-cli/fallow-node';

try {
  await detectDeadCode({ root: '/does/not/exist' });
} catch (err) {
  const e = err as FallowNodeError;
  console.error(e.name);      // "FallowNodeError"
  console.error(e.message);   // "analysis root does not exist: ..."
  console.error(e.exitCode);  // 2
  console.error(e.code);      // "FALLOW_INVALID_ROOT"
  console.error(e.context);   // "analysis.root"
  console.error(e.help);      // optional remediation hint
}

The exit codes are the same as in the CLI, for example 0 for success, 2 for a generic or validation error, and 7 for a network error (license and cloud operations).

When to use bindings vs the CLI

The bindings and the CLI run the same analysis engine and return the same data.

Limitations

• The bindings cover the one-shot analyses only. They do not include commands that write to the filesystem: fix, init, hooks install, hooks uninstall, --save-baseline, license activate, and coverage setup.
• detectSimilarCode is read-only and never does the first model download. For that, run fallow similar-code setup --local through the CLI after explicit approval.
• There is no baseline or regression support yet. For those workflows, use the CLI flags --baseline and --save-baseline.
• There is no watch mode. For incremental analysis, call the function again. The fallow per-file cache makes repeat runs fast.
• The API is new. Until it is stable, a minor version can have breaking changes.

See also