fix(javascript): preserve loader ownership and unavailable artifact facts

Preserve missing ASAR companion occurrence identity, declared size and unknown content in graph nodes and resolution limitations. Apply URL text semantics once for ESM lookup while preserving literal CommonJS paths and original specifiers. Keep CJS wrapper var bindings and assignment history, recognizing only untouched wrapper redeclarations.

Validation: real ASAR producer workflow and CLI/MCP path/coverage cases; semantic reassignment controls. Context7 Node documentation and direct Node wrapper execution confirm wrapper behavior.

Fixes #3213
Fixes #3214
Fixes #3223
Related: #3278, #3254

Co-authored-by: Geronimo <varungore1@gmail.com>
Co-authored-by: Paolo Valletta <paovalletta@hotmail.it>

src/domain/javascript/javascriptArtifactFiles.ts

@@ -1,4 +1,5 @@
 import type { JavaScriptSourceSelection } from "./javascriptSourceSelection.js";
+import type { ArtifactOccurrence } from "../artifactGraph.js";
 
 /** Whether an inventoried path has a source extension read by the analyzer. */
 export const isJavaScriptSourcePath = (path: string): boolean =>
@@ -34,9 +35,8 @@ export interface JavaScriptArtifactFile {
 }
 
 /**
- * One inventoried regular file outside the JavaScript-relevant kinds. Its presence
- * was inventoried, including unavailable or unhashed members. The source projection
- * does not read its bytes; references remain present-but-unanalyzed rather than absent.
+ * One inventoried regular file not backed by analyzed source bytes. Its inventory
+ * occurrence remains available even when content is opaque or unavailable.
  */
 export interface JavaScriptUnanalyzedArtifactFile {
   readonly path: string;
@@ -44,6 +44,14 @@ export interface JavaScriptUnanalyzedArtifactFile {
   readonly sha256: string | null;
   readonly bytes: number | null;
   readonly inventory_artifact_id: string | null;
+  readonly inventory_occurrence_id?: string;
+  readonly kind?: JavaScriptArtifactFileKind;
+  readonly artifact_kind?: ArtifactOccurrence["artifact_kind"];
+  readonly hash_status?:
+    | "verified"
+    | "mismatched"
+    | "not-hashed"
+    | "unavailable";
   readonly limitations?: readonly string[];
 }
 
@@ -66,6 +74,8 @@ export interface JavaScriptArtifactFileSet {
   readonly files: readonly JavaScriptArtifactFile[];
   /** Borrowed inventory lookup for regular files the source projection does not read. */
   readonly unanalyzed_files?: JavaScriptUnanalyzedArtifactLookup;
+  /** Relevant inventoried files whose bytes were unavailable. */
+  readonly unavailable_relevant_files: readonly JavaScriptUnanalyzedArtifactFile[];
   readonly containers: readonly JavaScriptArtifactContainer[];
   readonly text_bytes_read: number;
   readonly invalid_utf8_files: number;

src/domain/javascript/javascriptModuleResolutionMode.ts

@@ -16,7 +16,7 @@ export const moduleResolutionModeForJavaScriptReference = (
   if (referenceKind === "require") return "require";
   if (referenceKind === "dynamic-import") return "import";
   const extension = posix.extname(sourcePath).toLowerCase();
-  if (extension === ".cts") return "require";
+  if (extension === ".cjs" || extension === ".cts") return "require";
   if (extension === ".mts") return "import";
   if (extension === ".ts" || extension === ".tsx") return "compiler-dependent";
   return "import";

src/domain/javascript/javascriptSemanticAnalysis.require_links.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 
-import { analyzeJavaScriptSemantics } from "./javascriptSemanticAnalysis.js";
+import {
+  analyzeJavaScriptSemantics,
+  analyzeParsedJavaScriptSemantics,
+} from "./javascriptSemanticAnalysis.js";
+import { parseJavaScriptSource } from "./javascriptSourceParser.js";
+import { moduleResolutionModeForJavaScriptReference } from "./javascriptModuleResolutionMode.js";
 import {
   origin,
   topLevelBinding,
@@ -56,6 +61,74 @@ describe("TypeScript import-equals links", () => {
   });
 });
 
+describe("CommonJS wrapper parameter redeclarations", () => {
+  it("retains ambient exports and require through uninitialized top-level vars", () => {
+    const path = "app/main.cjs";
+    const parsed = parseJavaScriptSource(
+      'var module, exports, require; module.exports = require("./dependency.cjs");',
+      path,
+    );
+    expect(parsed).not.toBeNull();
+    const ir = analyzeParsedJavaScriptSemantics(
+      parsed!,
+      moduleResolutionModeForJavaScriptReference(path, "static-import"),
+    );
+    expect(ir.moduleLinks).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: "commonjs-export",
+          specifier: "./dependency.cjs",
+          localName: null,
+          exportedName: "default",
+        }),
+      ]),
+    );
+  });
+
+  it("retains the Node loader call on an uninitialized wrapper var assignment RHS", () => {
+    const path = "app/main.cjs";
+    const parsed = parseJavaScriptSource(
+      'var require; require = require("./bootstrap.cjs");',
+      path,
+    );
+    expect(parsed).not.toBeNull();
+    const ir = analyzeParsedJavaScriptSemantics(
+      parsed!,
+      moduleResolutionModeForJavaScriptReference(path, "static-import"),
+    );
+    expect(ir.moduleLinks).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: "require",
+          specifier: "./bootstrap.cjs",
+        }),
+      ]),
+    );
+  });
+
+  it.each([
+    'var require = local; require("./dependency.cjs");',
+    'var require; require = replacement; require("./dependency.cjs");',
+    "var module; module = replacement; module.exports = 1;",
+    "var exports; exports = replacement; exports.value = 1;",
+    'let require; require("./dependency.cjs");',
+    'function nested() { var require; require("./dependency.cjs"); }',
+  ])("keeps non-wrapper declarations as shadows: %s", (source) => {
+    const path = "app/main.cjs";
+    const parsed = parseJavaScriptSource(source, path);
+    expect(parsed).not.toBeNull();
+    const ir = analyzeParsedJavaScriptSemantics(
+      parsed!,
+      moduleResolutionModeForJavaScriptReference(path, "static-import"),
+    );
+    expect(
+      ir.moduleLinks.filter(
+        ({ kind }) => kind === "require" || kind === "commonjs-export",
+      ),
+    ).toEqual([]);
+  });
+});
+
 describe("TypeScript type-only module links", () => {
   it("retains declarations without runtime bindings or callable claims", () => {
     const ir = analyzeJavaScriptSemantics(`

src/domain/javascript/javascriptSemanticRequireOrigin.ts

@@ -5,6 +5,7 @@ import { BUILTIN_RESOURCE_METHODS } from "./javascriptBuiltinResourceMethods.js"
 import type { JavaScriptModuleOrigin } from "./javascriptSemanticIr.js";
 import {
   resolveSemanticBindingState,
+  isUnmodifiedCommonJsWrapperBinding,
   semanticResolutionBlocked,
   semanticStableInitializer,
   type JavaScriptSemanticAnalysisState,
@@ -46,13 +47,7 @@ export const semanticRequireLoaderAt = (
     return binding.initializers.length === 0 ? "factory-loader" : "unknown";
   if (isWrapperRequireInitializerCall(binding, node, state))
     return "commonjs-loader";
-  const scope = state.scopesById.get(binding.scopeId);
-  if (
-    scope?.kind === "program" &&
-    binding.declarationKinds.size > 0 &&
-    [...binding.declarationKinds].every((kind) => kind === "var") &&
-    binding.initializers.length === 0
-  )
+  if (isUnmodifiedCommonJsWrapperBinding(node.callee, "require", state))
     return "commonjs-loader";
   if (isSemanticCreateRequireBinding(binding, state)) return "create-require";
   const initializer = semanticStableInitializer(binding, state)?.node;
@@ -214,10 +209,9 @@ const writesModuleRequire = (
     const value = unwrapJavaScriptExpression(node).node;
     if (!t.isIdentifier(value)) return false;
     if (value.name === "module")
-      return (
-        resolveSemanticBindingState(state, value, "module") === undefined &&
-        !semanticResolutionBlocked(state, value, "module")
-      );
+      return resolveSemanticBindingState(state, value, "module") === undefined
+        ? !semanticResolutionBlocked(state, value, "module")
+        : isUnmodifiedCommonJsWrapperBinding(value, "module", state);
     const binding = resolveSemanticBindingState(state, value, value.name);
     if (binding === undefined || visited.has(binding.bindingId)) return false;
     const next = new Set(visited).add(binding.bindingId);
@@ -453,10 +447,17 @@ export const semanticRequireOrigin = (
     )
   )
     return undefined;
+  const requireBinding = resolveSemanticBindingState(
+    state,
+    current.callee,
+    "require",
+  );
   if (
-    resolveSemanticBindingState(state, current.callee, "require") !==
-      undefined ||
-    semanticResolutionBlocked(state, current.callee, "require") ||
+    (requireBinding !== undefined &&
+      !isUnmodifiedCommonJsWrapperBinding(current.callee, "require", state) &&
+      !isWrapperRequireInitializerCall(requireBinding, current, state)) ||
+    (requireBinding === undefined &&
+      semanticResolutionBlocked(state, current.callee, "require")) ||
     (state.ambientBindingWrites.get("require") ?? []).some(
       (write) =>
         !semanticTopLevelEffectFollowsCapture(

src/domain/javascript/javascriptSemanticState.ts

@@ -253,5 +253,28 @@ export const isUnshadowedGlobal = (
   name: string,
 ): boolean =>
   t.isIdentifier(node, { name }) &&
-  resolveSemanticBindingState(state, node, name) === undefined &&
-  !semanticResolutionBlocked(state, node, name);
+  (resolveSemanticBindingState(state, node, name) === undefined
+    ? !semanticResolutionBlocked(state, node, name)
+    : isUnmodifiedCommonJsWrapperBinding(node, name, state));
+
+/** A program-level `var` redeclaration still denotes its untouched CJS wrapper parameter. */
+export const isUnmodifiedCommonJsWrapperBinding = (
+  node: t.Node,
+  name: string,
+  state: JavaScriptSemanticAnalysisState,
+): boolean => {
+  if (
+    state.staticImportResolutionMode !== "require" ||
+    !["module", "exports", "require"].includes(name) ||
+    !t.isIdentifier(node, { name })
+  )
+    return false;
+  const binding = resolveSemanticBindingState(state, node, name);
+  if (binding === undefined || binding.initializers.length !== 0) return false;
+  const scope = state.scopesById.get(binding.scopeId);
+  return (
+    scope?.kind === "program" &&
+    binding.declarationKinds.size > 0 &&
+    [...binding.declarationKinds].every((kind) => kind === "var")
+  );
+};