Struct ModuleGraph 

pub struct ModuleGraph {
    pub modules: Vec<ModuleNode>,
    pub package_usage: FxHashMap<String, Vec<FileId>>,
    pub type_only_package_usage: FxHashMap<String, Vec<FileId>>,
    pub entry_points: FxHashSet<FileId>,
    pub runtime_entry_points: FxHashSet<FileId>,
    pub test_entry_points: FxHashSet<FileId>,
    pub reverse_deps: Vec<Vec<FileId>>,
    pub re_export_cycles: Vec<GraphReExportCycle>,
    /* private fields */
}

The core module dependency graph.

Derives serde so the whole graph can be persisted to .fallow/graph-cache.bin (see crate::cache) and skipped on a re-run whose inputs are byte-identical. namespace_imported is a derived FixedBitSet reconstructed from the edge set on cache load (reconstruct_namespace_imported), so it is #[serde(skip, default)] rather than persisted.

Fields

modules: Vec<ModuleNode>

All modules indexed by FileId.

Invariant: modules[file_id.0 as usize].file_id == file_id for every FileId in the graph. Holds because discover/walk.rs assigns FileIds sequentially via .enumerate() after path-sorting, and build::populate_edges pushes one ModuleNode per file in iteration order. Detectors rely on this for O(1) FileId-to-module lookup (graph.modules.get(file_id.0 as usize)) instead of building a per-call FxHashMap<FileId, &ModuleNode>.

package_usage: FxHashMap<String, Vec<FileId>>

Maps npm package names to the set of FileIds that import them.

type_only_package_usage: FxHashMap<String, Vec<FileId>>

Maps npm package names to the set of FileIds that import them with type-only imports. A package appearing here but not in package_usage (or only in both) indicates it’s only used for types and could be a devDependency.

entry_points: FxHashSet<FileId>

All entry point FileIds.

runtime_entry_points: FxHashSet<FileId>

Runtime/application entry point FileIds.

test_entry_points: FxHashSet<FileId>

Test entry point FileIds.

reverse_deps: Vec<Vec<FileId>>

Reverse index: for each FileId, which files import it.

re_export_cycles: Vec<GraphReExportCycle>

Re-export cycles and self-loops detected during Phase 4 chain resolution. Each entry names the participating files (sorted lexicographically) and a is_self_loop flag distinguishing single-file self-re-exports from multi-node cycles. Populated by re_exports::find_re_export_cycles and consumed by the analysis backend, which wraps each entry in a typed ReExportCycleFinding.

Implementations

impl ModuleGraph

pub fn ambiguous_star_exports(&self) -> Vec<AmbiguousStarExport>

Every export * collision in the project, sorted deterministically.

pub fn ambiguous_star_exports_on( &self, file_id: FileId, ) -> Vec<AmbiguousStarExport>

export * collisions on one module, for single-symbol queries.

pub fn ambiguity_participants(&self) -> AmbiguityParticipants

Declarations that lost export credit to a collision anywhere in the project.

impl ModuleGraph

pub fn find_cycles(&self) -> Vec<Vec<FileId>>

Find all circular dependency cycles in the module graph.

Uses an iterative implementation of Tarjan’s strongly connected components algorithm (O(V + E)) to find all SCCs with 2 or more nodes. Each such SCC represents a set of files involved in a circular dependency.

Returns cycles sorted by length (shortest first), with files within each cycle sorted by path for deterministic output.

Panics

Panics if the internal file-to-path lookup is inconsistent with the module list.

impl ModuleGraph

pub fn effective_re_export_routes( &self, source_file: FileId, source_name: &str, namespace: ExportNamespace, ) -> Vec<EffectiveReExportRoute>

Every effective outward route from one exported binding.

Routes carry aliases across named re-exports, omit ambiguous and shadowed paths, deduplicate convergent diamonds, and terminate on cycles.

impl ModuleGraph

pub fn focus_file_facts(&self, changed: &[FileId]) -> Vec<FocusFileFacts>

Compute the per-file focus graph facts (fan-in/out + the two confidence-flag signals) for a changed-file seed set.

Out-of-range or duplicate ids in changed are tolerated (dropped / deduped). Each fact is keyed by the changed file’s FileId; the caller relativizes via ModuleGraph::focus_facts_with_paths for serialization.

pub fn focus_facts_with_paths( &self, facts: &[FocusFileFacts], root: &Path, ) -> Vec<FocusFileFactsPaths>

Resolve a FocusFileFacts set’s FileIds to root-relative, forward- slashed paths, sorted for deterministic output. Files whose module is missing are dropped.

impl ModuleGraph

pub fn impact_closure(&self, changed: &[FileId]) -> ImpactClosure

Compute the impact closure for a changed-file seed set.

BFS over reverse_deps from every changed file yields the transitive affected set; the seed partitions into in_diff, the rest into affected_not_shown. The coordination gap walks each changed file’s exported-symbol references and reports those whose consumer is outside the diff (rule R2: one entry per distinct consumer module).

changed is a slice of FileIds; out-of-range or duplicate ids are tolerated. Type-only re-export edges are skipped for the gap evidence so a import type-only consumer (erased at build, no runtime contract) does not fire.

pub fn closure_with_paths( &self, closure: &ImpactClosure, root: &Path, ) -> ImpactClosurePaths

Resolve a closure’s FileIds to root-relative, forward-slashed paths, sorted for deterministic output. Files whose module is missing are dropped.

impl ModuleGraph

pub fn partition_order(&self, changed: &[FileId]) -> PartitionOrder

Compute the by-module partition and dependency-sensible order for a changed-file seed set.

Out-of-range or duplicate ids in changed are tolerated (dropped / deduped). The partition groups each changed file by its parent directory; the order is a deterministic topological sort over the inter-unit DAG (definitions before consumers, ties broken by the module_dir sort).

pub fn partition_order_with_paths( &self, partition: &PartitionOrder, root: &Path, ) -> PartitionOrderPaths

Resolve a partition + order’s FileIds to root-relative, forward-slashed paths, sorted for deterministic output. Files whose module is missing are dropped; a unit left empty after that drop is omitted. The module_dir keys (and the order entries, which are module_dir strings) are root-relativized too so the whole shape is root-relative.

impl ModuleGraph

pub fn public_export_keys( &self, public_api_entry_points: &FxHashSet<FileId>, root: &Path, ) -> FxHashSet<String>

Compute the set of public-export keys reachable through the given public_api_entry_points (an exports-aware set; see module docs).

Keys are "<root-relative forward-slashed path>::<export name>". Type-only exports are skipped: a type erased at build carries no runtime contract, so it never widens the public value surface that 6.A tracks.

pub fn public_export_origins( &self, public_api_entry_points: &FxHashSet<FileId>, ) -> FxHashSet<PublicExportOrigin>

Resolve the direct declarations exposed through public package entries. Shadowed and ambiguous star candidates contribute no origins.

pub fn public_export_origins_in_namespace( &self, public_api_entry_points: &FxHashSet<FileId>, namespace: ExportNamespace, ) -> FxHashSet<PublicExportOrigin>

Resolve direct declarations exposed through public package entries in one export namespace.

Type-only public surfaces matter to structural consumers such as class member analysis, while runtime consumers can continue to request only the value namespace.

pub fn public_export_bindings( &self, public_api_entry_points: &FxHashSet<FileId>, ) -> FxHashSet<EffectiveExportBinding>

Unique value bindings exposed through at least one public package entry.

pub fn public_export_declaration_bindings( &self, public_api_entry_points: &FxHashSet<FileId>, ) -> FxHashSet<EffectiveExportBinding>

Direct declaration bindings exposed through public entries, including declarations nested under public namespace-object exports.

impl ModuleGraph

pub fn build( resolved_modules: &[ResolvedModule], entry_points: &[EntryPoint], files: &[DiscoveredFile], ) -> Self

Build the module graph from resolved modules and entry points.

pub fn build_with_reachability_roots( resolved_modules: &[ResolvedModule], entry_points: &[EntryPoint], runtime_entry_points: &[EntryPoint], test_entry_points: &[EntryPoint], files: &[DiscoveredFile], ) -> Self

Build the module graph with explicit runtime and test reachability roots.

pub fn build_with_reachability_roots_and_replacements( resolved_modules: &[ResolvedModule], replaced_module_targets: &[ResolvedReplacedModuleTarget], entry_points: &[EntryPoint], runtime_entry_points: &[EntryPoint], test_entry_points: &[EntryPoint], files: &[DiscoveredFile], ) -> Self

Build the module graph with root-specific test-time module replacements.

pub const fn module_count(&self) -> usize

Total number of modules.

pub const fn edge_count(&self) -> usize

Total number of edges.

pub fn is_test_reachable(&self, file_id: FileId) -> bool

Return whether any test-root traversal reaches file_id.

pub fn is_test_reference_covered( &self, export: &ExportSymbol, reference_index: usize, ) -> bool

Return whether one test-root traversal covers the export reference at reference_index on export.

Coverage requires one profile that reaches the referencing file and every target hop. ESM hops also require that profile not to replace the hop target; CommonJS hops remain active because Vitest replacement mocks do not intercept require().

pub fn is_any_test_reference_covered(&self, export: &ExportSymbol) -> bool

Return whether any reference on export is covered by a test-root traversal.

pub fn resolve_export( &self, file_id: FileId, name: &str, namespace: ExportNamespace, ) -> EffectiveExportResolution

Resolve the effective declaration exported under name in one namespace.

This is the canonical graph contract for direct exports and every named or star re-export path. Missing and ambiguous bindings are explicit so consumers cannot accidentally credit an arbitrary source declaration.

pub fn effective_bindings_share_declaration_group( &self, left: EffectiveExportBinding, right: EffectiveExportBinding, ) -> bool

Whether two effective bindings denote the same declaration surface.

TypeScript declaration merges occupy separate export slots while representing one symbol. Consumers that compare type and value lanes use this instead of raw binding equality so either half can carry the reference credit for the merged declaration.

pub fn resolve_export_origin( &self, file_id: FileId, name: &str, namespace: ExportNamespace, ) -> Option<EffectiveExportOrigin<'_>>

Resolve one exported name to its unique direct declaration.

Missing and ambiguous bindings return None. Namespace-object exports are bindings in their own right rather than direct declarations, so they also have no declaration origin.

pub fn effective_export_surface( &self, file_id: FileId, name: &str, namespace: ExportNamespace, ) -> Option<EffectiveExportSurface<'_>>

Resolve one module surface to its canonical binding and reference-bearing graph export. Value and type namespaces are selected independently.

pub fn effective_export_surface_re_export( &self, file_id: FileId, name: &str, namespace: ExportNamespace, ) -> Option<&ReExportEdge>

Local re-export specifier that owns one effective module surface.

Direct declarations and star-only forwarded surfaces return None. Named and namespace re-exports return the namespace-compatible edge whose source resolves to the same canonical binding.

pub fn effective_export_surface_references( &self, file_id: FileId, name: &str, namespace: ExportNamespace, ) -> Vec<&SymbolReference>

References that reach one exact module export surface.

Star-only surfaces share their declaration with other barrels, so their origin references are filtered by recorded provenance instead of being borrowed wholesale from the declaration.

pub fn export_binding_origin( &self, binding: EffectiveExportBinding, ) -> Option<EffectiveExportOrigin<'_>>

Resolve a unique binding to its direct declaration, when it has one.

pub fn unique_export_bindings( &self, file_id: FileId, namespace: ExportNamespace, ) -> FxHashSet<EffectiveExportBinding>

Unique bindings exposed by a module in one namespace.

Multiple names that resolve to the same declaration are deduplicated; missing and ambiguous exports are excluded.

pub fn importer_connects_export_origin( &self, importer: FileId, source: FileId, name: &str, namespace: ExportNamespace, ) -> bool

Whether importer connects to source as an origin of name.

Any direct import connects the two modules for duplicate-export grouping, even when it imports a different symbol. A re-export-only edge connects them only when it contributes this binding, including each contributor to an ambiguous star export and excluding star bindings shadowed by an explicit export.

pub fn has_namespace_import(&self, file_id: FileId) -> bool

Check if any importer uses import * as ns for this module. Uses precomputed bitset, O(1) lookup.

pub fn edges_for(&self, file_id: FileId) -> Vec<FileId>

Get the target FileIds of all outgoing edges for a module.

pub fn outgoing_symbol_edges( &self, file_id: FileId, ) -> impl Iterator<Item = (FileId, &[ImportedSymbol])> + '_

Iterate the outgoing edges of file_id with full per-symbol data.

fallow trace needs the raw ImportedSymbol set on each edge in both directions, which the flattened summary structs cannot express. Returns an empty iterator for out-of-range file ids.

pub fn importers_of(&self, target: FileId) -> &[FileId]

The importer FileIds that directly import target (reverse-dep view).

Returns an empty slice when target is out of range.

pub fn direct_importer_summaries( &self, target: FileId, ) -> Vec<DirectImporterSummary>

Summarize files that directly import target.

Uses existing reverse dependency and edge indexes. Returns an empty list when the target is out of range or has no importers.

pub fn find_import_span_start( &self, source: FileId, target: FileId, ) -> Option<u32>

Find the byte offset of the import statement from source to target.

Mixed type/value imports to the same target are stored as one edge. Prefer the first value-carrying import so runtime-cycle diagnostics and line suppressions anchor on the import that actually participates in the cycle. Returns None if no edge exists or the edge has no symbols.

pub fn outgoing_edge_summaries( &self, file_id: FileId, ) -> impl Iterator<Item = (FileId, bool, Option<u32>)> + '_

Iterate outgoing edges with the data the boundary detector needs in a single pass: target file id, whether every symbol on the edge is type-only (matches the predicate used by cycle detection), and the span start of the first value-carrying symbol (or the first symbol when every symbol is type-only).

When featureB has both import type { Foo } from './x' and import { bar } from './x', fallow groups them into ONE edge with the type-only symbol first and the value symbol second. Consumers need the value span so findings anchor on the runtime import line; otherwise a // fallow-ignore-next-line above the type-only line would silently suppress the real violation.

Returns an empty iterator for out-of-range file ids.

pub fn outgoing_edge_summaries_with_exclusions<'a>( &'a self, file_id: FileId, excluded_span_starts: &'a FxHashSet<u32>, ) -> impl Iterator<Item = (FileId, bool, Option<u32>, bool)> + 'a

Like Self::outgoing_edge_summaries but additionally reports, as a fourth boolean, whether EVERY non-type-only symbol on the edge has an import_span start in excluded_span_starts (all_client_only). The security client-server-leak BFS passes the next/dynamic ssr:false dynamic-import span starts so it can skip an edge reached ONLY through the client-only escape hatch. An edge with no non-type-only symbols, or with at least one non-type-only symbol whose span is not excluded, reports false (so a target also reached via a real static import stays in the cone).

Returns an empty iterator for out-of-range file ids.

Trait Implementations

impl Debug for ModuleGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ModuleGraph

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ModuleGraph

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.