nodejs

Documentation

Overview

Package nodejs provides analyzers for Node.js projects.

A Node.js project is defined as any folder with a `package.json`. A project may or may not have dependencies.

A `BuildTarget` for Node.js is defined as the relative path to the directory containing the `package.json`, and the `Dir` is defined as the CWD for running build tools (like `npm` or `yarn`).

`npm` and `yarn` are explicitly supported as first-class tools. Where possible, these tools are queried before falling back to other strategies.

All Node.js projects are implicitly supported via `node_modules` parsing.

Index

• Constants
• Variables
• func AnalyzeNodeModules(dir module.Filepath, target module.Filepath) (graph.Deps, *errors.Error)
• func AnalyzeNpmCmd(dir module.Filepath, _ module.Filepath) (graph.Deps, *errors.Error)
• func AnalyzeNpmLock(dir module.Filepath, target module.Filepath) (graph.Deps, *errors.Error)
• func AnalyzePackageJson(dir module.Filepath, target module.Filepath) (graph.Deps, *errors.Error)
• func AnalyzeYarnCmd(dir module.Filepath, target module.Filepath) (graph.Deps, *errors.Error)
• func AnalyzeYarnLock(dir module.Filepath, target module.Filepath) (graph.Deps, *errors.Error)
• func Discover(dir string, options map[string]interface{}) ([]module.Module, error)
• func NewDiscover(dir module.Filepath) (map[module.Filepath]module.DiscoveredStrategies, *errors.Error)
• type Analyzer
  • func New(m module.Module) (*Analyzer, error)
  • func (a *Analyzer) Analyze() (graph.Deps, error)
  • func (a *Analyzer) Build() error
  • func (a *Analyzer) Clean() error
  • func (a *Analyzer) IsBuilt() (bool, error)
• type Options

Constants

const (
	AnalyzerName = "nodejs"

	YarnStrategy        = "yarn"
	NpmStrategy         = "npm"
	YarnLockStrategy    = "yarn.lock"
	NpmLockStrategy     = "package-lock.json"
	NodeModulesStrategy = "node_modules"
	PackageJsonStrategy = "package.json"
)

Variables

var NodeAnalyzer = module.AnalyzerV2{
	Name:         AnalyzerName,
	DiscoverFunc: NewDiscover,
	Strategies: module.Strategies{
		Named: map[module.StrategyName]module.Strategy{
			YarnStrategy:        AnalyzeYarnCmd,
			NpmStrategy:         AnalyzeNpmCmd,
			YarnLockStrategy:    AnalyzeYarnLock,
			NpmLockStrategy:     AnalyzeNpmLock,
			NodeModulesStrategy: AnalyzeNodeModules,
			PackageJsonStrategy: AnalyzePackageJson,
		},
		Optimal: []module.StrategyName{YarnStrategy, NpmStrategy, YarnLockStrategy, NpmLockStrategy},
		SortedNames: []module.StrategyName{
			YarnStrategy,
			NpmStrategy,
			YarnLockStrategy,
			NpmLockStrategy,
			NodeModulesStrategy,
			PackageJsonStrategy,
		},
	},
}

Functions

func AnalyzeNodeModules

func AnalyzeNodeModules(dir module.Filepath, target module.Filepath) (graph.Deps, *errors.Error)

target is node_modules

func AnalyzeNpmCmd

func AnalyzeNpmCmd(dir module.Filepath, _ module.Filepath) (graph.Deps, *errors.Error)

func AnalyzeNpmLock

func AnalyzeNpmLock(dir module.Filepath, target module.Filepath) (graph.Deps, *errors.Error)

func AnalyzePackageJson

func AnalyzePackageJson(dir module.Filepath, target module.Filepath) (graph.Deps, *errors.Error)

target is package.json

func AnalyzeYarnCmd

func AnalyzeYarnCmd(dir module.Filepath, target module.Filepath) (graph.Deps, *errors.Error)

path is path to package.json

func AnalyzeYarnLock

func AnalyzeYarnLock(dir module.Filepath, target module.Filepath) (graph.Deps, *errors.Error)

target is yarn.lock

func Discover

func Discover(dir string, options map[string]interface{}) ([]module.Module, error)

Discover searches for `package.json`s not within a `node_modules` or `bower_components`.

func NewDiscover

func NewDiscover(dir module.Filepath) (map[module.Filepath]module.DiscoveredStrategies, *errors.Error)

Types

type Analyzer

type Analyzer struct {
	NodeVersion string

	NPM  npm.NPM
	Yarn yarn.YarnTool

	Module  module.Module
	Options Options
}

func New

func New(m module.Module) (*Analyzer, error)

New configures Node, NPM, and Yarn commands.

func (*Analyzer) Analyze

func (a *Analyzer) Analyze() (graph.Deps, error)

func (*Analyzer) Build

func (a *Analyzer) Build() error

Build runs `yarn install --production --frozen-lockfile` if there exists a `yarn.lock` and `yarn` is available. Otherwise, it runs `npm install --production`.

func (*Analyzer) Clean

func (a *Analyzer) Clean() error

Clean removes `node_modules`.

func (*Analyzer) IsBuilt

func (a *Analyzer) IsBuilt() (bool, error)

IsBuilt returns true if a project has a manifest and either has no dependencies or has a `node_modules` folder.

Note that there could be very strange builds where this will produce false negatives (e.g. `node_modules` exists in a parent folder). There can also exist builds where this will produce false positives (e.g. `node_modules` folder does not include the correct dependencies). We also don't take $NODE_PATH into account during resolution.

TODO: with significantly more effort, we can eliminate both of these situations.

type Options

type Options struct {
	Strategy    string `mapstructure:"strategy"`
	AllowNPMErr bool   `mapstructure:"allow-npm-err"`
}

Options contains options for the `Analyzer`.

The analyzer can use many different strategies. These are:

• `yarn`: Run and parse `yarn ls --json`.
• `npm`: Run and parse `npm ls --json`.
• `yarn.lock`: Parse `./yarn.lock`.
• `package-lock.json`: Parse `./package-lock.json`.
• `node_modules`: Parse `./package.json` and recursively look up dependencies with `node_modules` resolution.
• `node_modules_local`: Parse manifests in `./node_modules“.
• `package.json`: Parse `./package.json`.

If no strategies are specified, the analyzer will try each of these strategies in descending order.