feat(javascript): resolve exact package import aliases (#1862)

* feat(javascript): resolve exact package import aliases

Resolve exact #alias specifiers against the importer's enclosing
package.json imports map using the shared condition, array, and null
target selection. Nested packages keep their own maps; missing keys,
explicit nulls, and out-of-scope aliases report a precise reason.
Wildcard, recursive, and external-package import targets remain
unresolved.

* fix(javascript): keep nested import aliases in CLI graphs

Bound nested #alias requires produce application-graph require edges
from the enclosing package. Node reports MODULE_NOT_FOUND when a nested
package.json has no imports field, without inheriting the ancestor map.

* fix(javascript): resolve literal package import keys before path admission

* fix(javascript): preserve import keys and invalid-target fallback

* fix(javascript): preserve unmatched package target arrays

* fix(javascript): retain package target refusal evidence

* test(browser): match real verifier startup budget

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>

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,
+    });
+  });
+});

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 };
+};