Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions docs/javascript-artifact-reconstruction.md
Original file line number Diff line number Diff line change
Expand Up @@ -469,6 +469,12 @@ from unmatched nested targets rather than reporting array indices.
For imports and requires, the active Node conditions include `module-sync`;
earlier active conditions retain precedence over later ones.

Package self-references use the importer's enclosing package scope before
installed dependencies. ESM requires the parsed package name to equal the
metadata name; a scope-only name such as `@scope` cannot capture `@scope/pkg`.
CommonJS retains Node's raw-request name/prefix matching. Both paths preserve
the original specifier and select exports under their own loader conditions.

Exact package-private `#alias` specifiers resolve against the importer's
enclosing `package.json` `imports` map — the nearest same-container package
scope, stopping at a `node_modules` directory so a nested package cannot inherit
Expand All @@ -484,8 +490,15 @@ URL targets before selecting a later package-local file; an unsupported bare
package or recursive alias keeps its unresolved outcome rather than selecting
a later fallback.

ESM relative module paths and selected package exports targets use URL suffix handling
and one percent-decoding pass. CommonJS relative paths and legacy package main
ESM relative module paths, legacy package subpaths without exports, and selected
package exports targets use URL suffix handling and one percent-decoding pass.
Bare specifiers retain their complete query/fragment text for exports key matching.
For dependency lookup, ESM constructs a package metadata URL instead of treating
the parsed package name as a literal directory. A root request such as `legacy?x`
does not load either `node_modules/legacy?x` or `node_modules/legacy`; an exact
self-reference with that metadata name can still select its exports first.
Without an exports map, ESM subpaths select exact files; directory imports and
extension fallback are refused. CommonJS relative paths and legacy package main
fields retain literal filename punctuation. Exports targets must start with
`./` and exclude `.`, `..`, and `node_modules` path segments, including their
encoded forms, before URL normalization. Arrays skip invalid exports targets
Expand Down
7 changes: 5 additions & 2 deletions src/application/javascript/JavaScriptArtifactAnalysis.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,10 @@
import { projectJavaScriptModuleSemantics } from "../../domain/javascript/javascriptModuleSemanticIr.js";
import { parseJavaScriptSource } from "../../domain/javascript/javascriptSourceParser.js";
import { hasValidSourceMapContents } from "../../domain/sourceMapContents.js";
import { flattenSourceMapLeaves } from "../../domain/sourceMapEnvelope.js";
import {
flattenSourceMapLeaves,
sourceMapJsonText,
} from "../../domain/sourceMapEnvelope.js";
import type {
JavaScriptSourceRange,
JavaScriptSourcePoint,
Expand Down Expand Up @@ -486,7 +489,7 @@
if (!file.text.included) return unavailableSourceMap(file);
let value: unknown;
try {
value = JSON.parse(file.text.value);
value = JSON.parse(sourceMapJsonText(file.text.value));
} catch (cause: unknown) {
void cause;
return invalidSourceMap(file, "Source map is not valid JSON.");
Expand Down Expand Up @@ -612,4 +615,4 @@
createHash("sha256").update(value).digest("hex");

const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
typeof value === "object" && value !== null && !Array.isArray(value);

Check warning on line 618 in src/application/javascript/JavaScriptArtifactAnalysis.ts

View workflow job for this annotation

GitHub Actions / Static checks

eslint(max-lines)

src/application/javascript/JavaScriptArtifactAnalysis.ts:618:72: File has too many lines (582).
208 changes: 114 additions & 94 deletions src/application/javascript/JavaScriptArtifactPathResolution.ts
Original file line number Diff line number Diff line change
Expand Up @@ -176,9 +176,7 @@ const contextualCandidate = (
): string | CandidateResolution => {
const { context } = input;
let declared =
context === "html-reference" ||
context === "url-reference" ||
(context === "module-specifier" && input.moduleKind !== "require")
context === "html-reference" || context === "url-reference"
Comment thread
morluto marked this conversation as resolved.
Resolved
? stripQueryAndFragment(input.declaredPath)
: input.declaredPath;
Comment thread
morluto marked this conversation as resolved.
Resolved
if (context === "html-reference") return htmlCandidate(input);
Expand All @@ -190,9 +188,9 @@ const contextualCandidate = (
"URL and Node builtin schemes are outside static artifact module resolution.",
]);
if (!declared.startsWith(".") && !declared.startsWith("/"))
return bareModuleCandidate(input, declared);
return bareModuleCandidate(input);
if (input.moduleKind !== "require") {
const decoded = decodeModuleUrlPath(declared);
const decoded = decodeModuleUrlPath(stripQueryAndFragment(declared));
if (typeof decoded !== "string") return decoded;
declared = decoded;
}
Expand Down Expand Up @@ -237,34 +235,51 @@ const relativeCandidate = (sourcePath: string, declared: string): string =>

const bareModuleCandidate = (
input: ResolveArtifactPathInput,
declared: string,
): CandidateResolution => {
const packageName = barePackageName(declared);
if (packageName === null || isBuiltin(declared))
const request = parseBarePackageRequest(input.declaredPath, input.moduleKind);
if (request === null || isBuiltin(input.declaredPath))
return unresolvedCandidate("external", [
"The bare specifier is a Node builtin or invalid package name.",
]);
if (input.moduleKind === "import" && packageName.includes("%"))
if (input.moduleKind === "import" && request.packageName.includes("%"))
return unresolvedCandidate("rejected", [
"Percent signs are not admitted in ES module package names.",
]);
const self = commonJsSelfCandidate(input, declared);
const self = packageSelfCandidate(input, request);
if (self !== null) return self;
const subpath =
declared === packageName ? "." : `.${declared.slice(packageName.length)}`;
// ESM constructs a package.json URL; its parsed identity is not a literal
// dependency directory. Self resolution above still uses the exact name.
let dependencyDirectory = posix.join("node_modules", request.packageName);
if (input.moduleKind === "import") {
const metadataUrl = new URL(
`./node_modules/${request.packageName}/package.json`,
PACKAGE_ARTIFACT_ROOT_URL,
);
if (!metadataUrl.pathname.endsWith("/package.json"))
return unresolvedCandidate("external", [
`ESM package name ${JSON.stringify(request.packageName)} produces a dependency URL whose pathname does not name package.json; no literal or suffix-stripped package directory was searched.`,
]);
const decoded = decodeModuleUrlPath(
metadataUrl.pathname.slice(PACKAGE_ARTIFACT_ROOT_URL.pathname.length),
);
if (typeof decoded !== "string") return decoded;
const confined = confineCandidate(decoded);
if (typeof confined !== "string") return confined;
dependencyDirectory = posix.dirname(confined);
}
const source = input.files.get(input.sourcePath);
let directory = posix.dirname(input.sourcePath);
while (true) {
const candidate = posix.join(directory, "node_modules", packageName);
const candidate = posix.join(directory, dependencyDirectory);
const metadata = readPackageMetadata(input, candidate);
if (packageExportsEligible(input) && metadata.kind !== "absent")
return resolvePackageSpecifier(input, candidate, subpath, metadata);
if (subpath === ".") {
if (request.dependencyExportsEligible && metadata.kind !== "absent")
return resolvePackageDependency(input, candidate, request, metadata);
if (request.packageSubpath === ".") {
const direct = resolveFileCandidates(input, fileCandidates(candidate));
if (direct !== null) return direct;
}
if (hasContainerDirectory(input.files, candidate, source?.container_sha256))
return resolvePackageSpecifier(input, candidate, subpath, metadata);
return resolvePackageDependency(input, candidate, request, metadata);
if (directory === "." || directory === "") break;
directory = posix.dirname(directory);
}
Expand Down Expand Up @@ -330,24 +345,25 @@ const resolvePackageImportAlias = (
return unresolvedCandidate("external", [
`Wildcard package import aliases remain unresolved; package metadata ${metadata.path} has no exact imports key ${specifier}.`,
]);
const selected = selectPackageImportTarget(
const selected = selectExportTarget(
lookup.target,
input.moduleKind,
metadata.path,
packageExportConditions(input.moduleKind),
packageMetadataUrl(metadata.path),
"imports",
);
if (selected.status === "rejected")
if (selected.kind === "invalid" || selected.kind === "invalid-config")
return unresolvedCandidate("rejected", [
`Package metadata ${metadata.path}: ${selected.limitation}`,
]);
if (selected.status === "unmatched")
if (selected.kind === "unmatched")
return unresolvedCandidate("external", [
`Package metadata ${metadata.path} declares no imports target for alias ${specifier} under the active conditions; it declares ${selected.declared.join(", ") || "no conditions"}.`,
]);
if (selected.status === "blocked")
if (selected.kind === "blocked")
return unresolvedCandidate("external", [
`Package metadata ${metadata.path} blocks import alias ${specifier} with ${selected.cause === "null" ? "an explicit null imports target" : "an empty imports target array"}.`,
]);
if (selected.status === "non-relative") {
if (selected.kind === "non-relative") {
const target = classifyPackageImportTargetString(selected.value);
return unresolvedCandidate("external", [
target.kind === "recursive"
Expand All @@ -358,77 +374,44 @@ const resolvePackageImportAlias = (
return resolveExportTarget(input, metadata.path, selected, "imports");
};

const selectPackageImportTarget = (
value: unknown,
moduleKind: ResolveArtifactPathInput["moduleKind"],
packagePath: string,
):
| ({ readonly status: "value" } & PackageFileTarget)
| { readonly status: "non-relative"; readonly value: string }
| { readonly status: "blocked"; readonly cause: PackageTargetBlockCause }
| { readonly status: "unmatched"; readonly declared: readonly string[] }
| { readonly status: "rejected"; readonly limitation: string } => {
const selected = selectExportTarget(
value,
packageExportConditions(moduleKind),
packageMetadataUrl(packagePath),
"imports",
);
if (selected.kind === "invalid" || selected.kind === "invalid-config")
return { status: "rejected", limitation: selected.limitation };
if (selected.kind === "unmatched")
return {
status: "unmatched",
declared: selected.declared,
};
if (selected.kind === "blocked")
return { status: "blocked", cause: selected.cause };
if (selected.kind === "non-relative")
return { status: "non-relative", value: selected.value };
return {
status: "value",
value: selected.value,
url: selected.url,
};
};

/** Self references use the nearest package scope before dependency lookup. */
const commonJsSelfCandidate = (
const packageSelfCandidate = (
input: ResolveArtifactPathInput,
declared: string,
request: BarePackageRequest,
): CandidateResolution | null => {
if (input.moduleKind !== "require" || !input.files.has(input.sourcePath))
if (input.moduleKind === undefined || !input.files.has(input.sourcePath))
Comment thread
morluto marked this conversation as resolved.
Resolved
return null;
const metadata = enclosingPackageMetadata(input);
if (metadata.kind === "none") return null;
if (metadata.kind === "unavailable")
return unresolvedCandidate("unavailable", [metadata.limitation]);
if (
metadata.name === undefined ||
metadata.exports === undefined ||
(declared !== metadata.name && !declared.startsWith(`${metadata.name}/`))
)
if (metadata.name === undefined || metadata.exports === undefined)
return null;
const subpath =
declared === metadata.name
? "."
: `.${declared.slice(metadata.name.length)}`;
let subpath: string;
if (input.moduleKind === "import") {
if (metadata.name !== request.packageName) return null;
subpath = request.packageSubpath;
} else if (input.declaredPath === metadata.name) {
subpath = ".";
} else if (input.declaredPath.startsWith(`${metadata.name}/`)) {
subpath = `.${input.declaredPath.slice(metadata.name.length)}`;
} else return null;
// Self resolution does not apply the CommonJS dependency-name matcher.
return resolvePackageExports(input, metadata.path, subpath, metadata.exports);
};

/** Package roots and exact subpaths share metadata and exports selection. */
const resolvePackageSpecifier = (
/** Resolve an installed dependency using one parsed request and its metadata. */
const resolvePackageDependency = (
input: ResolveArtifactPathInput,
directory: string,
subpath: string,
request: BarePackageRequest,
metadata: PackageMetadata,
): CandidateResolution => {
const exportsEligible = packageExportsEligible(input);
if (exportsEligible && metadata.kind === "unavailable")
const subpath = request.packageSubpath;
if (request.dependencyExportsEligible && metadata.kind === "unavailable")
return unresolvedCandidate("unavailable", [metadata.limitation]);
const rawExports =
exportsEligible && metadata.kind === "available"
request.dependencyExportsEligible && metadata.kind === "available"
? metadata.exports
: undefined;
if (rawExports === undefined) {
Expand All @@ -437,8 +420,17 @@ const resolvePackageSpecifier = (
resolveFileCandidates(input, fileCandidates(directory)) ??
resolveDirectory(input, directory, metadata, new Set())
);
// Preserve the trailing slash for a package directory request.
const candidate = confineCandidate(`${directory}/${subpath.slice(2)}`);
// Resolve legacy ESM subpaths as URLs: suffixes identify the loaded module
// but do not belong to its filesystem path. Keep the declared specifier on
// the relationship; only derive the inventory lookup path here.
const fileSubpath =
input.moduleKind === "import"
? decodeModuleUrlPath(stripQueryAndFragment(subpath.slice(2)))
: subpath.slice(2);
Comment thread
morluto marked this conversation as resolved.
Resolved
if (typeof fileSubpath !== "string") return fileSubpath;
const candidate = confineCandidate(`${directory}/${fileSubpath}`);
if (input.moduleKind === "import" && typeof candidate === "string")
return resolveLegacyEsmSubpath(input, candidate);
return typeof candidate === "string"
? resolveCandidate(input, candidate, new Set())
: candidate;
Expand All @@ -451,6 +443,21 @@ const resolvePackageSpecifier = (
);
};

/** Legacy ESM package subpaths are exact URLs, never extension or directory lookups. */
const resolveLegacyEsmSubpath = (
input: ResolveArtifactPathInput,
candidate: string,
): CandidateResolution => {
const file = resolveFileCandidates(input, [candidate]);
if (file !== null) return file;
const source = input.files.get(input.sourcePath);
if (hasContainerDirectory(input.files, candidate, source?.container_sha256))
return unresolvedCandidate("rejected", [
`ESM package subpath ${candidate} names a directory; directory imports are unsupported and package main or index lookup was not attempted.`,
]);
return exactPackageTargetNotFound(candidate, "ESM subpath");
};

const resolvePackageExports = (
input: ResolveArtifactPathInput,
packagePath: string,
Expand Down Expand Up @@ -517,23 +524,36 @@ const resolveExportTarget = (
);
};

const barePackageName = (specifier: string): string | null => {
const segments = specifier.split("/");
if (specifier.startsWith("@"))
return segments.length >= 2 && segments[0] !== "" && segments[1] !== ""
? `${segments[0]}/${segments[1]}`
: null;
return segments[0] === "" ? null : (segments[0] ?? null);
};
/** Derived package identity and dependency policy; input retains the raw request. */
interface BarePackageRequest {
readonly packageName: string;
readonly packageSubpath: string;
readonly dependencyExportsEligible: boolean;
}

const packageExportsEligible = (input: ResolveArtifactPathInput): boolean => {
if (input.moduleKind !== "require") return true;
const parseBarePackageRequest = (
specifier: string,
moduleKind: ResolveArtifactPathInput["moduleKind"],
): BarePackageRequest | null => {
const segments = specifier.split("/");
let packageName = segments[0] ?? "";
if (packageName === "") return null;
if (specifier.startsWith("@")) {
const packageSegment = segments[1];
if (packageSegment === undefined || packageSegment === "") return null;
packageName = `${packageName}/${packageSegment}`;
}
// Node's CommonJS exports matcher excludes percent-containing package names.
// Compare the captured name so a scoped name cannot fall back to its scope.
const match = /^((?:@[^/\\%]+\/)?[^./\\%][^/\\%]*)(\/.*)?$/.exec(
input.declaredPath,
);
return match?.[1] === barePackageName(input.declaredPath);
const dependencyExportsEligible =
moduleKind !== "require" ||
/^((?:@[^/\\%]+\/)?[^./\\%][^/\\%]*)(\/.*)?$/.exec(specifier)?.[1] ===
packageName;
return {
packageName,
packageSubpath: `.${specifier.slice(packageName.length)}`,
dependencyExportsEligible,
};
};

const hasContainerDirectory = (
Expand Down Expand Up @@ -1061,12 +1081,12 @@ const notFoundCandidate = (): CandidateResolution => ({

const exactPackageTargetNotFound = (
path: string,
mapKind: "exports" | "imports",
targetKind: "exports" | "imports" | "ESM subpath",
): CandidateResolution => ({
resolvedPath: null,
status: "not-found",
limitations: [
`The selected package ${mapKind === "imports" ? "import" : "exports"} target ${path} does not exist in the inventoried artifact container; ${mapKind === "imports" ? "import" : "exports"} targets are exact files, so no extension or directory index was tried.`,
`The selected package ${targetKind === "imports" ? "import" : targetKind} target ${path} does not exist in the inventoried artifact container; ${targetKind === "imports" ? "import" : targetKind} targets are exact files, so no extension or directory index was tried.`,
],
});

Expand Down
2 changes: 1 addition & 1 deletion src/browser/WebSourceMapFetcher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ import type {
import { webSourceMapsSchema } from "../domain/webBundleAnalysis.js";
import { createWebTextArtifact } from "../domain/webContentArtifact.js";
import { safeParseJson } from "../domain/safeJson.js";
import { sourceMapJsonText } from "../domain/sourceMapEnvelope.js";
import { jsonParts } from "../domain/jsonSerialization.js";
import {
inspectSourceMapValue,
sourceMapJsonText,
SourceMapFormatFailure,
type SourceMapLeaf,
} from "../javascript/sourceMaps/SourceMapFormat.js";
Expand Down
Loading
Loading