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/application/javascript/JavaScriptArtifactAnalysis.sourceMaps.test.ts

@@ -28,6 +28,7 @@ it("retains batched TraceMap-resolved paths and null source positions", () => {
         text: { included: true, value: sourceMapText },
       },
     ],
+    unavailable_relevant_files: [],
     containers: [],
     text_bytes_read: Buffer.byteLength(sourceMapText),
     invalid_utf8_files: 0,

src/application/javascript/JavaScriptArtifactGraphBuilder.ts

@@ -178,6 +178,7 @@ const graphCoverage = (context: JavaScriptArtifactGraphContext) => {
   );
   const unknownGap =
     (context.fileSet.source_selection?.unselected_files ?? 0) > 0 ||
+    context.fileSet.unavailable_relevant_files.length > 0 ||
     context.analysis.files.some(
       ({ analysis_failure, application_projection_failure }) =>
         analysis_failure !== undefined ||

src/application/javascript/JavaScriptArtifactGraphStructure.ts

@@ -1,7 +1,10 @@
 import type { ArtifactInventorySnapshot } from "../../domain/artifactInventorySnapshot.js";
 import type { ApplicationNode } from "../../domain/javascript/javascriptApplicationGraphSchemas.js";
 import { htmlInlineScriptLimitation } from "./JavaScriptArtifactAnalysis.js";
-import { completeApplicationCoverage } from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js";
+import {
+  completeApplicationCoverage,
+  partialApplicationCoverage,
+} from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js";
 import type { JavaScriptModuleArtifactAnalysis } from "./JavaScriptArtifactAnalysisTypes.js";
 import { jsonValueSchema } from "../../domain/jsonValue.js";
 import { freezeJsonSnapshot } from "../../domain/immutableJson.js";
@@ -300,8 +303,133 @@ export const addJavaScriptArtifactFiles = (
         },
       });
   }
+  addUnavailableAsarEntries(context);
 };
 
+const addUnavailableAsarEntries = (
+  context: JavaScriptArtifactGraphContext,
+): void => {
+  for (const file of context.fileSet.unavailable_relevant_files) {
+    if (!isAsarContainer(context, file.container_sha256)) continue;
+    const limitations = [
+      ...(file.limitations ?? []),
+      `The inventoried ${file.kind ?? "relevant"} entry has unavailable bytes; no content artifact identity can be established.`,
+    ];
+    const entry = context.accumulator.addNode({
+      kind: "asar-entry",
+      identity: {
+        strategy: "canonical-path",
+        stability: "artifact-version",
+        artifact_sha256: file.container_sha256,
+        path: file.path,
+      },
+      observations: [
+        {
+          label: file.path,
+          properties: {
+            entry_sha256: file.sha256,
+            bytes: file.bytes,
+            inventory_artifact_id: file.inventory_artifact_id,
+            ...(file.inventory_occurrence_id === undefined
+              ? {}
+              : { inventory_occurrence_id: file.inventory_occurrence_id }),
+            hash_status: file.hash_status,
+            artifact_kind: file.artifact_kind,
+            ...(file.kind === undefined ? {} : { kind: file.kind }),
+            content_available: false,
+          },
+          evidence: artifactObservationEvidence({
+            sha256: file.container_sha256,
+            path: file.path,
+            operation: "inventory-asar-unavailable-entry",
+            coverage: partialApplicationCoverage([], null),
+            limitations,
+          }),
+        },
+      ],
+    });
+    const parent =
+      context.containerNodes.get(file.container_sha256) ?? context.root;
+    context.accumulator.addEdge({
+      source_node_id: parent.node_id,
+      target_node_id: entry.node_id,
+      relation: "contains",
+      properties: {
+        path: file.path,
+        content_available: false,
+        hash_status: file.hash_status,
+      },
+      evidence: artifactObservationEvidence({
+        sha256: file.container_sha256,
+        path: file.path,
+        operation: "inventory-asar-unavailable-entry",
+        coverage: partialApplicationCoverage([], null),
+        limitations,
+      }),
+    });
+    if (file.kind === "native-addon" || file.artifact_kind === "native-addon") {
+      const addon = context.accumulator.addNode({
+        kind: "native-addon",
+        identity: {
+          strategy: "canonical-path",
+          stability: "artifact-version",
+          artifact_sha256: file.container_sha256,
+          path: file.path,
+        },
+        observations: [
+          {
+            label: file.path,
+            properties: {
+              availability: "unavailable",
+              ...(file.hash_status === undefined
+                ? {}
+                : { hash_status: file.hash_status }),
+              ...(file.artifact_kind === undefined
+                ? {}
+                : { artifact_kind: file.artifact_kind }),
+              bytes: file.bytes,
+              inventory_artifact_id: file.inventory_artifact_id,
+              ...(file.inventory_occurrence_id === undefined
+                ? {}
+                : { inventory_occurrence_id: file.inventory_occurrence_id }),
+            },
+            evidence: artifactObservationEvidence({
+              sha256: file.container_sha256,
+              path: file.path,
+              operation: "classify-unavailable-native-addon",
+              coverage: partialApplicationCoverage([], null),
+              limitations,
+            }),
+          },
+        ],
+      });
+      context.accumulator.addEdge({
+        source_node_id: entry.node_id,
+        target_node_id: addon.node_id,
+        relation: "contains",
+        properties: {
+          classification: "native-addon",
+          content_available: false,
+        },
+        evidence: artifactObservationEvidence({
+          sha256: file.container_sha256,
+          path: file.path,
+          operation: "classify-unavailable-native-addon",
+          coverage: partialApplicationCoverage([], null),
+          limitations,
+        }),
+      });
+    }
+  }
+};
+
+const isAsarContainer = (
+  context: JavaScriptArtifactGraphContext,
+  containerSha256: string,
+): boolean =>
+  context.snapshot.manifest.root_format === "asar" ||
+  containerSha256 !== context.snapshot.manifest.root_sha256;
+
 const sourceFileRange = (
   file: JavaScriptArtifactFile,
 ): JavaScriptSourceRange => {
@@ -464,10 +592,7 @@ const createAsarEntry = (
   context: JavaScriptArtifactGraphContext,
   file: JavaScriptArtifactFile,
 ): ApplicationNode | undefined => {
-  const isAsar =
-    context.snapshot.manifest.root_format === "asar" ||
-    file.container_sha256 !== context.snapshot.manifest.root_sha256;
-  if (!isAsar) return undefined;
+  if (!isAsarContainer(context, file.container_sha256)) return undefined;
   return context.accumulator.addNode({
     kind: "asar-entry",
     identity: {

src/application/javascript/JavaScriptArtifactPathResolution.test.ts

@@ -68,6 +68,56 @@ describe("artifact-local graph identity", () => {
 });
 
 describe("loader-owned path lookup", () => {
+  it("applies URL whitespace handling only to ESM lookup and retains declarations", () => {
+    const tab = "\t";
+    const files = fileMap([
+      file("app/entry.mjs", "root"),
+      file("app/feature.js", "root"),
+      file(`app/tab${tab}name.js`, "root"),
+    ]);
+    for (const whitespace of ["\t", "\n", "\r"]) {
+      const raw = `./fea${whitespace}ture.js`;
+      expect(
+        resolve({
+          declaredPath: raw,
+          sourcePath: "app/entry.mjs",
+          context: "module-specifier",
+          moduleKind: "import",
+          files,
+        }),
+      ).toMatchObject({ declared_path: raw, resolved_path: "app/feature.js" });
+    }
+    expect(
+      resolve({
+        declaredPath: `./tab${tab}name.js`,
+        sourcePath: "app/entry.mjs",
+        context: "module-specifier",
+        moduleKind: "import",
+        files,
+      }),
+    ).toMatchObject({ resolved_path: null });
+    expect(
+      resolve({
+        declaredPath: `./tab${tab}name.js`,
+        sourcePath: "app/entry.cjs",
+        context: "module-specifier",
+        moduleKind: "require",
+        files,
+      }),
+    ).toMatchObject({ resolved_path: "app/tab\tname.js" });
+    expect(
+      resolve({
+        declaredPath: "./tab%09name.js",
+        sourcePath: "app/entry.mjs",
+        context: "module-specifier",
+        moduleKind: "import",
+        files,
+      }),
+    ).toMatchObject({ resolved_path: "app/tab\tname.js" });
+  });
+});
+
+describe("loader-specific module suffix lookup", () => {
   it("keeps relative ESM imports exact", () => {
     const files = fileMap([
       file("app/entry.mjs", "root"),
@@ -186,6 +236,42 @@ describe("loader-owned path lookup", () => {
   });
 });
 
+describe("unavailable inventoried native add-ons", () => {
+  it("retains an inventoried native add-on whose bytes are unavailable", () => {
+    const unavailable = {
+      path: "app/addon.node",
+      container_sha256: file("app/entry.cjs", "root").container_sha256,
+      sha256: null,
+      bytes: 8192,
+      inventory_artifact_id: null,
+      inventory_occurrence_id: "missing-addon-occurrence",
+      kind: "native-addon" as const,
+      hash_status: "unavailable" as const,
+      limitations: ["unpacked companion is missing"],
+    };
+    const result = resolve({
+      declaredPath: "./addon.node",
+      sourcePath: "app/entry.cjs",
+      context: "module-specifier",
+      moduleKind: "require",
+      files: fileMap([file("app/entry.cjs", "root")]),
+      unanalyzedFiles: {
+        get: (path) => (path === unavailable.path ? unavailable : undefined),
+        hasDirectory: () => false,
+      },
+    });
+    expect(result).toMatchObject({
+      declared_path: "./addon.node",
+      resolution_status: "unavailable",
+      candidate_path: "app/addon.node",
+      limitations: [
+        "unpacked companion is missing",
+        expect.stringContaining("inventoried native-addon file"),
+      ],
+    });
+  });
+});
+
 describe("bare package root file lookup", () => {
   it("uses loader-specific bare package roots when only a sibling .js file exists", () => {
     const absentDirectory = fileMap([

src/application/javascript/JavaScriptArtifactPathResolution.ts

@@ -499,6 +499,7 @@ const contextualCandidate = (
   }
   const hasUrlPathSemantics =
     context === "module-specifier" && input.moduleKind === "import";
+  if (hasUrlPathSemantics) declared = htmlUrlText(declared);
   const rejected = rejectDeclaration(
     declared,
     declaresLiteralPercent(input) || hasUrlPathSemantics,
@@ -1400,7 +1401,9 @@ const findFileCandidate = (
       candidatePath: path,
       limitations: [
         ...(unanalyzed.limitations ?? []),
-        `${path} exists in the inventoried artifact container (sha256 ${unanalyzed.sha256 ?? "unknown"}, ${unanalyzed.bytes === null ? "unknown size" : `${String(unanalyzed.bytes)} bytes`}) but is not a JavaScript, JSON, HTML, source map, or native add-on file; its contents were not analyzed.`,
+        unanalyzed.kind === undefined
+          ? `${path} exists in the inventoried artifact container (sha256 ${unanalyzed.sha256 ?? "unknown"}, ${unanalyzed.bytes === null ? "unknown size" : `${String(unanalyzed.bytes)} bytes`}) but is not a JavaScript, JSON, HTML, source map, or native add-on file; its contents were not analyzed.`
+          : `${path} is an inventoried ${unanalyzed.kind} file, but its bytes are unavailable (hash status ${unanalyzed.hash_status ?? "unknown"}); resolution cannot be confirmed.`,
       ],
     };
   return null;

src/application/javascript/JavaScriptArtifactReconstruction.ts

@@ -261,7 +261,8 @@ export const reconstructJavaScriptArtifact = async (
           ),
         ),
         statistics: {
-          relevant_files: files.files.length,
+          relevant_files:
+            files.files.length + files.unavailable_relevant_files.length,
           nested_asar_containers: files.containers.length,
           text_bytes_read: files.text_bytes_read,
           invalid_utf8_files: files.invalid_utf8_files,