Lab 04 · Node Runtime Labs

Module resolution inspector.

Build a local resolver tool that explains how Node turns an importer and specifier into a selected module, which package rules changed the path, and where CommonJS, ESM, caches, cycles, and symlinks can change what a developer sees.

Read the phase plan Get the lab

14Phases

AdvancedDifficulty

0 depsPackage installs

Resolver commandsResolution trace session

01Fixtures
$ npm run fixtures
Builds the package trees used by every trace.
02Relative
$ npm run resolve -- fixtures/generated/app/src/index.cjs ./local
Shows extension probing and package boundary details.
03Exports
$ npm run resolve -- fixtures/generated/app/src/index.cjs pkg-exports/feature
Walks the package exports decision path.
04Cache
$ npm run cache -- fixtures/generated/cycles/a.cjs --format json
Records loaded modules and cycle shape.
05Package
$ npm run inspect-package -- fixtures/generated/app
Prints package metadata the resolver consumed.

Generate fixtures, resolve specifiers, then inspect cache state.

What this lab builds

The finished tool explains Node resolution.

Resolver CLI

Accept an importer path and a specifier, choose the right resolver branch, keep mode and condition options explicit, and print either text or JSON traces.

Fixture package workspace

Generate small packages for main fields, exports maps, blocked subpaths, conditions, ESM, CJS, dual packages, cache cases, cycles, shadowing, and symlinks.

Package rule evidence

Record path probes, node_modules search directories, package metadata, selected export targets, condition checks, selected format, warnings, and errors.

Reports you can hand off

Write text, JSON, Markdown, and self-contained HTML reports, plus cache graphs, cycle evidence, symlink notes, and interop warnings.

Complete phase plan

Every phase in Lab 04.

The build starts with the CLI contract and ends with shareable reports. Each phase adds one resolver branch, one runtime observation path, or one report surface.

00Create the projectCreate the resolver inspector CLI and prove the command contract is stable before any resolver logic exists.

Tasks

Create a private ESM package for Node.js v24 or newer with resolve, fixtures, cache, and inspect-package scripts.
Create src, src/resolver, src/reports, src/probes, scripts, fixtures, and reports folders with one job per folder.
Create the CLI entry file and dispatch resolve <importer> <specifier> from raw process arguments.
Add help output that prints the positional arguments and supported flags, then exits successfully.
Parse mode, repeated conditions, text or JSON format, and preserve-symlinks into one stable options object.
Reject unknown flags on stderr with exit code 2 so bad tool input never creates false resolver evidence.
Create the first report object with importer, specifier, mode, conditions, attempts, warnings, and errors.

Artifact

A CLI shell that accepts the resolver command, prints help, validates flags, and emits a first report shape.

01Create fixture packagesGenerate controlled fixture packages that trigger every resolver branch the inspector needs to explain.

Tasks

Create scripts/create-fixtures.mjs and wire npm run fixtures to it.
Reset only fixtures/generated on every run so generated packages stay repeatable without touching source or reports.
Generate app importers, nested importers, node_modules, and inspector-input.json with importer/specifier pairs for the final report.
Generate relative path targets for exact files, JSON files, directory entries, and missing-file cases.
Generate package fixtures for built-in shadowing, main, broken main, exports, blocked exports, invalid export targets, conditions, ESM, CJS, dual packages, runtime-built CJS, and package shadowing.
Generate nested shadow packages, cache-demo files, circular dependency files, and workspace symlink cases when the platform permits symlinks.
Write fixture-manifest.json with package names, success cases, failure cases, labels, and symlink status.

Artifact

A fixture workspace whose package tree explains relative imports, built-ins, package lookup, metadata, exports, conditions, interop, cache, cycles, and symlinks.

02Resolve relative and absolute pathsTrace CommonJS-style resolution for relative and absolute file specifiers.

Tasks

Create a trace helper for attempts, metadata events, warnings, and errors.
Classify ./, ../, and absolute specifiers as path specifiers before package lookup.
In require mode, try exact path, .js, .json, and .node candidates in order.
When the target is a directory, inspect package.json main, then index.js, index.json, and index.node.
Record failure codes for missing files, missing directory entries, invalid package JSON, and invalid main targets.
Render the same report as readable text or full JSON without mutating the resolver model.

Artifact

A path resolver that shows every attempted candidate before a selected file or a clear missing-path error.

03Resolve built-in modulesDetect Node built-in module specifiers before filesystem or package lookup begins.

Tasks

Load builtinModules from node:module and normalize names with and without the node: prefix.
Record built-in results with the original specifier and canonical node: target.
Run built-in detection before relative path and bare package classification.
Prove a userland package named fs cannot affect require('fs') resolution.
Render the zero-search path by stating that filesystem probing and node_modules lookup were skipped.

Artifact

A built-in branch that resolves fs, path, node:fs, and node:path with no filesystem attempts.

04Resolve node_modules lookupWalk parent directories to explain how bare package lookup selects the nearest package root.

Tasks

Split bare specifiers into packageName and packageSubpath, including scoped package names.
Generate node_modules search directories from path.dirname(importer) up to the filesystem root.
Record every candidate package path and whether it exists.
Stop at the first existing package root and record it as the selected package root.
Add a closest-package-wins note when a nested package shadows an app-level package.
Report package-not-found with importer, package name, and searched directory count when no candidate exists.

Artifact

A bare package lookup trace that shows the full upward search list and the selected package root.

05Read package.json entry fieldsInspect main, type, package boundaries, legacy fallback, and selected module format.

Tasks

Create a package-json helper that reads package.json, returns the parsed object, and records parse or missing-field outcomes.
When exports is absent, resolve main relative to the package root.
Feed main targets through the same file and directory probing code used for relative paths.
If main is missing or invalid, record the invalid target and try index.js, index.json, then index.node.
Store packageRoot, packageName, packageType, and entryField on package reports.
Classify the selected file as ESM or CJS using .mjs, .cjs, and nearest package type rules.
Render package metadata decisions beside filesystem attempts in text output.

Artifact

A package entry trace that explains the selected file, fallback path, package boundary, and module format.

06Explain package exportsTrace package exports for root entries, subpath exports, blocked deep imports, and invalid targets.

Tasks

Route packages with exports through the export map before main is checked.
Normalize package root access to . and package subpaths to ./subpath.
Support string exports and object exports for the package root.
Support direct subpath exports such as ./feature.
Report ERR_PACKAGE_PATH_NOT_EXPORTED when a subpath is absent or mapped to null.
Include packageRoot, requestedSubpath, and availableExports in blocked-subpath evidence.
Reject export targets that escape the package root or use invalid target shapes.

Artifact

An exports resolver that shows matched keys, selected targets, hidden subpaths, and invalid export-target failures.

07Add conditional exportsExplain active condition sets, condition object order, nested condition objects, and selected branches.

Tasks

Build the active condition set for require mode with node, require, module-sync, and default.
Build the active condition set for import mode with node, import, and default.
Add repeated --conditions flags before default while preserving command-line order.
Evaluate condition object entries in insertion order and select the first active branch with a valid target.
Support nested condition objects while recording the branch path, such as node then import.
Render active conditions, skipped branches, matched branches, and selected targets in text output.

Artifact

A condition trace that makes branch order visible and shows why changing mode or custom conditions changes the result.

08Add ESM resolution modeCompare CommonJS-style and ESM-style resolution through explicit require and import modes.

Tasks

Route --mode require to the CommonJS-style resolver and --mode import to a separate ESM-style resolver path.
Return node: URLs for built-ins and file:// URLs for file-backed import-mode results.
Make extensionless relative imports fail in import mode with an extension-required explanation.
Make directory imports fail in import mode with a directory-import-unsupported explanation.
Use import-mode condition sets for package exports resolution.
Add --compare-modes to produce two normal reports and render a compact diff.
Name differences such as extension-required, condition-branch-differs, directory-import-unsupported, and format-differs.

Artifact

A mode-aware resolver that can show why the same specifier resolves differently under require and import.

09Detect CJS and ESM interop hazardsWarn when a successful resolution still creates likely consumer-side module shape problems.

Tasks

Define warning records with type, evidence, and suggestion.
Add consumer-format and imported-name flags, defaulting consumer format from resolver mode.
Warn when an ESM consumer requests a named import from a CJS target with runtime-built exports.
Warn when a CJS consumer requires an ESM target and needs to handle namespace shape or top-level-await risk.
In compare mode, warn when require and import select different files for the same package.
Warn when conditional exports select different module formats for different consumers.
Keep warnings advisory so successful resolution remains successful when warnings exist.

Artifact

Interop warnings that separate resolution success from consumption risk and include evidence plus a suggested fix path.

10Visualize require.cacheRun a fixture in a child process and show which CommonJS modules were loaded and cached.

Tasks

Create a CommonJS cache preload that can read the child process require.cache.
Spawn node --require with the cache preload from npm run cache.
Pass the report path through MODULE_INSPECTOR_CACHE_REPORT.
On process exit, synchronously write cache entries with id, filename, loaded, and children.
Wrap Module._load to record every request, parent filename, resolved filename, and whether the cache entry existed before the load.
Build a loaded-module tree or edge list from cache entries and child links.
Mark repeated requires as cache hits by combining load events with final cache entries.

Artifact

A runtime cache report that shows loaded modules, child edges, repeated requests, and cache-hit evidence from the observed child process.

11Detect circular dependenciesFind cycles in the loaded CommonJS module graph and show partial-load evidence.

Tasks

Normalize cache entries into graph nodes with id, filename, and loaded.
Normalize module.children links into graph edges with from and to.
Run a DFS cycle detector that records paths returning to an active ancestor.
Store each cycle as an ordered path plus the edge that closed the cycle.
Record partial observations when Module._cache already contains a module with loaded false before the original loader runs.
Print cycle participants, final loaded state, and the load event that saw a module before evaluation finished.

Artifact

A cache graph with nodes, edges, cycle paths, closing edges, and partial-export observations.

12Inspect symlink and workspace behaviorShow how symlinks change lookup paths, real paths, and module identity.

Tasks

Read the fixture manifest and report whether the symlink case is available on the platform.
For selected files, store packageLookupPath, resolvedPath, realPath, and cacheIdentityPath.
Use fs.realpathSync.native only after a concrete file exists.
Add --preserve-symlinks and make it change the identity path recorded in the report.
Add notes when resolvedPath differs from realPath, when two specifiers share a real path, or when preserve-symlinks changes identity.
Extend cache mode so the child process can run with preserve-symlinks for comparison.
Record child process flags in cache report metadata.

Artifact

Symlink evidence that compares lookup spelling, real filesystem target, and identity paths for workspace-style packages.

13Generate HTML and Markdown reportsTurn resolver traces, warnings, graph data, cycles, timeline events, and symlink notes into readable reports.

Tasks

Create HTML and Markdown renderer modules that consume report data without rerunning resolution.
Implement inspect-package so it reads importer/specifier pairs from fixtures/generated/app/inspector-input.json.
Build a package report model with summary, traces, warnings, errors, graph, cycles, timeline, and symlinks.
Add timeline events when the resolver classifies a specifier, reads package metadata, selects a branch, emits a warning, or fails.
Write module-inspector.json with all sections, including empty arrays.
Render module-inspector.md with summary rows, stable trace ids, warnings, graph edges, cycles, and symlink notes.
Render self-contained module-inspector.html with escaped file paths, package names, error messages, trace timelines, attempts, package rules, condition checks, warnings, graphs, cycles, and symlink sections.
Keep failed traces in the final report so broken fixtures appear as errors while successful traces still render.

Artifact

A final JSON model plus Markdown and HTML reports generated from the same evidence.

Resolution evidence

The report surface is part of the build.

Lab 04 treats resolver evidence as data: attempted paths, package metadata, condition branches, warnings, runtime cache graphs, cycle paths, symlink notes, and final reports all come from the same model.

attempts[]exact, extension, directory, and package candidates

warnings[]interop risks with evidence and suggestions

errors[]missing files, blocked exports, and invalid targets

graph.nodes[]loaded CommonJS module cache entries

graph.edges[]parent-to-child require relationships

cycles[]ordered circular dependency paths

symlinks[]lookup, realpath, and identity notes

module-inspector.htmlself-contained diagnostic report

Choose your
NodeBook package.

Buy a single volume or lock in every volume at once. Switch between one-reader pricing and team licenses for up to 25 members.

Choose volume

Individual pricing is for one reader and one personal purchase record.

Downloadable book bundle

Digital Bundle

Volume I as EPUB, light and dark PDFs, slides, cheatsheets, and future updates.

$19.99$49.99

One-time purchase

Volume I EPUB for offline reading
Light and dark PDF editions
Slide decks for chapter review
Cheatsheets for quick lookup
Future Digital Bundle updates
Lifetime access to the files

Get Digital Bundle

This is the downloadable Volume I study bundle. It does not include Node Runtime Labs.

Best value

Everything for this volume

NodeBook Pro

Volume I Labs plus its downloadable bundle in one purchase. Save $9.99 vs buying the Digital Bundle and Labs separately.

$49.99$99.99

One-time purchase

Node Runtime LabsDigital Bundle

Everything in Node Runtime Labs
Everything in the Digital Bundle
Volume I labs and book bundle
Future updates for both products
Lifetime access to purchased files

Get NodeBook Pro

Includes both paid products for Volume I.

Premium labs

Complex runtime projects

Node Runtime Labs

Volume I long-form builds with checkpoints, hints, debugging notes, and expected output.

$39.99$79.99

One-time purchase

Volume I runtime lab projects
Phase-by-phase build instructions
Checkpoints, hints, and rubrics
Debugging notes and expected output
Reflection questions
Future lab updates

Get Labs Bundle

This is the paid labs bundle for Volume I. It does not include EPUB, PDFs, slides, or cheatsheets.

See complete pricing breakdown

Other labs in the bundle

Lab 04 sits inside the runtime lab set.

The bundle includes seven runtime projects covering process observation, binary storage, streams, module resolution, file watching, async orchestration, and custom protocols.

Lab 01