Module Isolation Health (7%)

What Are Module Nodes?

In CodeGraph, a Module Node represents an entity in an import statement that the extraction pipeline failed to resolve to either a local repository source file (via relative paths or path aliases) or a declared third-party dependency in package.json.

When the Relationship Extractor encounters an import statement, it follows this resolution order:

1. Relative / Aliased File: Matches an internal file in the repository → creates a FileNode target.
2. Declared Dependency: Package name is found in package.json dependencies or devDependencies → creates a DependencyNode target.
3. Unresolved Fallback: Any import target that fails both lookups above → creates a ModuleNode target.

Why Module Nodes Occur & Why They Have Low Weight (7%)

Module nodes typically appear in two common scenarios:

• Node.js Built-in Modules: Imports like import fs from "fs", import path from "node:path", or import crypto from "crypto". These are native platform APIs provided by the runtime environment and are intentionally omitted from package.json.
• Unlisted or Implicit Dependencies: Imports of packages not explicitly declared in the nearest manifest (e.g., peer dependencies, workspace packages, or missing dependencies).

Module Ratio Calculation

The calculator measures the ratio of module nodes to the total node population in the canonical graph and scores it linearly:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
export function calculateModuleHealth(graph: Graph): ModuleHealthResult {
    const moduleCount = graph.nodesByKind.get("module")?.size ?? 0;
    const totalNodeCount = graph.nodes.size;

    if (totalNodeCount === 0) {
        return {
            score: 100,
            moduleCount: 0,
            totalNodeCount: 0,
            moduleRatio: 0,
        };
    }

    const moduleRatio = moduleCount / totalNodeCount;

    // Linear health score: 100 * (1 - moduleRatio)
    const score = 100 * (1 - moduleRatio);

    return {
        score,
        moduleCount,
        totalNodeCount,
        moduleRatio,
    };
}