diff --git a/docs/javascript-application-graph.md b/docs/javascript-application-graph.md index 2290491a5..48e17bf44 100644 --- a/docs/javascript-application-graph.md +++ b/docs/javascript-application-graph.md @@ -104,6 +104,15 @@ static inferences. Dynamic or ambiguous IPC is retained without a pairing edge. Runtime entities retain passive-CDP authority, while a successful static/runtime correspondence is a separately identified cross-layer inference. +Source module links retain their resolution mode. Static imports in `.ts` and +`.tsx` are `compiler-dependent` when compiler options have not been retained. +REA compares Node import and require resolution: a shared outcome remains +available with a limitation; divergent outcomes remain unavailable with both +conditional branches and their limitations. This models source relationships, +not verified emitted code or execution. A declaration file found only through +an emitted-extension fallback is retained as a candidate, not a runtime target; +an explicitly selected path keeps its original identity. + ## Evidence and authority Every observation and edge carries all of the following: diff --git a/src/application/ReferenceSourceImportEntries.ts b/src/application/ReferenceSourceImportEntries.ts index a6e962118..36dae9949 100644 --- a/src/application/ReferenceSourceImportEntries.ts +++ b/src/application/ReferenceSourceImportEntries.ts @@ -104,7 +104,11 @@ const resolveInternalSpecifier = ( ]); // Retain present runtime files first; substitute only a missing counterpart. // Counterparts cover explicit filenames, not directory/index resolution. - candidates.push(...typescriptEmittedSourceCandidates(fromPath, normalized)); + candidates.push( + ...typescriptEmittedSourceCandidates(fromPath, normalized).map( + ({ path }) => path, + ), + ); const match = lookupPath.resolveCandidates(candidates); return match === undefined ? { to: normalized, resolution: "unresolved" } diff --git a/src/application/TypeScriptEmittedSourceCandidates.ts b/src/application/TypeScriptEmittedSourceCandidates.ts index 663c7dada..0e7adf41c 100644 --- a/src/application/TypeScriptEmittedSourceCandidates.ts +++ b/src/application/TypeScriptEmittedSourceCandidates.ts @@ -8,6 +8,11 @@ const EMITTED_SUFFIXES: ReadonlyArray< [".jsx", [".tsx", ".d.ts"]], ]; +export interface TypeScriptEmittedSourceCandidate { + readonly path: string; + readonly kind: "implementation" | "declaration"; +} + /** * Return TypeScript source counterparts for an explicit emitted filename. * Callers retain exact runtime-file precedence and must not use these for @@ -16,7 +21,7 @@ const EMITTED_SUFFIXES: ReadonlyArray< export const typescriptEmittedSourceCandidates = ( sourcePath: string, candidate: string, -): readonly string[] => { +): readonly TypeScriptEmittedSourceCandidate[] => { if (!/\.(?:ts|tsx|mts|cts)$/u.test(sourcePath)) return []; const emitted = EMITTED_SUFFIXES.find(([suffix]) => candidate.endsWith(suffix), @@ -25,5 +30,8 @@ export const typescriptEmittedSourceCandidates = ( // Strip the matched suffix by length. posix.extname would miss dotfile // names such as ".js", whose whole basename is the emitted suffix itself. const stem = candidate.slice(0, candidate.length - emitted[0].length); - return emitted[1].map((suffix) => `${stem}${suffix}`); + return emitted[1].map((suffix) => ({ + path: `${stem}${suffix}`, + kind: suffix.startsWith(".d.") ? "declaration" : "implementation", + })); }; diff --git a/src/application/javascript/JavaScriptArtifactAnalysis.ts b/src/application/javascript/JavaScriptArtifactAnalysis.ts index dd1a50488..e61d3ae94 100644 --- a/src/application/javascript/JavaScriptArtifactAnalysis.ts +++ b/src/application/javascript/JavaScriptArtifactAnalysis.ts @@ -1,6 +1,6 @@ import { createHash } from "node:crypto"; -import { moduleKindForJavaScriptReference } from "./JavaScriptArtifactPathResolution.js"; +import { moduleResolutionModeForJavaScriptReference } from "../../domain/javascript/javascriptModuleResolutionMode.js"; import { setImmediate } from "node:timers/promises"; import { resolveJavaScriptSourceMapReferences } from "../../domain/javascript/javascriptSourceMapPaths.js"; @@ -384,7 +384,10 @@ function* analyzeArtifactFileSteps< analysis.parse_status === "complete" || analysis.parse_status === "partial" ? yield* analyzeParsedJavaScriptSemanticsSteps( parsed, - moduleKindForJavaScriptReference(file.path, "static-import"), + moduleResolutionModeForJavaScriptReference( + file.path, + "static-import", + ), ) : null; const projected = diff --git a/src/application/javascript/JavaScriptArtifactGraphContext.ts b/src/application/javascript/JavaScriptArtifactGraphContext.ts index 8b0fed5f1..1779bdaae 100644 --- a/src/application/javascript/JavaScriptArtifactGraphContext.ts +++ b/src/application/javascript/JavaScriptArtifactGraphContext.ts @@ -66,6 +66,7 @@ export interface AstEdgeInput { /** Inferred static relationship edge values. */ export interface InferenceEdgeInput extends AstEdgeInput { + readonly limitations?: readonly string[]; readonly relation: | "imports" | "loads" @@ -162,6 +163,9 @@ export const addStaticInferenceEdge = ( range: input.range, operation: "map-static-relationship", coverage: input.coverage, + ...(input.limitations === undefined + ? {} + : { limitations: input.limitations }), }), }); }; @@ -347,7 +351,7 @@ export const resolveArtifactPath = ( specifier: string, sourcePath: string, files: ReadonlyMap, - moduleKind?: "import" | "require", + moduleKind?: "import" | "require" | "compiler-dependent", ): string | null => resolveArtifactPathByContext({ declaredPath: specifier, diff --git a/src/application/javascript/JavaScriptArtifactGraphFindings.ts b/src/application/javascript/JavaScriptArtifactGraphFindings.ts index 3e92ff1a4..0020ef577 100644 --- a/src/application/javascript/JavaScriptArtifactGraphFindings.ts +++ b/src/application/javascript/JavaScriptArtifactGraphFindings.ts @@ -12,7 +12,6 @@ import { javascriptAnalysisCoverage, linkElectronRoleToAsset, moduleLookupKey, - resolveArtifactPath, selfReferenceOmissions, sourceNodeFor, type JavaScriptArtifactGraphContext, @@ -23,9 +22,11 @@ import { staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js"; import { - moduleKindForJavaScriptReference, + artifactPathResolutionProperties, resolveArtifactPathByContext, + type ArtifactPathResolution, } from "./JavaScriptArtifactPathResolution.js"; +import { moduleResolutionModeForJavaScriptReference } from "../../domain/javascript/javascriptModuleResolutionMode.js"; type StaticReference = JavaScriptStaticAnalysis["references"][number]; type StaticEndpoint = JavaScriptStaticAnalysis["endpoints"][number]; @@ -41,9 +42,12 @@ interface FindingInput { } interface ResolvedReference { - readonly path: string; - readonly file: JavaScriptArtifactFile; + readonly path: string | null; + readonly file: JavaScriptArtifactFile | null; readonly node: ApplicationNode; + readonly limitations: readonly string[]; + readonly resolutionStatus?: string; + readonly resolution?: ArtifactPathResolution; } /** Project imports, workers, roles, endpoints, storage, and source-map links. */ @@ -90,7 +94,7 @@ const addReference = ( const resolved = input.value.specifier === null ? null - : resolveReference(context, input.file.path, input.value); + : resolveReference(context, input.file.path, input.value, input.coverage); if (input.value.kind === "worker" || input.value.kind === "service-worker") { const worker = context.accumulator.addNode({ kind: input.value.kind === "worker" ? "worker" : "service-worker", @@ -126,7 +130,7 @@ const addReference = ( relation: "loads", properties: { kind: input.value.kind }, }); - if (resolved !== null) + if (resolved !== null && resolved.path !== null) addStaticInferenceEdge(context, { source: worker, target: resolved.node, @@ -135,6 +139,7 @@ const addReference = ( coverage: input.coverage, relation: "maps_to", properties: { resolved_path: resolved.path }, + limitations: resolved.limitations, }); return; } @@ -154,13 +159,25 @@ const addReference = ( file: input.file, range: input.value.location, coverage: input.coverage, - relation: resolved?.file.kind === "native-addon" ? "loads" : "imports", + relation: resolved?.file?.kind === "native-addon" ? "loads" : "imports", properties: { kind: input.value.kind, specifier: input.value.specifier, expression: input.value.expression, + resolution_mode: + input.value.kind === "static-import" || + input.value.kind === "dynamic-import" || + input.value.kind === "require" + ? moduleResolutionModeForJavaScriptReference( + input.file.path, + input.value.kind, + ) + : null, resolved_path: resolved?.path ?? null, + resolution_status: resolved?.resolutionStatus ?? null, + ...artifactPathResolutionProperties(resolved?.resolution), }, + ...(resolved === null ? {} : { limitations: resolved.limitations }), }); }; @@ -373,6 +390,7 @@ const resolveReference = ( context: JavaScriptArtifactGraphContext, sourcePath: string, reference: StaticReference, + coverage: JavaScriptArtifactGraphCoverage, ): ResolvedReference | null => { const specifier = reference.specifier; if (specifier === null) return null; @@ -392,30 +410,70 @@ const resolveReference = ( const file = context.filesByPath.get(sourcePath); return file === undefined ? null - : { path: `${sourcePath}#module:${specifier}`, file, node: module }; + : { + path: `${sourcePath}#module:${specifier}`, + file, + node: module, + limitations: [], + }; } // Worker scripts are URLs relative to the script, not module specifiers. - const path = isWorker + const resolution = isWorker ? resolveArtifactPathByContext({ declaredPath: specifier, sourcePath, context: "url-reference", files: context.filesByPath, - }).resolved_path - : resolveArtifactPath( - specifier, + }) + : resolveArtifactPathByContext({ + declaredPath: specifier, sourcePath, - context.filesByPath, - reference.kind === "require" || - reference.kind === "static-import" || - reference.kind === "dynamic-import" - ? moduleKindForJavaScriptReference(sourcePath, reference.kind) - : undefined, - ); - if (path === null) return null; + context: "module-specifier", + files: context.filesByPath, + ...("require" === reference.kind || + "static-import" === reference.kind || + "dynamic-import" === reference.kind + ? { + moduleKind: moduleResolutionModeForJavaScriptReference( + sourcePath, + reference.kind, + ), + } + : {}), + }); + const path = resolution.resolved_path; + if (path === null) { + if (isWorker) return null; + const source = context.filesByPath.get(sourcePath); + return source === undefined + ? null + : { + path: null, + file: null, + node: unresolvedReferenceNode( + context, + source, + reference, + coverage, + resolution, + ), + limitations: resolution.limitations, + resolutionStatus: resolution.resolution_status, + resolution, + }; + } const file = context.filesByPath.get(path); const node = context.fileNodes.get(path); - return file === undefined || node === undefined ? null : { path, file, node }; + return file === undefined || node === undefined + ? null + : { + path, + file, + node, + limitations: resolution.limitations, + resolutionStatus: resolution.resolution_status, + resolution, + }; }; const resolveBundlerChunkReference = ( @@ -453,7 +511,7 @@ const resolveBundlerChunkReference = ( const node = unique[0]; return node === undefined ? null - : { path: `${sourcePath}#chunk:${key}`, file, node }; + : { path: `${sourcePath}#chunk:${key}`, file, node, limitations: [] }; }; const unresolvedReferenceNode = ( @@ -461,6 +519,7 @@ const unresolvedReferenceNode = ( file: JavaScriptArtifactFile, reference: StaticReference, coverage: JavaScriptArtifactGraphCoverage, + resolution?: ArtifactPathResolution, ): ApplicationNode => context.accumulator.addNode({ kind: "javascript-module", @@ -477,6 +536,10 @@ const unresolvedReferenceNode = ( specifier: reference.specifier, expression: reference.expression, resolution: "unresolved", + ...(resolution === undefined + ? {} + : { resolution_status: resolution.resolution_status }), + ...artifactPathResolutionProperties(resolution), }, evidence: staticInferenceEvidence({ sha256: file.sha256, @@ -487,6 +550,7 @@ const unresolvedReferenceNode = ( confidence: "low", limitations: [ "The static reference could not be resolved within the inventoried artifact.", + ...(resolution?.limitations ?? []), ], }), }, diff --git a/src/application/javascript/JavaScriptArtifactPathResolution.test.ts b/src/application/javascript/JavaScriptArtifactPathResolution.test.ts index 1a8713929..b746d7e97 100644 --- a/src/application/javascript/JavaScriptArtifactPathResolution.test.ts +++ b/src/application/javascript/JavaScriptArtifactPathResolution.test.ts @@ -1890,21 +1890,40 @@ describe("TypeScript NodeNext emitted-extension resolution", () => { ).toMatchObject({ resolution_status: "resolved", resolved_path: target }); }, ); +}); + +describe("TypeScript declaration fallback ownership", () => { + const container = "container"; it.each([ ["./dep.js", "src/dep.d.ts"], ["./cfg.mjs", "src/cfg.d.mts"], ["./legacy.cjs", "src/legacy.d.cts"], ] as const)( - "resolves %s to a declaration counterpart", + "retains %s as compile-time evidence without inventing a runtime target", (specifier, target) => { const files = fileMap([ file("src/main.ts", container), file(target, container, "export const value = 1;"), ]); + for (const moduleKind of ["import", "require"] as const) { + expect( + resolve({ + declaredPath: specifier, + sourcePath: "src/main.ts", + context: "module-specifier", + moduleKind, + files, + }), + ).toMatchObject({ + resolution_status: "unavailable", + resolved_path: null, + candidate_path: target, + }); + } expect( resolve({ - declaredPath: specifier, + declaredPath: "./" + target.slice(4), sourcePath: "src/main.ts", context: "module-specifier", moduleKind: "import", diff --git a/src/application/javascript/JavaScriptArtifactPathResolution.ts b/src/application/javascript/JavaScriptArtifactPathResolution.ts index 3ea23ab11..cb29ab2a9 100644 --- a/src/application/javascript/JavaScriptArtifactPathResolution.ts +++ b/src/application/javascript/JavaScriptArtifactPathResolution.ts @@ -19,8 +19,13 @@ import { classifyPackageImportTargetString, lookupExactPackageImport, } from "../../domain/javascript/javascriptPackageImportAliases.js"; -import { typescriptEmittedSourceCandidates } from "../TypeScriptEmittedSourceCandidates.js"; +import { + typescriptEmittedSourceCandidates, + type TypeScriptEmittedSourceCandidate, +} from "../TypeScriptEmittedSourceCandidates.js"; import { isRelativeJavaScriptModuleSpecifier } from "../../domain/javascript/javascriptModuleSpecifier.js"; +import type { JavaScriptModuleResolutionMode } from "../../domain/javascript/javascriptModuleResolutionMode.js"; +import type { JsonValue } from "../../domain/jsonValue.js"; type ArtifactPathResolutionContext = | "package-entrypoint" @@ -39,6 +44,16 @@ interface ArtifactPathResolutionBase { readonly declared_path: string; readonly resolution_context: ArtifactPathResolutionContext; readonly limitations: readonly string[]; + readonly conditional_resolutions?: readonly ConditionalModuleResolution[]; + readonly candidate_path?: string; +} + +export interface ConditionalModuleResolution { + readonly mode: "import" | "require"; + readonly resolution_status: UnresolvedArtifactPathStatus | "resolved"; + readonly resolved_path: string | null; + readonly candidate_path?: string; + readonly limitations: readonly string[]; } /** Explicit outcome of artifact-confined path resolution. */ @@ -62,26 +77,13 @@ export interface ResolveArtifactPathInput { readonly files: ReadonlyMap; readonly htmlBaseHref?: string | null; /** Import/require semantics; runtime resource paths omit this provenance. */ - readonly moduleKind?: "import" | "require"; + readonly moduleKind?: JavaScriptModuleResolutionMode; } -/** Loader selected by a source-level JavaScript module reference. */ -export const moduleKindForJavaScriptReference = ( - sourcePath: string, - referenceKind: "static-import" | "dynamic-import" | "require", - resolutionMode?: "import" | "require", -): "import" | "require" => - resolutionMode ?? - (referenceKind === "require" || - (referenceKind === "static-import" && - posix.extname(sourcePath).toLowerCase() === ".cts") - ? "require" - : "import"); - /** Preserve an explicitly retained loader mode on graph relationships. */ export const moduleResolutionModeProperties = ( - mode: "import" | "require" | undefined, -): Readonly> => + mode: JavaScriptModuleResolutionMode | undefined, +): Readonly> => mode === undefined ? {} : { resolution_mode: mode }; const EXTENSIONS = [ @@ -110,43 +112,116 @@ interface PackageFileTarget { readonly url: URL; } -type CandidateResolution = - | { - readonly resolvedPath: string; - readonly status: "resolved"; - readonly limitations: readonly string[]; - } +type CandidateResolution = { + readonly limitations: readonly string[]; + readonly candidatePath?: string; + readonly conditionalResolutions?: readonly ConditionalModuleResolution[]; +} & ( + | { readonly resolvedPath: string; readonly status: "resolved" } | { readonly resolvedPath: null; readonly status: UnresolvedArtifactPathStatus; - readonly limitations: readonly string[]; /** A truthy package main failed, so Node must not try ancestor packages. */ readonly stopsAncestorLookup?: true; - }; + } +); /** Resolve one declaration while preserving its original input identity. */ export const resolveArtifactPathByContext = ( input: ResolveArtifactPathInput, ): ArtifactPathResolution => { const resolution = resolvePath(input); + const facts = { + declared_path: input.declaredPath, + resolution_context: input.context, + limitations: resolution.limitations, + ...(resolution.candidatePath === undefined + ? {} + : { candidate_path: resolution.candidatePath }), + ...(resolution.conditionalResolutions === undefined + ? {} + : { conditional_resolutions: resolution.conditionalResolutions }), + }; return resolution.status === "resolved" ? { - declared_path: input.declaredPath, - resolution_context: input.context, + ...facts, resolved_path: resolution.resolvedPath, resolution_status: resolution.status, - limitations: resolution.limitations, } - : { - declared_path: input.declaredPath, - resolution_context: input.context, - resolved_path: null, - resolution_status: resolution.status, - limitations: resolution.limitations, - }; + : { ...facts, resolved_path: null, resolution_status: resolution.status }; }; +/** Project retained conditional identities without flattening them into display text. */ +export const artifactPathResolutionProperties = ( + resolution: ArtifactPathResolution | undefined, +): Readonly> => ({ + ...(resolution?.candidate_path === undefined + ? {} + : { candidate_path: resolution.candidate_path }), + ...(resolution?.conditional_resolutions === undefined + ? {} + : { + conditional_resolutions: resolution.conditional_resolutions.map( + (branch) => ({ + mode: branch.mode, + resolution_status: branch.resolution_status, + resolved_path: branch.resolved_path, + limitations: [...branch.limitations], + ...(branch.candidate_path === undefined + ? {} + : { candidate_path: branch.candidate_path }), + }), + ), + }), +}); + +const conditionalResolution = ( + mode: "import" | "require", + result: CandidateResolution, +): ConditionalModuleResolution => ({ + mode, + resolution_status: result.status, + resolved_path: result.resolvedPath, + limitations: result.limitations, + ...(result.candidatePath === undefined + ? {} + : { candidate_path: result.candidatePath }), +}); + const resolvePath = (input: ResolveArtifactPathInput): CandidateResolution => { + if (input.moduleKind === "compiler-dependent") { + const imported = resolvePath({ ...input, moduleKind: "import" }); + const required = resolvePath({ ...input, moduleKind: "require" }); + const sameOutcome = + imported.status === required.status && + imported.resolvedPath === required.resolvedPath && + imported.candidatePath === required.candidatePath; + const limitation = + "Static TypeScript loader mode is compiler-dependent without retained compiler options. " + + (sameOutcome + ? "Node import and require resolution agree on this outcome." + : "Node import and require resolution disagree; neither branch is an established target."); + return sameOutcome + ? { + ...imported, + limitations: [ + ...new Set([ + ...imported.limitations, + ...required.limitations, + limitation, + ]), + ], + } + : { + resolvedPath: null, + status: "unavailable", + limitations: [limitation], + conditionalResolutions: [ + conditionalResolution("import", imported), + conditionalResolution("require", required), + ], + }; + } // Package import keys are literal lookup identities, not artifact paths. // The selected target is admitted separately by resolveExportTarget. if ( @@ -176,12 +251,47 @@ const resolvePath = (input: ResolveArtifactPathInput): CandidateResolution => { : []; if (isModuleUrlPath && input.moduleKind === "import") return ( - resolveFileCandidates(input, [confined, ...emittedSourceCandidates]) ?? - notFoundCandidate() + resolveRuntimeSourceCandidates( + input, + confined, + emittedSourceCandidates, + ) ?? notFoundCandidate() ); return resolveCandidate(input, confined, new Set(), emittedSourceCandidates); }; +const resolveRuntimeSourceCandidates = ( + input: ResolveArtifactPathInput, + exactPath: string, + sourceCandidates: readonly TypeScriptEmittedSourceCandidate[], +): CandidateResolution | null => { + const source = input.files.get(input.sourcePath); + const exactCandidate: TypeScriptEmittedSourceCandidate = { + path: exactPath, + kind: "implementation", + }; + for (const candidate of [exactCandidate, ...sourceCandidates]) { + const target = input.files.get(candidate.path); + if ( + target === undefined || + (source !== undefined && + target.container_sha256 !== source.container_sha256) + ) + continue; + return candidate.kind === "declaration" + ? { + resolvedPath: null, + status: "unavailable", + candidatePath: candidate.path, + limitations: [ + "Only a TypeScript declaration fallback was found; it does not establish the requested runtime module.", + ], + } + : { resolvedPath: candidate.path, status: "resolved", limitations: [] }; + } + return null; +}; + const rejectDeclaration = (declared: string): CandidateResolution | null => { if (declared.length === 0) return unresolvedCandidate("rejected", ["The declared path is empty."]); @@ -849,12 +959,10 @@ const resolveCandidate = ( input: ResolveArtifactPathInput, candidate: string, packageChain: ReadonlySet, - emittedSourceCandidates: readonly string[] = [], + emittedSourceCandidates: readonly TypeScriptEmittedSourceCandidate[] = [], ): CandidateResolution => - resolveFileCandidates(input, [ - ...fileCandidates(candidate, input.moduleKind), - ...emittedSourceCandidates, - ]) ?? + resolveFileCandidates(input, fileCandidates(candidate, input.moduleKind)) ?? + resolveRuntimeSourceCandidates(input, candidate, emittedSourceCandidates) ?? resolveDirectory( input, candidate, @@ -940,11 +1048,26 @@ const resolveFileCandidates = ( (source === undefined || target.container_sha256 === source.container_sha256) ) - return { resolvedPath: path, status: "resolved", limitations: [] }; + return isRuntimeDeclarationPath(input, path) + ? { + resolvedPath: null, + status: "unavailable", + candidatePath: path, + limitations: [ + `The TypeScript declaration ${path} is compile-time evidence and cannot identify a runtime module implementation.`, + ], + } + : { resolvedPath: path, status: "resolved", limitations: [] }; } return null; }; +const isRuntimeDeclarationPath = ( + input: ResolveArtifactPathInput, + path: string, +): boolean => + input.moduleKind !== undefined && /\.d\.(?:ts|mts|cts)$/iu.test(path); + const NODE_MODULE_EXTENSIONS = [".js", ".json", ".node"] as const; const fileCandidates = ( diff --git a/src/application/javascript/JavaScriptModuleRelationships.ts b/src/application/javascript/JavaScriptModuleRelationships.ts index 514a9bb7c..3b46e95ae 100644 --- a/src/application/javascript/JavaScriptModuleRelationships.ts +++ b/src/application/javascript/JavaScriptModuleRelationships.ts @@ -18,6 +18,7 @@ import type { JavaScriptModuleOrigin, JavaScriptSemanticModuleLink, } from "../../domain/javascript/javascriptSemanticIr.js"; +import { moduleResolutionModeForJavaScriptReference } from "../../domain/javascript/javascriptModuleResolutionMode.js"; import type { JavaScriptArtifactFile } from "../../domain/javascript/javascriptArtifactFiles.js"; import { addAstContainsEdge, @@ -30,7 +31,7 @@ import { staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js"; import { - moduleKindForJavaScriptReference, + artifactPathResolutionProperties, moduleResolutionModeProperties, resolveArtifactPathByContext, type ArtifactPathResolution, @@ -54,6 +55,7 @@ interface RelationshipInput { type ResolvedModuleTarget = { readonly node: ApplicationNode; readonly limitations: readonly string[]; + readonly resolution?: ArtifactPathResolution; } & ( | { readonly path: string; @@ -287,7 +289,7 @@ const resolveModuleTarget = ( sourcePath: input.file.path, context: "module-specifier", files: input.context.filesByPath, - moduleKind: moduleKindForJavaScriptReference( + moduleKind: moduleResolutionModeForJavaScriptReference( input.file.path, input.link.kind === "require" || input.link.kind === "commonjs-export" ? "require" @@ -297,15 +299,12 @@ const resolveModuleTarget = ( }); if (resolution.resolution_status !== "resolved") return { - node: unresolvedModuleNode( - input, - specifier, - resolution.resolution_status, - ), + node: unresolvedModuleNode(input, specifier, resolution), path: null, file: null, status: resolution.resolution_status, limitations: resolution.limitations, + resolution, }; const path = resolution.resolved_path; const file = input.context.filesByPath.get(path); @@ -322,20 +321,24 @@ const resolveModuleTarget = ( file, status: "resolved", limitations: resolution.limitations, + resolution, }; }; const unresolvedModuleNode = ( input: RelationshipInput, specifier: string, - status: Exclude, + resolution: Extract< + ArtifactPathResolution, + { resolution_status: Exclude } + >, ): ApplicationNode => input.context.accumulator.addNode({ kind: "javascript-module", identity: artifactLocalIdentity( input.file.sha256, "unresolved-semantic-module", - `${status}:${specifier}`, + `${resolution.resolution_status}:${specifier}`, ), observations: [ { @@ -343,7 +346,8 @@ const unresolvedModuleNode = ( properties: { semantic_role: "module-reference", declared_specifier: specifier, - resolution_status: status, + resolution_status: resolution.resolution_status, + ...artifactPathResolutionProperties(resolution), }, evidence: staticInferenceEvidence({ sha256: input.file.sha256, @@ -364,6 +368,9 @@ const moduleOriginForExport = ( ): JavaScriptModuleOrigin | null => { if (link.specifier !== null) return { + ...(link.resolutionMode === undefined + ? {} + : { resolutionMode: link.resolutionMode }), specifier: link.specifier, importedPath: link.importedName === null ? [] : [link.importedName], }; @@ -393,6 +400,7 @@ const relationshipProperties = ( exported_name: link.exportedName, resolved_path: target?.path ?? null, resolution_status: target?.status ?? null, + ...artifactPathResolutionProperties(target?.resolution), target_file_kind: target?.file?.kind ?? null, target_json_status: target?.file?.kind === "json" || target?.file?.kind === "package-json" @@ -441,6 +449,7 @@ const moduleFormat = ( const extension = posix.extname(path).toLowerCase(); if (extension === ".mjs" || extension === ".mts") return "esm"; if (extension === ".cjs" || extension === ".cts") return "commonjs"; + if (extension === ".ts" || extension === ".tsx") return "unknown"; const esm = ir.moduleLinks.some(({ kind }) => ["import", "export", "re-export"].includes(kind), ); diff --git a/src/composition/javascriptAnalysisWorkerProcess.ts b/src/composition/javascriptAnalysisWorkerProcess.ts index 09a9c9bc3..d1c3c134e 100644 --- a/src/composition/javascriptAnalysisWorkerProcess.ts +++ b/src/composition/javascriptAnalysisWorkerProcess.ts @@ -1,4 +1,4 @@ -import { moduleKindForJavaScriptReference } from "../application/javascript/JavaScriptArtifactPathResolution.js"; +import { moduleResolutionModeForJavaScriptReference } from "../domain/javascript/javascriptModuleResolutionMode.js"; import { parseJavaScriptSource } from "../domain/javascript/javascriptSourceParser.js"; import { analyzeParsedJavaScriptStaticSourceSteps } from "../domain/javascript/javascriptStaticAnalysis.js"; import { @@ -56,7 +56,7 @@ const analyze: JavaScriptSourceWorkerAnalyzer = async ( const ir = await completeJavaScriptAnalysisSteps( analyzeParsedJavaScriptSemanticsSteps( parsed, - moduleKindForJavaScriptReference(file.path, "static-import"), + moduleResolutionModeForJavaScriptReference(file.path, "static-import"), ), ); parsed = null; diff --git a/src/domain/javascript/javascriptModuleResolutionMode.ts b/src/domain/javascript/javascriptModuleResolutionMode.ts new file mode 100644 index 000000000..d14b91bd9 --- /dev/null +++ b/src/domain/javascript/javascriptModuleResolutionMode.ts @@ -0,0 +1,23 @@ +import { posix } from "node:path"; + +/** Loader evidence retained for a source-level module reference. */ +export type JavaScriptModuleResolutionMode = + | "import" + | "require" + | "compiler-dependent"; + +/** Derive source mode only when syntax or an explicit source format owns it. */ +export const moduleResolutionModeForJavaScriptReference = ( + sourcePath: string, + referenceKind: "static-import" | "dynamic-import" | "require", + explicitMode?: JavaScriptModuleResolutionMode, +): JavaScriptModuleResolutionMode => { + if (explicitMode !== undefined) return explicitMode; + if (referenceKind === "require") return "require"; + if (referenceKind === "dynamic-import") return "import"; + const extension = posix.extname(sourcePath).toLowerCase(); + if (extension === ".cts") return "require"; + if (extension === ".mts") return "import"; + if (extension === ".ts" || extension === ".tsx") return "compiler-dependent"; + return "import"; +}; diff --git a/src/domain/javascript/javascriptSemanticAnalysis.ts b/src/domain/javascript/javascriptSemanticAnalysis.ts index 35a8b7dc9..f6c6db25d 100644 --- a/src/domain/javascript/javascriptSemanticAnalysis.ts +++ b/src/domain/javascript/javascriptSemanticAnalysis.ts @@ -68,6 +68,7 @@ import { import { isJavaScriptRpcClientFactory } from "./javascriptRpcEndpoints.js"; import { createSemanticModuleInterop } from "./javascriptModuleInterop.js"; import { SemanticPropertyPathCoverage } from "./javascriptSemanticPropertyPaths.js"; +import type { JavaScriptModuleResolutionMode } from "./javascriptModuleResolutionMode.js"; interface BindPatternInput { readonly pattern: t.Node; @@ -138,7 +139,7 @@ export function* indexJavaScriptBindingsSteps( /** Recover semantics from an already parsed JavaScript artifact. */ export const analyzeParsedJavaScriptSemantics = ( file: ParsedJavaScriptSource, - staticImportResolutionMode: "import" | "require" = "import", + staticImportResolutionMode: JavaScriptModuleResolutionMode = "import", ): JavaScriptSemanticIr => completeSemanticSteps( analyzeParsedJavaScriptSemanticsSteps(file, staticImportResolutionMode), @@ -152,7 +153,7 @@ export const analyzeParsedJavaScriptSemantics = ( */ export function* analyzeParsedJavaScriptSemanticsSteps( file: ParsedJavaScriptSource, - staticImportResolutionMode: "import" | "require" = "import", + staticImportResolutionMode: JavaScriptModuleResolutionMode = "import", ): Generator { const state = createState(file.program, staticImportResolutionMode); yield* collectDefinitionsSteps(file.program, state); @@ -539,7 +540,7 @@ const bindingOrigin = ( const createState = ( program: t.Program, - staticImportResolutionMode: "import" | "require" = "import", + staticImportResolutionMode: JavaScriptModuleResolutionMode = "import", ): JavaScriptSemanticAnalysisState => { const root: JavaScriptSemanticScopeState = { scopeId: semanticScopeId("program", program), @@ -1216,8 +1217,11 @@ const addBinding = (input: AddBindingInput): void => { if (directOrigin !== undefined) binding.directOrigins.push( directOrigin.resolutionMode === undefined && - state.staticImportResolutionMode === "require" - ? { ...directOrigin, resolutionMode: "require" } + state.staticImportResolutionMode !== "import" + ? { + ...directOrigin, + resolutionMode: state.staticImportResolutionMode, + } : directOrigin, ); binding.runtimeImport ||= runtimeImport === true; diff --git a/src/domain/javascript/javascriptSemanticIr.ts b/src/domain/javascript/javascriptSemanticIr.ts index 18f1eb485..005471775 100644 --- a/src/domain/javascript/javascriptSemanticIr.ts +++ b/src/domain/javascript/javascriptSemanticIr.ts @@ -4,10 +4,11 @@ import type { JavaScriptSemanticCoverage, JavaScriptSemanticReturnCoverage, } from "./javascriptSemanticCoverage.js"; +import type { JavaScriptModuleResolutionMode } from "./javascriptModuleResolutionMode.js"; /** One exact module origin followed through imports, requires, or aliases. */ export interface JavaScriptModuleOrigin { - readonly resolutionMode?: "import" | "require"; + readonly resolutionMode?: JavaScriptModuleResolutionMode; readonly specifier: string; readonly importedPath: readonly string[]; } @@ -393,7 +394,7 @@ export interface JavaScriptSemanticFrontier { /** Static import/export relationship retained for cross-file composition. */ export interface JavaScriptSemanticModuleLink { - readonly resolutionMode?: "import" | "require"; + readonly resolutionMode?: JavaScriptModuleResolutionMode; readonly kind: | "import" | "type-import" diff --git a/src/domain/javascript/javascriptSemanticProjection.ts b/src/domain/javascript/javascriptSemanticProjection.ts index 9d252a0d8..b477bb5af 100644 --- a/src/domain/javascript/javascriptSemanticProjection.ts +++ b/src/domain/javascript/javascriptSemanticProjection.ts @@ -533,7 +533,20 @@ const addModuleLink = ( }, referenceNode: t.Node, ): void => { - const collected = { ...link, callableId: link.callableId ?? null }; + const resolutionMode = + link.resolutionMode ?? + (link.kind === "import" || + link.kind === "re-export" || + link.kind === "type-import" + ? state.staticImportResolutionMode + : link.kind === "require" + ? "require" + : undefined); + const collected = { + ...link, + ...(resolutionMode === undefined ? {} : { resolutionMode }), + callableId: link.callableId ?? null, + }; state.moduleLinks.push(collected); if (link.localName !== null) { const binding = resolveSemanticBindingState( diff --git a/src/domain/javascript/javascriptSemanticReturns.ts b/src/domain/javascript/javascriptSemanticReturns.ts index a3ca92ead..27bb030d0 100644 --- a/src/domain/javascript/javascriptSemanticReturns.ts +++ b/src/domain/javascript/javascriptSemanticReturns.ts @@ -123,9 +123,7 @@ export const resolveSemanticModuleCallables = ( : undefined; return { ...link, - ...(resolutionMode === "import" || resolutionMode === "require" - ? { resolutionMode } - : {}), + ...(resolutionMode !== undefined ? { resolutionMode } : {}), callableId: resolved.length === 1 ? (resolved[0] ?? null) : null, }; }); diff --git a/src/domain/javascript/javascriptSemanticState.ts b/src/domain/javascript/javascriptSemanticState.ts index b82abc62d..d01a4be52 100644 --- a/src/domain/javascript/javascriptSemanticState.ts +++ b/src/domain/javascript/javascriptSemanticState.ts @@ -12,6 +12,7 @@ import type { JavaScriptSemanticCallable, JavaScriptSemanticScope, } from "./javascriptSemanticIr.js"; +import type { JavaScriptModuleResolutionMode } from "./javascriptModuleResolutionMode.js"; /** Internal initializer plus a destructuring/member projection. */ interface JavaScriptSemanticInitializer { @@ -63,7 +64,7 @@ export interface JavaScriptSemanticScopeState { /** Shared state for semantic collection and evaluation. */ export interface JavaScriptSemanticAnalysisState { /** Effective loader for static imports in this source artifact. */ - readonly staticImportResolutionMode: "import" | "require"; + readonly staticImportResolutionMode: JavaScriptModuleResolutionMode; readonly parentsByNode: WeakMap; readonly scopes: JavaScriptSemanticScopeState[]; readonly scopesById: Map; diff --git a/src/javascript/analysis/JavaScriptAnalysisWorkerSchemas.ts b/src/javascript/analysis/JavaScriptAnalysisWorkerSchemas.ts index b666cfa9b..84a63d79b 100644 --- a/src/javascript/analysis/JavaScriptAnalysisWorkerSchemas.ts +++ b/src/javascript/analysis/JavaScriptAnalysisWorkerSchemas.ts @@ -475,7 +475,9 @@ const origin = z .strictObject({ specifier: z.string(), importedPath: strings, - resolutionMode: z.enum(["import", "require"]).optional(), + resolutionMode: z + .enum(["import", "require", "compiler-dependent"]) + .optional(), }) .transform(({ resolutionMode, ...rest }) => ({ ...rest, @@ -530,7 +532,9 @@ const coverage = z }); const moduleLink = z .strictObject({ - resolutionMode: z.enum(["import", "require"]).optional(), + resolutionMode: z + .enum(["import", "require", "compiler-dependent"]) + .optional(), kind: z.enum([ "import", "type-import", diff --git a/tests/boundary/filesystem/javascript-applications/javascriptModuleRelationships.test.ts b/tests/boundary/filesystem/javascript-applications/javascriptModuleRelationships.test.ts index 9b4df9992..cdd95bc97 100644 --- a/tests/boundary/filesystem/javascript-applications/javascriptModuleRelationships.test.ts +++ b/tests/boundary/filesystem/javascript-applications/javascriptModuleRelationships.test.ts @@ -152,7 +152,7 @@ describe("TypeScript source module loader semantics", () => { }); }); -describe("CommonJS and ESM module relationships", () => { +describe("JavaScript module relationships", () => { it("composes bindings, re-exports, dynamic imports, and JSON modules", async () => { const root = await moduleFixture(); const first = await reconstructJavaScriptFixture(root); @@ -288,6 +288,122 @@ describe("CommonJS and ESM module relationships", () => { }); }); +describe("Compiler-dependent TypeScript resolution", () => { + it("retains only compiler-independent targets for .ts static imports", async () => { + const root = await createTestTempDirectory("rea-ts-conditional-loader-"); + await writeFixtureFiles(root, { + "package.json": '{"type":"commonjs"}', + "main.ts": `import { value as different } from "different"; +import { value as same } from "same"; +void different; void same;`, + "node_modules/different/package.json": JSON.stringify({ + exports: { + ".": { + import: "./import.mjs", + require: "./require.cjs", + }, + }, + }), + "node_modules/different/import.mjs": "export const value = 'import';", + "node_modules/different/require.cjs": "exports.value = 'require';", + "node_modules/same/package.json": JSON.stringify({ + exports: { ".": { import: "./shared.js", require: "./shared.js" } }, + }), + "node_modules/same/shared.js": "export const value = 'shared';", + }); + + const { graph } = await reconstructJavaScriptFixture(root); + const different = findRelationshipEdge(graph, { + kind: "import", + specifier: "different", + localName: "different", + }); + const same = findRelationshipEdge(graph, { + kind: "import", + specifier: "same", + localName: "same", + resolvedPath: "node_modules/same/shared.js", + }); + const staticFinding = (specifier: string) => + graph.edges.find( + ({ relation, properties }) => + relation === "imports" && + properties.kind === "static-import" && + properties.specifier === specifier, + ); + + expect( + findSourceModule(graph, "main.ts")?.observations[0]?.properties, + ).toMatchObject({ module_format: "unknown" }); + expect(different).toMatchObject({ + properties: { + resolution_mode: "compiler-dependent", + resolution_status: "unavailable", + resolved_path: null, + conditional_resolutions: [ + { + mode: "import", + resolution_status: "resolved", + resolved_path: "node_modules/different/import.mjs", + }, + { + mode: "require", + resolution_status: "resolved", + resolved_path: "node_modules/different/require.cjs", + }, + ], + }, + }); + expect(same).toMatchObject({ + properties: { + resolution_mode: "compiler-dependent", + resolved_path: "node_modules/same/shared.js", + resolution_status: "resolved", + }, + evidence: { + limitations: expect.arrayContaining([ + expect.stringContaining( + "compiler-dependent without retained compiler options", + ), + ]), + }, + }); + expect(staticFinding("different")).toMatchObject({ + properties: { + resolution_mode: "compiler-dependent", + resolution_status: "unavailable", + conditional_resolutions: [ + { + mode: "import", + resolved_path: "node_modules/different/import.mjs", + }, + { + mode: "require", + resolved_path: "node_modules/different/require.cjs", + }, + ], + }, + evidence: { + limitations: expect.arrayContaining([ + expect.stringContaining( + "compiler-dependent without retained compiler options", + ), + ]), + }, + }); + expect(staticFinding("same")).toMatchObject({ + properties: { resolved_path: "node_modules/same/shared.js" }, + evidence: { + limitations: expect.arrayContaining([ + expect.stringContaining( + "compiler-dependent without retained compiler options", + ), + ]), + }, + }); + }); +}); + it("does not assign one module origin to an export with colliding path encodings", async () => { const root = await createTestTempDirectory("rea-ambiguous-module-origin-"); await writeFixtureFiles(root, {