Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(javascript): resolve exact package import aliases (#1862)
Matt Van Hornd28b41ea4e93
diff --git a/.agents/skills/reverse-engineer-anything/references/javascript-applications.md b/.agents/skills/reverse-engineer-anything/references/javascript-applications.mdindex f40d3113a..82645590a 100644--- a/.agents/skills/reverse-engineer-anything/references/javascript-applications.md+++ b/.agents/skills/reverse-engineer-anything/references/javascript-applications.md@@ -9,7 +9,10 @@ provenance; inputs and recovered code are never executed. Recovery requires acaller-supplied Wakaru on Linux x64; see [the recovery guide](https://github.com/morluto/rea/blob/main/docs/javascript-recovery.md).Use `analyze_javascript_application` directly on the operator-supplied ASAR or-extracted tree. When size is unknown or large and the connected schema advertises+extracted tree. Exact `#alias` specifiers resolve through the importer's+enclosing package `imports` map to package-local files; nested `node_modules`+packages use their own map. Wildcard, recursive, and external-package import+targets stay unresolved with that limitation. When size is unknown or large and the connected schema advertises`detail`, request `detail: "summary"`. This returns an `inspect_analysis_view`Evidence record with a distinct ID and a `normalized_result.parent_evidence_id`for the complete retained application analysis. Source-map contents are part ofdiff --git a/docs/javascript-artifact-reconstruction.md b/docs/javascript-artifact-reconstruction.mdindex 7442fc746..fbafe042e 100644--- a/docs/javascript-artifact-reconstruction.md+++ b/docs/javascript-artifact-reconstruction.md@@ -452,9 +452,29 @@ such as `./web3:app.js` still names a local artifact.Package `exports` fallback arrays are supported both at the top level and underthe root `"."` entry. The resolver selects targets in declared order using thesame conditional and invalid-entry handling as nested exports arrays.+Nonempty arrays containing only inactive conditions remain unmatched, allowing+the enclosing condition object to continue to a later active condition.+Empty arrays and explicit null targets keep their blocking outcome.+Refusal evidence distinguishes those source values and retains condition names+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.+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+an ancestor's aliases. Selected targets are package-local `./` files with no+extension or index fallback, using the same condition, array, and null selection+as exports subpaths. A missing key, explicit null, or out-of-scope alias keeps+an unresolved edge with that reason. Wildcard keys (`#internal/*`), recursive+`#` targets, and external-package import targets remain unresolved.++Exact keys such as `#/x` are literal lookup identities. `#` and names ending+in `/` are invalid. Imports arrays skip invalid parent-relative, absolute, and+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 handlingand one percent-decoding pass. CommonJS relative paths and legacy package mainfields retain literal filename punctuation. Exports targets must start withdiff --git a/src/application/javascript/JavaScriptArtifactPathResolution.test.ts b/src/application/javascript/JavaScriptArtifactPathResolution.test.tsindex 9a79f84d1..491d5236d 100644--- a/src/application/javascript/JavaScriptArtifactPathResolution.test.ts+++ b/src/application/javascript/JavaScriptArtifactPathResolution.test.ts@@ -868,6 +868,365 @@ describe("package exports exact targets", () => {});});+describe("package import alias resolution", () => {+ it.each(["import", "require"] as const)(+ "resolves an exact #%s alias from the enclosing package imports map",+ (moduleKind) => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#config": "./config.cjs" },+ }),+ "main.js": "",+ "config.cjs": "",+ });+ expect(+ resolve({+ declaredPath: "#config",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind,+ files,+ }),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "config.cjs",+ declared_path: "#config",+ });+ },+ );++ it("resolves an alias from a nested file through the enclosing package root", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#config": "./config.cjs" },+ }),+ "src/main.js": "",+ "config.cjs": "",+ });+ expect(+ resolve({+ declaredPath: "#config",+ sourcePath: "src/main.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ }),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "config.cjs",+ });+ });++ it("uses a nested package imports map rather than the application root", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#config": "./root.cjs" },+ }),+ "root.cjs": "",+ "node_modules/fixture/package.json": JSON.stringify({+ imports: { "#config": "./local.cjs" },+ }),+ "node_modules/fixture/index.js": "",+ "node_modules/fixture/local.cjs": "",+ });+ expect(+ resolve({+ declaredPath: "#config",+ sourcePath: "node_modules/fixture/index.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ }),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "node_modules/fixture/local.cjs",+ });+ });++ it("does not inherit an ancestor imports map across a nested package.json", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#config": "./root.cjs" },+ }),+ "root.cjs": "",+ "node_modules/fixture/package.json": "{}",+ "node_modules/fixture/index.js": "",+ });+ const outcome = resolve({+ declaredPath: "#config",+ sourcePath: "node_modules/fixture/index.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ });+ expect(outcome).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(outcome.limitations.join(" ")).toContain(+ "node_modules/fixture/package.json",+ );+ expect(outcome.limitations.join(" ")).not.toContain("root.cjs");+ });++ it("does not apply a nested package map to the application root importer", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#config": "./root.cjs" },+ }),+ "main.js": "",+ "root.cjs": "",+ "node_modules/fixture/package.json": JSON.stringify({+ imports: { "#config": "./local.cjs" },+ }),+ "node_modules/fixture/local.cjs": "",+ });+ expect(+ resolve({+ declaredPath: "#config",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ }),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "root.cjs",+ });+ });+});++describe("package import alias target selection", () => {+ it("selects import and require conditions from an imports target", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: {+ "#config": {+ import: "./config.mjs",+ require: "./config.cjs",+ default: "./fallback.js",+ },+ },+ }),+ "main.js": "",+ "config.mjs": "",+ "config.cjs": "",+ "fallback.js": "",+ });+ expect(+ resolve({+ declaredPath: "#config",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "import",+ files,+ }).resolved_path,+ ).toBe("config.mjs");+ expect(+ resolve({+ declaredPath: "#config",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ }).resolved_path,+ ).toBe("config.cjs");+ });++ it("resolves array import targets at their first string entry", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#config": [{ import: "./missing.mjs" }, "./config.cjs"] },+ }),+ "main.js": "",+ "config.cjs": "",+ });+ expect(+ resolve({+ declaredPath: "#config",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ }),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "config.cjs",+ });+ });++ it("does not add an extension or index to a selected import target", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#config": "./config" },+ }),+ "main.js": "",+ "config.cjs": "",+ "config/index.js": "",+ });+ const outcome = resolve({+ declaredPath: "#config",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ });+ expect(outcome).toMatchObject({+ resolution_status: "not-found",+ resolved_path: null,+ });+ expect(outcome.limitations.join(" ")).toContain(+ "import targets are exact files",+ );+ });+});++describe("package import alias refusals", () => {+ it("reports a missing exact alias without looking in another package", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#config": "./config.cjs" },+ }),+ "main.js": "",+ "config.cjs": "",+ });+ const outcome = resolve({+ declaredPath: "#other",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ });+ expect(outcome).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(outcome.limitations.join(" ")).toContain("#other");+ expect(outcome.limitations.join(" ")).toContain("#config");+ });++ it("reports an explicit null import target as blocked", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#config": null },+ }),+ "main.js": "",+ "config.cjs": "",+ });+ const outcome = resolve({+ declaredPath: "#config",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ });+ expect(outcome).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(outcome.limitations.join(" ")).toContain("explicit null");+ });++ it("leaves wildcard import aliases unresolved", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#internal/*": "./src/*.js" },+ }),+ "main.js": "",+ "src/util.js": "",+ });+ const outcome = resolve({+ declaredPath: "#internal/util",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "import",+ files,+ });+ expect(outcome).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(outcome.limitations.join(" ")).toMatch(/wildcard/i);+ });++ it("leaves recursive and external-package import targets unresolved", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#loop": "#config", "#dep": "fixture" },+ }),+ "main.js": "",+ "node_modules/fixture/index.js": "",+ });+ const recursive = resolve({+ declaredPath: "#loop",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ });+ const external = resolve({+ declaredPath: "#dep",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ });+ expect(recursive).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(recursive.limitations.join(" ")).toMatch(/recursive/i);+ expect(external).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(external.limitations.join(" ")).toMatch(/external-package/i);+ });++ it("rejects reserved hash specifiers", () => {+ const files = aliasFiles({+ "package.json": JSON.stringify({+ imports: { "#config": "./config.cjs" },+ }),+ "main.js": "",+ "config.cjs": "",+ });+ expect(+ resolve({+ declaredPath: "#",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "import",+ files,+ }),+ ).toMatchObject({ resolution_status: "rejected", resolved_path: null });+ });++ it("does not use a foreign-container enclosing package.json", () => {+ const files = fileMap([+ file(+ "package.json",+ "other",+ JSON.stringify({ imports: { "#config": "./config.cjs" } }),+ ),+ file("main.js", "root"),+ file("config.cjs", "root"),+ ]);+ const outcome = resolve({+ declaredPath: "#config",+ sourcePath: "main.js",+ context: "module-specifier",+ moduleKind: "require",+ files,+ });+ expect(outcome).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(outcome.limitations.join(" ")).toContain("package scopes");+ });+});+describe("directory package entrypoint precedence", () => {it.each([["require", '{"main":"actual.cjs"}', "actual.cjs"],@@ -1211,6 +1570,15 @@ const file = (: { included: true, value: text },});+const aliasFiles = (+ entries: Readonly<Record<string, string | null>>,+): ReturnType<typeof fileMap> =>+ fileMap(+ Object.entries(entries).map(([path, text]) =>+ file(path, "root", text ?? ""),+ ),+ );+describe("exact HTML resource resolution", () => {it.each([["extension", ["app.js"]],diff --git a/src/application/javascript/JavaScriptArtifactPathResolution.ts b/src/application/javascript/JavaScriptArtifactPathResolution.tsindex 73d82e91b..b6bbde2b6 100644--- a/src/application/javascript/JavaScriptArtifactPathResolution.ts+++ b/src/application/javascript/JavaScriptArtifactPathResolution.ts@@ -14,6 +14,11 @@ import {percentDecodeUrlPath,stripQueryAndFragment,} from "../../domain/artifactPathSyntax.js";+import {+ classifyPackageImportSpecifier,+ classifyPackageImportTargetString,+ lookupExactPackageImport,+} from "../../domain/javascript/javascriptPackageImportAliases.js";type ArtifactPathResolutionContext =| "package-entrypoint"@@ -103,6 +108,13 @@ export const resolveArtifactPathByContext = (};const resolvePath = (input: ResolveArtifactPathInput): CandidateResolution => {+ // Package import keys are literal lookup identities, not artifact paths.+ // The selected target is admitted separately by resolveExportTarget.+ if (+ input.context === "module-specifier" &&+ input.declaredPath.startsWith("#")+ )+ return resolvePackageImportAlias(input, input.declaredPath);const rejected = rejectDeclaration(input.declaredPath);if (rejected !== null) return rejected;const candidate = contextualCandidate(input);@@ -202,9 +214,9 @@ const bareModuleCandidate = (declared: string,): CandidateResolution => {const packageName = barePackageName(declared);- if (packageName === null || isBuiltin(declared) || declared.startsWith("#"))+ if (packageName === null || isBuiltin(declared))return unresolvedCandidate("external", [- "The bare specifier is a Node builtin, package import map, or invalid package name.",+ "The bare specifier is a Node builtin or invalid package name.",]);if (input.moduleKind === "import" && packageName.includes("%"))return unresolvedCandidate("rejected", [@@ -235,42 +247,138 @@ const bareModuleCandidate = (]);};-/** Self references use the nearest package scope before dependency lookup. */-const commonJsSelfCandidate = (+/**+ * Nearest same-container package.json, stopping at a `node_modules` directory+ * so a nested package cannot inherit an ancestor's map.+ */+const enclosingPackageMetadata = (input: ResolveArtifactPathInput,- declared: string,-): CandidateResolution | null => {- if (input.moduleKind !== "require" || !input.files.has(input.sourcePath))- return null;+):+ | Extract<PackageMetadata, { readonly kind: "available" | "unavailable" }>+ | { readonly kind: "none" } => {let directory = posix.dirname(input.sourcePath);while (posix.basename(directory) !== "node_modules") {const metadata = readPackageMetadata(input, directory);- if (metadata.kind === "unavailable")- return unresolvedCandidate("unavailable", [metadata.limitation]);- if (metadata.kind === "available") {- if (- metadata.name === undefined ||- metadata.exports === undefined ||- (declared !== metadata.name &&- !declared.startsWith(`${metadata.name}/`))- )- return null;- const subpath =- declared === metadata.name- ? "."- : `.${declared.slice(metadata.name.length)}`;- // Self resolution does not apply the CommonJS dependency-name matcher.- return resolvePackageExports(- input,- metadata.path,- subpath,- metadata.exports,- );- }+ if (metadata.kind !== "absent") return metadata;if (directory === "." || directory === "") break;directory = posix.dirname(directory);}- return null;+ return { kind: "none" };+};++/**+ * Resolve an exact `#alias` against the importer's enclosing `imports` map.+ * Selected relative targets are exact files; patterns, recursive aliases, and+ * external-package targets stay unresolved without falling through.+ */+const resolvePackageImportAlias = (+ input: ResolveArtifactPathInput,+ specifier: string,+): CandidateResolution => {+ const classified = classifyPackageImportSpecifier(specifier);+ if (classified.kind === "invalid")+ return unresolvedCandidate("rejected", [+ `The package import specifier ${JSON.stringify(specifier)} is invalid; "#" and specifiers that end with "/" are not valid import aliases.`,+ ]);+ if (classified.kind === "pattern")+ return unresolvedCandidate("external", [+ `Wildcard and directory package import aliases remain unresolved; ${JSON.stringify(specifier)} is not an exact imports key.`,+ ]);+ const metadata = enclosingPackageMetadata(input);+ if (metadata.kind === "none")+ return unresolvedCandidate("external", [+ `No enclosing package.json defines package import alias ${specifier}; package import maps do not cross package scopes.`,+ ]);+ if (metadata.kind === "unavailable")+ return unresolvedCandidate("unavailable", [metadata.limitation]);+ const lookup = lookupExactPackageImport(metadata.imports, specifier);+ if (lookup.kind === "undefined-map")+ return unresolvedCandidate("external", [+ `Package metadata ${metadata.path} does not define package import alias ${specifier}.`,+ ]);+ if (lookup.kind === "missing-key")+ return unresolvedCandidate("external", [+ `Package metadata ${metadata.path} does not define package import alias ${specifier}; it declares ${lookup.declared.join(", ") || "no imports keys"}.`,+ ]);+ if (lookup.kind === "pattern-unresolved")+ return unresolvedCandidate("external", [+ `Wildcard package import aliases remain unresolved; package metadata ${metadata.path} has no exact imports key ${specifier}.`,+ ]);+ const selected = selectPackageImportTarget(lookup.target, input.moduleKind);+ if (selected.status === "rejected")+ return unresolvedCandidate("rejected", [+ `Package metadata ${metadata.path}: ${selected.limitation}`,+ ]);+ if (selected.status === "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")+ 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") {+ const target = classifyPackageImportTargetString(selected.value);+ return unresolvedCandidate("external", [+ target.kind === "recursive"+ ? `Recursive package import aliases remain unresolved; package metadata ${metadata.path} maps ${specifier} to ${JSON.stringify(target.target)}.`+ : `External-package import targets remain unresolved; package metadata ${metadata.path} maps ${specifier} to ${JSON.stringify(target.target)}.`,+ ]);+ }+ return resolveExportTarget(input, metadata.path, selected.value, "imports");+};++const selectPackageImportTarget = (+ value: unknown,+ moduleKind: ResolveArtifactPathInput["moduleKind"],+):+ | { readonly status: "value"; readonly value: string }+ | { 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),+ "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 };+};++/** Self references use the nearest package scope before dependency lookup. */+const commonJsSelfCandidate = (+ input: ResolveArtifactPathInput,+ declared: string,+): CandidateResolution | null => {+ if (input.moduleKind !== "require" || !input.files.has(input.sourcePath))+ 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}/`))+ )+ return null;+ const subpath =+ declared === metadata.name+ ? "."+ : `.${declared.slice(metadata.name.length)}`;+ // 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. */@@ -324,16 +432,17 @@ const resolvePackageExports = (]);if (exported.status === "blocked")return unresolvedCandidate("external", [- `Directory package metadata ${packagePath} blocks subpath ${subpath} with an explicit null exports target.`,+ `Directory package metadata ${packagePath} blocks subpath ${subpath} with ${exported.cause === "null" ? "an explicit null exports target" : "an empty exports target array"}.`,]);return resolveExportTarget(input, packagePath, exported.value);};-/** An exports target is a URL naming one exact file for both Node loaders. */+/** An exports or import target is a URL naming one exact file for both Node loaders. */const resolveExportTarget = (input: ResolveArtifactPathInput,packagePath: string,target: string,+ mapKind: "exports" | "imports" = "exports",): CandidateResolution => {const rejected = rejectDeclaration(target);if (rejected !== null) return rejected;@@ -343,7 +452,7 @@ const resolveExportTarget = (if (typeof candidate !== "string") return candidate;return (resolveFileCandidates(input, [candidate]) ??- exactExportsTargetNotFound(candidate)+ exactPackageTargetNotFound(candidate, mapKind));};@@ -492,6 +601,7 @@ type PackageMetadata =readonly path: string;readonly name: string | undefined;readonly exports: string | object | undefined;+ readonly imports: object | undefined;readonly main: unknown;readonly module: unknown;}@@ -532,6 +642,7 @@ const readPackageMetadata = (};const name = Reflect.get(value, "name");const exports = Reflect.get(value, "exports");+ const imports = Reflect.get(value, "imports");return {kind: "available",path,@@ -543,6 +654,11 @@ const readPackageMetadata = ((typeof exports === "object" && exports !== null)? exports: undefined,+ // Import maps must be non-array objects; other shapes are not a map.+ imports:+ typeof imports === "object" && imports !== null && !Array.isArray(imports)+ ? imports+ : undefined,main: Reflect.get(value, "main"),module: Reflect.get(value, "module"),};@@ -644,10 +760,12 @@ const fileCandidates = (candidate: string): readonly string[] => [const indexCandidates = (candidate: string): readonly string[] =>EXTENSIONS.map((extension) => posix.join(candidate, `index${extension}`));+type PackageTargetBlockCause = "null" | "empty-array";+type PackageExportOutcome =| { readonly status: "value"; readonly value: string }| { readonly status: "rejected"; readonly limitation: string }- | { readonly status: "blocked" }+ | { readonly status: "blocked"; readonly cause: PackageTargetBlockCause }| { readonly status: "unmatched"; readonly declared: readonly string[] };/** Only exact non-directory keys participate; wildcard expansion is unsupported. */@@ -687,29 +805,33 @@ const selectPackageExport = (if (selected.kind === "unmatched")return {status: "unmatched",- declared:- typeof target === "object" && target !== null- ? Object.keys(target)- : declared,+ declared: selected.declared,+ };+ if (selected.kind === "blocked")+ return { status: "blocked", cause: selected.cause };+ if (selected.kind === "non-relative")+ return {+ status: "rejected",+ limitation: `The package exports target ${JSON.stringify(selected.value)} must start with "./".`,};- return selected.kind === "blocked"- ? { status: "blocked" }- : { status: "value", value: selected.value };+ return { status: "value", value: selected.value };};type ExportTargetOutcome =| { readonly kind: "value"; readonly value: string }- | { readonly kind: "blocked" }- | { readonly kind: "unmatched" }+ | { readonly kind: "non-relative"; readonly value: string }+ | { readonly kind: "blocked"; readonly cause: PackageTargetBlockCause }+ | { readonly kind: "unmatched"; readonly declared: readonly string[] }| { readonly kind: "invalid"; readonly limitation: string }| { readonly kind: "invalid-config"; readonly limitation: string };const invalidExportTarget = (value: unknown,reason: string,+ mapKind: "exports" | "imports" = "exports",): ExportTargetOutcome => ({kind: "invalid",- limitation: `The package exports target ${JSON.stringify(value) ?? String(value)} ${reason}.`,+ limitation: `The package ${mapKind === "imports" ? "import" : "exports"} target ${JSON.stringify(value) ?? String(value)} ${reason}.`,});// Node checks raw target segments before URL normalization. Compare encoded@@ -729,50 +851,80 @@ const forbiddenExportSegment = (value: string): string | undefined =>);});+const selectStringPackageTarget = (+ value: string,+ mapKind: "exports" | "imports",+): ExportTargetOutcome => {+ if (mapKind === "imports") {+ const target = classifyPackageImportTargetString(value);+ if (target.kind === "invalid")+ return invalidExportTarget(+ value,+ "cannot be parent-relative, absolute, or a URL",+ mapKind,+ );+ if (target.kind !== "relative") return { kind: "non-relative", value };+ } else if (!value.startsWith("./"))+ return invalidExportTarget(value, 'must start with "./"', mapKind);+ const forbidden = forbiddenExportSegment(value);+ return forbidden === undefined+ ? { kind: "value", value }+ : invalidExportTarget(+ value,+ `contains forbidden path segment ${JSON.stringify(forbidden)} before URL normalization`,+ mapKind,+ );+};++const selectArrayPackageTarget = (+ value: readonly unknown[],+ conditions: ReadonlySet<string>,+ mapKind: "exports" | "imports",+): ExportTargetOutcome => {+ if (value.length === 0) return { kind: "blocked", cause: "empty-array" };+ let lastRefusal:+ | Extract<ExportTargetOutcome, { readonly kind: "invalid" | "blocked" }>+ | undefined;+ const declared = new Set<string>();+ for (const entry of value) {+ const nested = selectExportTarget(entry, conditions, mapKind);+ // Node's array fallback catches invalid targets, not invalid configuration.+ if (nested.kind === "invalid-config") return nested;+ if (nested.kind === "unmatched") {+ for (const condition of nested.declared) declared.add(condition);+ continue;+ }+ if (nested.kind === "invalid" || nested.kind === "blocked") {+ lastRefusal = nested;+ continue;+ }+ return nested;+ }+ return lastRefusal ?? { kind: "unmatched", declared: [...declared] };+};+/*** Resolve a target in Node's declared order. Explicit null blocks an active* condition, whereas an unmatched nested object permits the next condition.* An array skips unmatched and invalid entries, stops at its first string, and- * preserves the final invalid-versus-null refusal if no string is selected.+ * preserves the last invalid/null outcome if no string is selected. A nonempty+ * array of unmatched conditions stays unmatched; an empty array blocks.*/const selectExportTarget = (value: unknown,conditions: ReadonlySet<string>,+ mapKind: "exports" | "imports" = "exports",): ExportTargetOutcome => {- if (typeof value === "string") {- if (!value.startsWith("./"))- return invalidExportTarget(value, 'must start with "./"');- const forbidden = forbiddenExportSegment(value);- return forbidden === undefined- ? { kind: "value", value }- : invalidExportTarget(- value,- `contains forbidden path segment ${JSON.stringify(forbidden)} before URL normalization`,- );- }- if (value === null) return { kind: "blocked" };- if (Array.isArray(value)) {- let invalid: string | null = null;- for (const entry of value) {- const nested = selectExportTarget(entry, conditions);- // Node's array fallback catches invalid targets, not invalid configuration.- if (nested.kind === "invalid-config") return nested;- if (nested.kind === "invalid") {- invalid = nested.limitation;- continue;- }- if (nested.kind === "unmatched") continue;- invalid = null;- if (nested.kind === "value") return nested;- }- return invalid === null- ? { kind: "blocked" }- : { kind: "invalid", limitation: invalid };- }+ if (typeof value === "string")+ return selectStringPackageTarget(value, mapKind);+ if (value === null) return { kind: "blocked", cause: "null" };+ if (Array.isArray(value))+ return selectArrayPackageTarget(value, conditions, mapKind);if (typeof value !== "object")return invalidExportTarget(value,"must be a relative string, object, array, or null",+ mapKind,);for (const key of Object.keys(value)) {const numeric = Number(key);@@ -782,12 +934,15 @@ const selectExportTarget = (limitation: `The package exports configuration contains numeric condition key ${JSON.stringify(key)}.`,};}+ const declared = new Set<string>();for (const [condition, target] of Object.entries(value)) {+ declared.add(condition);if (!conditions.has(condition)) continue;- const nested = selectExportTarget(target, conditions);+ const nested = selectExportTarget(target, conditions, mapKind);if (nested.kind !== "unmatched") return nested;+ for (const name of nested.declared) declared.add(name);}- return { kind: "unmatched" };+ return { kind: "unmatched", declared: [...declared] };};/**@@ -816,11 +971,14 @@ const notFoundCandidate = (): CandidateResolution => ({],});-const exactExportsTargetNotFound = (path: string): CandidateResolution => ({+const exactPackageTargetNotFound = (+ path: string,+ mapKind: "exports" | "imports",+): CandidateResolution => ({resolvedPath: null,status: "not-found",limitations: [- `The selected package exports target ${path} does not exist in the inventoried artifact container; exports targets are exact files, so no extension or directory index was tried.`,+ `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.`,],});diff --git a/src/domain/javascript/javascriptPackageImportAliases.test.ts b/src/domain/javascript/javascriptPackageImportAliases.test.tsnew file mode 100644index 000000000..6f64c1d65--- /dev/null+++ b/src/domain/javascript/javascriptPackageImportAliases.test.ts@@ -0,0 +1,147 @@+import { describe, expect, it } from "vitest";++import {+ classifyPackageImportSpecifier,+ classifyPackageImportTargetString,+ lookupExactPackageImport,+} from "./javascriptPackageImportAliases.js";++describe("package import specifier classification", () => {+ it("treats an exact hash alias as an exact key", () => {+ expect(classifyPackageImportSpecifier("#config")).toEqual({+ kind: "exact",+ key: "#config",+ });+ });++ it.each(["#internal/env", "#/hidden"])(+ "treats %j as an exact key",+ (specifier) => {+ expect(classifyPackageImportSpecifier(specifier)).toEqual({+ kind: "exact",+ key: specifier,+ });+ },+ );++ it.each(["#", "#/", "#utils/"])(+ "rejects reserved specifier %j",+ (specifier) => {+ expect(classifyPackageImportSpecifier(specifier)).toEqual({+ kind: "invalid",+ });+ },+ );++ it.each(["#internal/*", "#*"])(+ "leaves pattern specifier %j unresolved",+ (specifier) => {+ expect(classifyPackageImportSpecifier(specifier)).toEqual({+ kind: "pattern",+ });+ },+ );+});++describe("exact package import lookup", () => {+ it("returns the exact target without falling through to another key", () => {+ expect(+ lookupExactPackageImport(+ { "#config": "./config.cjs", "#other": "./other.cjs" },+ "#config",+ ),+ ).toEqual({+ kind: "found",+ target: "./config.cjs",+ declared: ["#config", "#other"],+ });+ });++ it("names declared exact keys when the requested alias is absent", () => {+ expect(+ lookupExactPackageImport({ "#config": "./config.cjs" }, "#missing"),+ ).toEqual({+ kind: "missing-key",+ declared: ["#config"],+ });+ });++ it("does not claim a miss when the map only has pattern keys", () => {+ expect(+ lookupExactPackageImport({ "#internal/*": "./src/*.js" }, "#internal/a"),+ ).toEqual({+ kind: "pattern-unresolved",+ declared: ["#internal/*"],+ });+ });++ it("still selects an exact key when the same map also has patterns", () => {+ expect(+ lookupExactPackageImport(+ { "#config": "./config.cjs", "#internal/*": "./src/*.js" },+ "#config",+ ),+ ).toEqual({+ kind: "found",+ target: "./config.cjs",+ declared: ["#config", "#internal/*"],+ });+ });++ it.each([undefined, null, "./config.cjs", ["#config"], 7] as const)(+ "treats non-object imports value %j as an undefined map",+ (imports) => {+ expect(lookupExactPackageImport(imports, "#config")).toEqual({+ kind: "undefined-map",+ });+ },+ );++ it("does not treat a pattern key as an exact match for itself", () => {+ expect(+ lookupExactPackageImport({ "#internal/*": "./src/*.js" }, "#internal/*"),+ ).toEqual({+ kind: "pattern-unresolved",+ declared: ["#internal/*"],+ });+ });+});++describe("package import target string classification", () => {+ it("keeps package-local relative targets", () => {+ expect(classifyPackageImportTargetString("./config.cjs")).toEqual({+ kind: "relative",+ target: "./config.cjs",+ });+ });++ it("marks recursive hash aliases as recursive", () => {+ expect(classifyPackageImportTargetString("#other")).toEqual({+ kind: "recursive",+ target: "#other",+ });+ });++ it.each(["lodash", "pkg/subpath"])(+ "marks %j as an external-package target",+ (target) => {+ expect(classifyPackageImportTargetString(target)).toEqual({+ kind: "external-package",+ target,+ });+ },+ );++ it.each([+ "../outside.js",+ "/outside.js",+ "https://example.invalid/mod.js",+ "file:///outside.js",+ "node:fs",+ ])("marks %j as an invalid import target", (target) => {+ expect(classifyPackageImportTargetString(target)).toEqual({+ kind: "invalid",+ target,+ });+ });+});diff --git a/src/domain/javascript/javascriptPackageImportAliases.ts b/src/domain/javascript/javascriptPackageImportAliases.tsnew file mode 100644index 000000000..9eab77e10--- /dev/null+++ b/src/domain/javascript/javascriptPackageImportAliases.ts@@ -0,0 +1,98 @@+/**+ * Exact package-private import-alias lookup. Node resolves `#` specifiers+ * against the importer's enclosing package `imports` map; this module owns the+ * specifier and exact-key rules. Condition, array, and null target selection+ * stay with the shared package-target machinery. Wildcard keys, recursive+ * `#` targets, and external-package targets remain explicit unknowns.+ */++/** How one `#` specifier participates in exact import-alias lookup. */+export type PackageImportSpecifierClassification =+ | { readonly kind: "invalid" }+ | { readonly kind: "pattern" }+ | { readonly kind: "exact"; readonly key: string };++/** Outcome of looking up one exact `#` key in a package `imports` object. */+export type PackageImportExactLookup =+ | { readonly kind: "undefined-map" }+ | {+ readonly kind: "missing-key";+ readonly declared: readonly string[];+ }+ | {+ readonly kind: "pattern-unresolved";+ readonly declared: readonly string[];+ }+ | {+ readonly kind: "found";+ readonly target: unknown;+ readonly declared: readonly string[];+ };++/** How a selected string target is interpreted for package-private imports. */+export type PackageImportTargetClassification =+ | { readonly kind: "relative"; readonly target: string }+ | { readonly kind: "invalid"; readonly target: string }+ | { readonly kind: "recursive"; readonly target: string }+ | { readonly kind: "external-package"; readonly target: string };++/**+ * Classify a `#` module specifier before any package-scope walk.+ * `#` and names ending in `/` are invalid. Other literal keys, including+ * `#/…`, participate in exact lookup; wildcard expansion remains unsupported.+ */+export const classifyPackageImportSpecifier = (+ specifier: string,+): PackageImportSpecifierClassification => {+ if (specifier === "#" || specifier.endsWith("/")) return { kind: "invalid" };+ if (specifier.includes("*")) return { kind: "pattern" };+ return { kind: "exact", key: specifier };+};++/** True when an `imports` key is a pattern rather than an exact alias. */+export const isPackageImportPatternKey = (key: string): boolean =>+ key.includes("*") || key.endsWith("/");++/**+ * Look up one exact `#` key in a package `imports` value.+ * A missing exact key is reported as missing when every declared key is also+ * exact; if the map contains pattern keys, the miss stays pattern-unresolved+ * rather than claiming the specifier is undefined.+ */+export const lookupExactPackageImport = (+ imports: unknown,+ key: string,+): PackageImportExactLookup => {+ if (typeof imports !== "object" || imports === null || Array.isArray(imports))+ return { kind: "undefined-map" };+ const declared = Object.keys(imports);+ if (Object.hasOwn(imports, key) && !isPackageImportPatternKey(key))+ return {+ kind: "found",+ target: Reflect.get(imports, key),+ declared,+ };+ return declared.some(isPackageImportPatternKey)+ ? { kind: "pattern-unresolved", declared }+ : { kind: "missing-key", declared };+};++/**+ * Classify a selected string import target. Only package-local `./` paths are+ * resolved as files; recursive `#` aliases and bare packages stay unknown.+ * Parent-relative, absolute, and URL targets are invalid, allowing array+ * selection to skip them before choosing a package-local fallback.+ */+export const classifyPackageImportTargetString = (+ target: string,+): PackageImportTargetClassification => {+ if (target.startsWith("./")) return { kind: "relative", target };+ if (+ target.startsWith("../") ||+ target.startsWith("/") ||+ URL.canParse(target)+ )+ return { kind: "invalid", target };+ if (target.startsWith("#")) return { kind: "recursive", target };+ return { kind: "external-package", target };+};diff --git a/tests/acceptance/applications/packageImportAliasesCli.test.ts b/tests/acceptance/applications/packageImportAliasesCli.test.tsnew file mode 100644index 000000000..90927dfa1--- /dev/null+++ b/tests/acceptance/applications/packageImportAliasesCli.test.ts@@ -0,0 +1,251 @@+import { createHash } from "node:crypto";+import { mkdir, writeFile } from "node:fs/promises";+import { createRequire } from "node:module";+import { dirname, join, relative } from "node:path";++import { expect } from "vitest";+import { z } from "zod";++import { javascriptApplicationAnalysisResultSchema } from "../../../src/domain/javascript/javascriptApplicationAnalysis.js";+import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { cliTest } from "../../support/cli/cliFixture.js";++const literalAliases = ["#/x", "#x%2Fy", "#x%2Ey", "#x\\y", "#x\0y"];+const fallbackAliases = {+ "#inactive-array": {+ node: [{ browser: "./browser.cjs" }],+ default: "./config.cjs",+ },+ "#nested-inactive-array": {+ node: [[{ browser: "./browser.cjs" }]],+ default: "./config.cjs",+ },+ "#parent": ["../outside.cjs", "./config.cjs"],+ "#absolute": { node: [["/outside.cjs"], "./config.cjs"] },+ "#url": {+ import: ["https://example.invalid/outside.cjs", "./config.cjs"],+ require: ["file:///outside.cjs", "./config.cjs"],+ },+};+const resolvedAliases = [...literalAliases, ...Object.keys(fallbackAliases)];+const refusedAliases = {+ "#empty": { target: [], limitation: "an empty imports target array" },+ "#empty-active": {+ target: { node: [] },+ limitation: "an empty imports target array",+ },+ "#null-last": {+ target: [[], null],+ limitation: "an explicit null imports target",+ },+ "#empty-last": {+ target: [null, []],+ limitation: "an empty imports target array",+ },+ "#inactive": {+ target: [{ browser: "./browser.cjs" }],+ limitation: "it declares browser.",+ },+ "#nested-inactive": {+ target: [+ [{ browser: "./browser.cjs" }, { "rea-inactive": "./inactive.cjs" }],+ ],+ limitation: "it declares browser, rea-inactive.",+ },+};+const allAliases = [...resolvedAliases, ...Object.keys(refusedAliases)];++const createPackageImportAliasFixture = async () => {+ const root = await createTestTempDirectory("rea-package-import-aliases-");+ const mainSource = [+ 'const config = require("#config");',+ 'const nested = require("./node_modules/fixture/index.cjs");',+ 'const missing = require("#missing");',+ ...allAliases.map((specifier) => `require(${JSON.stringify(specifier)});`),+ ].join("\n");+ const moduleSource = allAliases+ .map((specifier) => `import ${JSON.stringify(specifier)};`)+ .join("\n");+ const nestedSource = [+ 'const config = require("#config");',+ "module.exports = config;",+ ].join("\n");+ const files = {+ "package.json": JSON.stringify({+ name: "app",+ imports: {+ "#config": "./config.cjs",+ ...Object.fromEntries(+ literalAliases.map((specifier) => [specifier, "./config.cjs"]),+ ),+ ...fallbackAliases,+ ...Object.fromEntries(+ Object.entries(refusedAliases).map(([specifier, { target }]) => [+ specifier,+ target,+ ]),+ ),+ },+ }),+ "main.cjs": mainSource,+ "main.mjs": moduleSource,+ "config.cjs": "module.exports = 'app-config';",+ "node_modules/fixture/package.json": JSON.stringify({+ name: "fixture",+ imports: { "#config": "./local.cjs" },+ }),+ "node_modules/fixture/index.cjs": nestedSource,+ "node_modules/fixture/local.cjs": "module.exports = 'fixture-config';",+ };+ await Promise.all(+ Object.entries(files).map(async ([path, content]) => {+ const absolute = join(root, path);+ await mkdir(dirname(absolute), { recursive: true });+ await writeFile(absolute, content);+ }),+ );+ return { root, mainSource, moduleSource, nestedSource };+};++cliTest.for(["CLI", "stdio MCP"] as const)(+ "resolves exact package import aliases with package scope through %s",+ async (surface, { cli }) => {+ const { root, mainSource, moduleSource, nestedSource } =+ await createPackageImportAliasFixture();+ const nativeRequire = createRequire(join(root, "main.cjs"));+ expect(+ relative(root, nativeRequire.resolve("#config")).replaceAll("\\", "/"),+ ).toBe("config.cjs");+ expect(+ relative(+ root,+ createRequire(join(root, "node_modules/fixture/index.cjs")).resolve(+ "#config",+ ),+ ).replaceAll("\\", "/"),+ ).toBe("node_modules/fixture/local.cjs");+ expect(() => nativeRequire.resolve("#missing")).toThrow(+ expect.objectContaining({ code: "ERR_PACKAGE_IMPORT_NOT_DEFINED" }),+ );++ let document: unknown;+ if (surface === "CLI") {+ const response = await cli.run({+ arguments: ["analyze-javascript-application", root, "--format", "json"],+ environment: { REA_LOG_LEVEL: "silent" },+ });+ expect(response.exitCode, response.stderr).toBe(0);+ document = response.json;+ } else {+ const { call } = await connectLocalToolsMcp();+ const response = await call("analyze_javascript_application", {+ input_path: root,+ format: "directory",+ });+ expect(response.isError, JSON.stringify(response)).not.toBe(true);+ document = response.structuredContent;+ }+ const { graph } = z+ .object({ normalized_result: javascriptApplicationAnalysisResultSchema })+ .parse(document).normalized_result;+ for (const specifier of resolvedAliases)+ for (const [moduleKind, sourcePath, source] of [+ ["require", "main.cjs", mainSource],+ ["import", "main.mjs", moduleSource],+ ] as const)+ expect(graph.edges).toContainEqual(+ expect.objectContaining({+ properties: expect.objectContaining({+ module_link_kind: moduleKind,+ specifier,+ resolved_path: "config.cjs",+ resolution_status: "resolved",+ }),+ evidence: sourceEvidence(sourcePath, source),+ }),+ );+ const imports = graph.edges.filter(+ ({ properties }) => properties.module_link_kind === "require",+ );+ for (const [specifier, { limitation }] of Object.entries(refusedAliases))+ for (const [moduleKind, sourcePath, source] of [+ ["require", "main.cjs", mainSource],+ ["import", "main.mjs", moduleSource],+ ] as const)+ expect(graph.edges).toContainEqual(+ expect.objectContaining({+ properties: expect.objectContaining({+ module_link_kind: moduleKind,+ specifier,+ resolved_path: null,+ resolution_status: "external",+ }),+ evidence: sourceEvidence(sourcePath, source, limitation),+ }),+ );+ expect(imports).toContainEqual(+ expect.objectContaining({+ properties: expect.objectContaining({+ specifier: "#config",+ resolved_path: "config.cjs",+ resolution_status: "resolved",+ }),+ evidence: sourceEvidence("main.cjs", mainSource),+ }),+ );+ expect(imports).toContainEqual(+ expect.objectContaining({+ properties: expect.objectContaining({+ specifier: "#config",+ resolved_path: "node_modules/fixture/local.cjs",+ resolution_status: "resolved",+ }),+ evidence: sourceEvidence(+ "node_modules/fixture/index.cjs",+ nestedSource,+ ),+ }),+ );+ expect(imports).toContainEqual(+ expect.objectContaining({+ properties: expect.objectContaining({+ specifier: "#missing",+ resolved_path: null,+ resolution_status: "external",+ }),+ evidence: expect.objectContaining({+ limitations: expect.arrayContaining([+ expect.stringContaining("does not define package import alias"),+ ]),+ }),+ }),+ );+ },+);++const sourceEvidence = (+ sourcePath: string,+ source: string,+ limitation?: string,+): unknown =>+ expect.objectContaining({+ artifact: expect.objectContaining({+ available: true,+ sha256: createHash("sha256").update(source).digest("hex"),+ }),+ location: expect.objectContaining({+ available: true,+ value: expect.objectContaining({+ kind: "source-range",+ source: sourcePath,+ }),+ }),+ ...(limitation === undefined+ ? {}+ : {+ limitations: expect.arrayContaining([+ expect.stringContaining(limitation),+ ]),+ }),+ });diff --git a/tests/boundary/browser/cdpSvgXlinkHref.test.ts b/tests/boundary/browser/cdpSvgXlinkHref.test.tsindex be4fe268e..56c3fc3cf 100644--- a/tests/boundary/browser/cdpSvgXlinkHref.test.ts+++ b/tests/boundary/browser/cdpSvgXlinkHref.test.ts@@ -29,6 +29,11 @@ const chromeExecutable = [existsSync(candidate),);+// Match the real-browser verifier: a cold Chrome launch on a loaded coverage+// runner can exceed 20 seconds before publishing DevToolsActivePort.+const CHROME_STARTUP_TIMEOUT_MS = 60_000;+const CHROME_TEST_TIMEOUT_MS = CHROME_STARTUP_TIMEOUT_MS + 30_000;+// Issue 1586's page, plus the HTML, image, use, and foreign-origin cases the// real snapshot must distinguish. The XHTML page is the prefixed-svg gap// reported on PR 1602. The tests are skipped when no Chrome-family executable@@ -90,7 +95,7 @@ it.skipIf(chromeExecutable === undefined)(executable,activePortPath: join(profile, "DevToolsActivePort"),stderr: () => stderr,- timeoutMs: 20_000,+ timeoutMs: CHROME_STARTUP_TIMEOUT_MS,});const endpoint = `http://127.0.0.1:${String(port)}`;const provider = new CdpBrowserProvider();@@ -158,6 +163,7 @@ it.skipIf(chromeExecutable === undefined)(});}},+ CHROME_TEST_TIMEOUT_MS,);const xhtmlPage = `<?xml version="1.0" encoding="UTF-8"?>@@ -261,7 +267,7 @@ for (const { format, page, contentType, nodeNames, link, destinations } of [executable,activePortPath: join(profile, "DevToolsActivePort"),stderr: () => stderr,- timeoutMs: 20_000,+ timeoutMs: CHROME_STARTUP_TIMEOUT_MS,});const endpoint = `http://127.0.0.1:${String(port)}`;const provider = new CdpBrowserProvider();@@ -312,6 +318,7 @@ for (const { format, page, contentType, nodeNames, link, destinations } of [});}},+ CHROME_TEST_TIMEOUT_MS,);}diff --git a/tests/boundary/javascript/packageConditionalExports.test.ts b/tests/boundary/javascript/packageConditionalExports.test.tsindex 1eb992760..b53fe8516 100644--- a/tests/boundary/javascript/packageConditionalExports.test.ts+++ b/tests/boundary/javascript/packageConditionalExports.test.ts@@ -742,6 +742,30 @@ describe("nested and array package export targets", () => {);});describe("unmatched package export conditions", () => {+ it.each([+ [[{ browser: "./default.cjs" }], "browser"],+ [+ [[{ browser: "./default.cjs" }, { "rea-inactive": "./node.cjs" }]],+ "browser, rea-inactive",+ ],+ [{ node: [{ browser: "./default.cjs" }] }, "node, browser"],+ ] as const)(+ "preserves condition names in unmatched target %j",+ async (target, declared) => {+ for (const moduleKind of ["import", "require"] as const) {+ const { node_error, outcome } = await compareWithNode(+ target,+ moduleKind,+ );+ expect(node_error).toBe("ERR_PACKAGE_PATH_NOT_EXPORTED");+ expect(outcome).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(outcome.limitations[0]).toContain(`It declares ${declared}.`);+ }+ },+ );it.each(["import", "require"] as const)("names the declared conditions for %s",async (moduleKind) => {@@ -769,6 +793,31 @@ describe("unmatched package export conditions", () => {});});+describe("blocked package export provenance", () => {+ it.each([+ [[], "an empty exports target array"],+ [{ node: [] }, "an empty exports target array"],+ [[null, []], "an empty exports target array"],+ [[[], null], "an explicit null exports target"],+ ] as const)(+ "preserves the blocking source value in %j",+ async (target, limitation) => {+ for (const moduleKind of ["import", "require"] as const) {+ const { node_error, outcome } = await compareWithNode(+ target,+ moduleKind,+ );+ expect(node_error).toBe("ERR_PACKAGE_PATH_NOT_EXPORTED");+ expect(outcome).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(outcome.limitations[0]).toContain(limitation);+ }+ },+ );+});+describe("package exports fallback refusal reasons", () => {it.each([[{ import: [42, 7] }, "ERR_INVALID_PACKAGE_TARGET", "rejected"],diff --git a/tests/boundary/javascript/packageImportAliases.test.ts b/tests/boundary/javascript/packageImportAliases.test.tsnew file mode 100644index 000000000..b009c3ad4--- /dev/null+++ b/tests/boundary/javascript/packageImportAliases.test.ts@@ -0,0 +1,654 @@+import { execFile } from "node:child_process";+import { mkdir, writeFile } from "node:fs/promises";+import { createRequire } from "node:module";+import { dirname, join, relative } from "node:path";+import { promisify } from "node:util";+import { fileURLToPath } from "node:url";++import { describe, expect, it } from "vitest";+import { z } from "zod";++import {+ resolveArtifactPathByContext,+ type ArtifactPathResolution,+} from "../../../src/application/javascript/JavaScriptArtifactPathResolution.js";+import type { JavaScriptArtifactFile } from "../../../src/domain/javascript/javascriptArtifactFiles.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++const execute = promisify(execFile);+const nodeOutcomeSchema = z.strictObject({+ target: z.string().nullable(),+ error_code: z.string().nullable(),+});++const posixRelative = (root: string, absolute: string): string =>+ relative(root, absolute).replaceAll("\\", "/");++const inventory = (+ contents: ReadonlyMap<string, string>,+): Map<string, JavaScriptArtifactFile> =>+ new Map(+ [...contents].map(([path, value]) => [+ path,+ {+ path,+ container_sha256: "a".repeat(64),+ sha256: "b".repeat(64),+ bytes: Buffer.byteLength(value),+ inventory_artifact_id: path,+ kind: path.endsWith("package.json") ? "package-json" : "javascript",+ unpacked: false,+ text: { included: true, value },+ },+ ]),+ );++const writeTree = async (+ root: string,+ files: Readonly<Record<string, string>>,+): Promise<Map<string, string>> => {+ const contents = new Map<string, string>();+ await Promise.all(+ Object.entries(files).map(async ([path, value]) => {+ const absolute = join(root, path);+ await mkdir(dirname(absolute), { recursive: true });+ await writeFile(absolute, value);+ contents.set(path, value);+ }),+ );+ return contents;+};++const nodeRequireTarget = async (+ importer: string,+ specifier: string,+): Promise<z.infer<typeof nodeOutcomeSchema>> => {+ try {+ return {+ target: createRequire(importer).resolve(specifier),+ error_code: null,+ };+ } catch (error) {+ const code =+ error instanceof Error && "code" in error+ ? z.string().parse(Reflect.get(error, "code"))+ : null;+ return { target: null, error_code: code };+ }+};++const nodeImportTarget = async (+ cwd: string,+ specifier: string,+): Promise<z.infer<typeof nodeOutcomeSchema>> => {+ const { stdout } = await execute(+ process.execPath,+ [+ "--input-type=module",+ "-e",+ `+ try {+ const url = await import.meta.resolve(${JSON.stringify(specifier)});+ console.log(JSON.stringify({ target: url, error_code: null }));+ } catch (error) {+ console.log(JSON.stringify({+ target: null,+ error_code: error.code ?? null,+ }));+ }+ `,+ ],+ { cwd },+ );+ return nodeOutcomeSchema.parse(JSON.parse(stdout));+};++const resolveAlias = (+ files: Map<string, JavaScriptArtifactFile>,+ declaredPath: string,+ sourcePath: string,+ moduleKind: "import" | "require",+): ArtifactPathResolution =>+ resolveArtifactPathByContext({+ declaredPath,+ sourcePath,+ context: "module-specifier",+ moduleKind,+ files,+ });++describe("literal package import keys compared with Node", () => {+ it("matches literal imports keys containing path-like bytes in both Node loaders", async () => {+ const root = await createTestTempDirectory("rea-import-alias-literal-");+ const specifiers = ["#/x", "#x%2Fy", "#x%2Ey", "#x\\y", "#x\0y"];+ const contents = await writeTree(root, {+ "package.json": JSON.stringify({+ imports: Object.fromEntries(+ specifiers.map((specifier) => [specifier, "./target.cjs"]),+ ),+ }),+ "main.cjs": "module.exports = 1;",+ "target.cjs": "module.exports = 1;",+ });+ const inventoried = inventory(contents);+ for (const specifier of specifiers) {+ const required = await nodeRequireTarget(+ join(root, "main.cjs"),+ specifier,+ );+ expect(required.error_code).toBeNull();+ expect(posixRelative(root, required.target ?? "")).toBe("target.cjs");+ const imported = await nodeImportTarget(root, specifier);+ expect(imported.error_code).toBeNull();+ expect(posixRelative(root, fileURLToPath(imported.target ?? ""))).toBe(+ "target.cjs",+ );+ for (const moduleKind of ["require", "import"] as const)+ expect(+ resolveAlias(inventoried, specifier, "main.cjs", moduleKind),+ JSON.stringify({ specifier, moduleKind }),+ ).toMatchObject({+ declared_path: specifier,+ resolution_status: "resolved",+ resolved_path: "target.cjs",+ });+ }+ });++ it("still rejects unsafe selected targets for literal imports keys", async () => {+ const root = await createTestTempDirectory("rea-import-alias-target-");+ const contents = await writeTree(root, {+ "package.json": JSON.stringify({+ imports: { "#x%2Fy": "./nested%2Ftarget.cjs" },+ }),+ "main.cjs": "module.exports = 1;",+ "nested/target.cjs": "module.exports = 1;",+ });+ const inventoried = inventory(contents);+ const required = await nodeRequireTarget(join(root, "main.cjs"), "#x%2Fy");+ expect(required.error_code).toBe("ERR_INVALID_MODULE_SPECIFIER");+ const imported = await nodeImportTarget(root, "#x%2Fy");+ expect(imported.error_code).toBe("ERR_INVALID_MODULE_SPECIFIER");+ for (const moduleKind of ["require", "import"] as const)+ expect(+ resolveAlias(inventoried, "#x%2Fy", "main.cjs", moduleKind),+ ).toMatchObject({ resolution_status: "rejected", resolved_path: null });+ });+});++describe("inactive package target arrays compared with Node", () => {+ it("continues past inactive arrays in enclosing imports and exports conditions", async () => {+ const root = await createTestTempDirectory("rea-inactive-package-array-");+ const conditional = {+ node: [{ browser: "./browser.cjs" }],+ default: "./fallback.cjs",+ };+ const nested = {+ node: [+ [{ browser: "./browser.cjs" }],+ { "rea-inactive": "./inactive.cjs" },+ ],+ default: "./fallback.cjs",+ };+ const contents = await writeTree(root, {+ "package.json": JSON.stringify({+ imports: { "#conditional": conditional, "#nested": nested },+ }),+ "main.cjs": "module.exports = 1;",+ "fallback.cjs": "module.exports = 1;",+ "node_modules/fixture/package.json": JSON.stringify({+ name: "fixture",+ exports: { ".": conditional, "./nested": nested },+ }),+ "node_modules/fixture/fallback.cjs": "module.exports = 2;",+ });+ const inventoried = inventory(contents);+ for (const [specifier, expected] of [+ ["#conditional", "fallback.cjs"],+ ["#nested", "fallback.cjs"],+ ["fixture", "node_modules/fixture/fallback.cjs"],+ ["fixture/nested", "node_modules/fixture/fallback.cjs"],+ ] as const) {+ const required = await nodeRequireTarget(+ join(root, "main.cjs"),+ specifier,+ );+ expect(required.error_code, specifier).toBeNull();+ expect(posixRelative(root, required.target ?? "")).toBe(expected);+ const imported = await nodeImportTarget(root, specifier);+ expect(imported.error_code).toBeNull();+ expect(posixRelative(root, fileURLToPath(imported.target ?? ""))).toBe(+ expected,+ );+ for (const moduleKind of ["require", "import"] as const)+ expect(+ resolveAlias(inventoried, specifier, "main.cjs", moduleKind),+ ).toMatchObject({+ declared_path: specifier,+ resolution_status: "resolved",+ resolved_path: expected,+ });+ }+ });+});++describe("package target refusal evidence compared with Node", () => {+ it("keeps empty, null, invalid, and unmatched array outcomes distinct", async () => {+ const root = await createTestTempDirectory("rea-inactive-package-refusal-");+ const inactive = { browser: "./browser.cjs" };+ const contents = await writeTree(root, {+ "package.json": JSON.stringify({+ imports: {+ "#empty-direct": [],+ "#empty": { node: [], default: "./fallback.cjs" },+ "#null": { node: [null, inactive], default: "./fallback.cjs" },+ "#null-last": [[], null],+ "#empty-last": [null, []],+ "#invalid": {+ node: ["../outside.cjs", inactive],+ default: "./fallback.cjs",+ },+ "#unmatched": [inactive],+ "#unmatched-nested": [+ [inactive, { "rea-inactive": "./inactive.cjs" }],+ ],+ "#unmatched-active": { node: [inactive] },+ },+ }),+ "main.cjs": "module.exports = 1;",+ "fallback.cjs": "module.exports = 1;",+ });+ const inventoried = inventory(contents);+ for (const [specifier, errorCode, status, limitation] of [+ [+ "#empty-direct",+ "ERR_PACKAGE_IMPORT_NOT_DEFINED",+ "external",+ "an empty imports target array",+ ],+ [+ "#empty",+ "ERR_PACKAGE_IMPORT_NOT_DEFINED",+ "external",+ "an empty imports target array",+ ],+ [+ "#null",+ "ERR_PACKAGE_IMPORT_NOT_DEFINED",+ "external",+ "an explicit null imports target",+ ],+ [+ "#null-last",+ "ERR_PACKAGE_IMPORT_NOT_DEFINED",+ "external",+ "an explicit null imports target",+ ],+ [+ "#empty-last",+ "ERR_PACKAGE_IMPORT_NOT_DEFINED",+ "external",+ "an empty imports target array",+ ],+ ["#invalid", "ERR_INVALID_PACKAGE_TARGET", "rejected", "../outside.cjs"],+ [+ "#unmatched",+ "ERR_PACKAGE_IMPORT_NOT_DEFINED",+ "external",+ "it declares browser.",+ ],+ [+ "#unmatched-nested",+ "ERR_PACKAGE_IMPORT_NOT_DEFINED",+ "external",+ "it declares browser, rea-inactive.",+ ],+ [+ "#unmatched-active",+ "ERR_PACKAGE_IMPORT_NOT_DEFINED",+ "external",+ "it declares node, browser.",+ ],+ ] as const) {+ expect(+ (await nodeRequireTarget(join(root, "main.cjs"), specifier)).error_code,+ ).toBe(errorCode);+ expect((await nodeImportTarget(root, specifier)).error_code).toBe(+ errorCode,+ );+ for (const moduleKind of ["require", "import"] as const) {+ const result = resolveAlias(+ inventoried,+ specifier,+ "main.cjs",+ moduleKind,+ );+ expect(result).toMatchObject({+ resolution_status: status,+ resolved_path: null,+ });+ expect(result.limitations.join(" "), specifier).toContain(limitation);+ }+ }+ });+});++describe("package import target arrays compared with Node", () => {+ it("skips invalid parent, absolute, and URL targets before an exact fallback", async () => {+ const root = await createTestTempDirectory("rea-import-alias-fallback-");+ const imports = {+ "#parent": ["../outside.cjs", "./fallback.cjs"],+ "#absolute": { node: [["/outside.cjs"], "./fallback.cjs"] },+ "#url": {+ import: ["https://example.invalid/outside.cjs", "./fallback.cjs"],+ require: ["file:///outside.cjs", "./fallback.cjs"],+ },+ };+ const contents = await writeTree(root, {+ "package.json": JSON.stringify({ imports }),+ "main.cjs": "module.exports = 1;",+ "fallback.cjs": "module.exports = 1;",+ });+ const inventoried = inventory(contents);+ for (const specifier of Object.keys(imports)) {+ const required = await nodeRequireTarget(+ join(root, "main.cjs"),+ specifier,+ );+ expect(required.error_code).toBeNull();+ expect(posixRelative(root, required.target ?? "")).toBe("fallback.cjs");+ const imported = await nodeImportTarget(root, specifier);+ expect(imported.error_code).toBeNull();+ expect(posixRelative(root, fileURLToPath(imported.target ?? ""))).toBe(+ "fallback.cjs",+ );+ for (const moduleKind of ["require", "import"] as const)+ expect(+ resolveAlias(inventoried, specifier, "main.cjs", moduleKind),+ ).toMatchObject({+ declared_path: specifier,+ resolution_status: "resolved",+ resolved_path: "fallback.cjs",+ });+ }+ });++ it("preserves invalid, null, and unsupported-package outcomes in arrays", async () => {+ const root = await createTestTempDirectory(+ "rea-import-alias-fallback-refuse-",+ );+ const contents = await writeTree(root, {+ "package.json": JSON.stringify({+ imports: {+ "#invalid": [null, "../outside.cjs"],+ "#blocked": ["../outside.cjs", null],+ "#package": ["fixture", "./fallback.cjs"],+ },+ }),+ "main.cjs": "module.exports = 1;",+ "fallback.cjs": "module.exports = 1;",+ "node_modules/fixture/package.json": JSON.stringify({+ name: "fixture",+ main: "index.cjs",+ }),+ "node_modules/fixture/index.cjs": "module.exports = 2;",+ });+ const inventoried = inventory(contents);+ for (const [specifier, errorCode, resolutionStatus, reason] of [+ ["#invalid", "ERR_INVALID_PACKAGE_TARGET", "rejected", "../outside.cjs"],+ [+ "#blocked",+ "ERR_PACKAGE_IMPORT_NOT_DEFINED",+ "external",+ "explicit null",+ ],+ ] as const) {+ const required = await nodeRequireTarget(+ join(root, "main.cjs"),+ specifier,+ );+ expect(required.error_code).toBe(errorCode);+ expect((await nodeImportTarget(root, specifier)).error_code).toBe(+ errorCode,+ );+ for (const moduleKind of ["require", "import"] as const) {+ const result = resolveAlias(+ inventoried,+ specifier,+ "main.cjs",+ moduleKind,+ );+ expect(result).toMatchObject({+ resolution_status: resolutionStatus,+ resolved_path: null,+ });+ expect(result.limitations.join(" ")).toContain(reason);+ }+ }+ const required = await nodeRequireTarget(+ join(root, "main.cjs"),+ "#package",+ );+ expect(posixRelative(root, required.target ?? "")).toBe(+ "node_modules/fixture/index.cjs",+ );+ const imported = await nodeImportTarget(root, "#package");+ expect(imported.error_code).toBeNull();+ expect(posixRelative(root, fileURLToPath(imported.target ?? ""))).toBe(+ "node_modules/fixture/index.cjs",+ );+ for (const moduleKind of ["require", "import"] as const) {+ const result = resolveAlias(+ inventoried,+ "#package",+ "main.cjs",+ moduleKind,+ );+ expect(result).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(result.limitations.join(" ")).toContain(+ "External-package import targets remain unresolved",+ );+ }+ });+});++describe("package import aliases compared with Node", () => {+ it("matches Node require and import for an exact root alias", async () => {+ const root = await createTestTempDirectory("rea-import-alias-root-");+ const files = {+ "package.json": JSON.stringify({+ name: "app",+ imports: { "#config": "./config.cjs" },+ }),+ "main.cjs": 'module.exports = require("#config");',+ "config.cjs": "module.exports = 'config.cjs';",+ };+ const contents = await writeTree(root, files);+ const inventoried = inventory(contents);+ const required = await nodeRequireTarget(join(root, "main.cjs"), "#config");+ expect(posixRelative(root, required.target ?? "")).toBe("config.cjs");+ expect(+ resolveAlias(inventoried, "#config", "main.cjs", "require"),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "config.cjs",+ });+ const imported = await nodeImportTarget(root, "#config");+ expect(imported.error_code).toBeNull();+ expect(+ resolveAlias(inventoried, "#config", "main.cjs", "import"),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "config.cjs",+ });+ });++ it("matches Node when a nested package has its own imports map", async () => {+ const root = await createTestTempDirectory("rea-import-alias-nested-");+ const files = {+ "package.json": JSON.stringify({+ name: "app",+ imports: { "#config": "./root.cjs" },+ }),+ "root.cjs": "module.exports = 'root';",+ "node_modules/fixture/package.json": JSON.stringify({+ name: "fixture",+ imports: { "#config": "./local.cjs" },+ }),+ "node_modules/fixture/index.cjs": 'module.exports = require("#config");',+ "node_modules/fixture/local.cjs": "module.exports = 'local';",+ };+ const contents = await writeTree(root, files);+ const inventoried = inventory(contents);+ const nested = await nodeRequireTarget(+ join(root, "node_modules/fixture/index.cjs"),+ "#config",+ );+ expect(posixRelative(root, nested.target ?? "")).toBe(+ "node_modules/fixture/local.cjs",+ );+ expect(+ resolveAlias(+ inventoried,+ "#config",+ "node_modules/fixture/index.cjs",+ "require",+ ),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "node_modules/fixture/local.cjs",+ });+ const fromRoot = await nodeRequireTarget(join(root, "root.cjs"), "#config");+ expect(posixRelative(root, fromRoot.target ?? "")).toBe("root.cjs");+ expect(+ resolveAlias(inventoried, "#config", "root.cjs", "require"),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "root.cjs",+ });+ });++ it("matches Node when a nested package does not define the alias", async () => {+ const root = await createTestTempDirectory("rea-import-alias-scope-");+ const files = {+ "package.json": JSON.stringify({+ name: "app",+ imports: { "#config": "./root.cjs" },+ }),+ "root.cjs": "module.exports = 'root';",+ "node_modules/fixture/package.json": JSON.stringify({+ name: "fixture",+ }),+ "node_modules/fixture/index.cjs": 'module.exports = require("#config");',+ };+ await writeTree(root, files);+ const nested = await nodeRequireTarget(+ join(root, "node_modules/fixture/index.cjs"),+ "#config",+ );+ expect(nested.target).toBeNull();+ // CJS reports MODULE_NOT_FOUND when the nested package.json has no+ // `imports` field at all; it still does not inherit the ancestor map.+ expect(nested.error_code).toBe("MODULE_NOT_FOUND");+ const outcome = resolveAlias(+ inventory(new Map(Object.entries(files))),+ "#config",+ "node_modules/fixture/index.cjs",+ "require",+ );+ expect(outcome).toMatchObject({+ resolution_status: "external",+ resolved_path: null,+ });+ expect(outcome.limitations.join(" ")).toContain(+ "node_modules/fixture/package.json",+ );+ });+});++describe("package import alias refusals compared with Node", () => {+ it("matches Node refusal for a missing key, explicit null, and reserved specifier", async () => {+ const root = await createTestTempDirectory("rea-import-alias-refuse-");+ const files = {+ "package.json": JSON.stringify({+ name: "app",+ imports: {+ "#config": "./config.cjs",+ "#blocked": null,+ "#": "./config.cjs",+ "#/": "./config.cjs",+ "#config/": "./config.cjs",+ },+ }),+ "main.cjs": "module.exports = 1;",+ "config.cjs": "module.exports = 1;",+ };+ await writeTree(root, files);+ const inventoried = inventory(new Map(Object.entries(files)));+ const missing = await nodeRequireTarget(join(root, "main.cjs"), "#missing");+ expect(missing.error_code).toBe("ERR_PACKAGE_IMPORT_NOT_DEFINED");+ expect(+ resolveAlias(inventoried, "#missing", "main.cjs", "require"),+ ).toMatchObject({ resolution_status: "external", resolved_path: null });+ const blocked = await nodeRequireTarget(join(root, "main.cjs"), "#blocked");+ expect(blocked.error_code).toBe("ERR_PACKAGE_IMPORT_NOT_DEFINED");+ expect(+ resolveAlias(inventoried, "#blocked", "main.cjs", "require"),+ ).toMatchObject({ resolution_status: "external", resolved_path: null });+ for (const specifier of ["#", "#/", "#config/"]) {+ const reserved = await nodeRequireTarget(+ join(root, "main.cjs"),+ specifier,+ );+ expect(reserved.error_code).toBe("ERR_INVALID_MODULE_SPECIFIER");+ expect((await nodeImportTarget(root, specifier)).error_code).toBe(+ "ERR_INVALID_MODULE_SPECIFIER",+ );+ for (const moduleKind of ["require", "import"] as const)+ expect(+ resolveAlias(inventoried, specifier, "main.cjs", moduleKind),+ ).toMatchObject({ resolution_status: "rejected", resolved_path: null });+ }+ });++ it("matches Node when an import condition selects a different exact file", async () => {+ const root = await createTestTempDirectory("rea-import-alias-cond-");+ const files = {+ "package.json": JSON.stringify({+ name: "app",+ type: "module",+ imports: {+ "#config": {+ import: "./config.mjs",+ require: "./config.cjs",+ },+ },+ }),+ "main.cjs": 'module.exports = require("#config");',+ "config.cjs": "export default 'cjs'; module.exports = 'cjs';",+ "config.mjs": "export default 'mjs';",+ };+ await writeTree(root, files);+ const inventoried = inventory(new Map(Object.entries(files)));+ const required = await nodeRequireTarget(join(root, "main.cjs"), "#config");+ expect(posixRelative(root, required.target ?? "")).toBe("config.cjs");+ expect(+ resolveAlias(inventoried, "#config", "main.cjs", "require"),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "config.cjs",+ });+ const imported = await nodeImportTarget(root, "#config");+ expect(imported.error_code).toBeNull();+ expect(imported.target ?? "").toContain("config.mjs");+ expect(+ resolveAlias(inventoried, "#config", "main.cjs", "import"),+ ).toMatchObject({+ resolution_status: "resolved",+ resolved_path: "config.mjs",+ });+ });+});