@esmx/core 3.0.0-rc.116 → 3.0.0-rc.118

package/dist/declaration/resolver.test.mjs

@@ -0,0 +1,1005 @@
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { readDeclaration } from "./reader.mjs";
+import { resolveMounts } from "./resolver.mjs";
+import {
+  createFixtureRoot,
+  removeFixtureRoot,
+  writeFixturePackage
+} from "./test-fixtures.mjs";
+import { DiagnosticCode } from "./types.mjs";
+const fixtureRoots = [];
+async function fixtureRoot() {
+  const root = await createFixtureRoot();
+  fixtureRoots.push(root);
+  return root;
+}
+afterEach(async () => {
+  await Promise.all(fixtureRoots.splice(0).map(removeFixtureRoot));
+});
+function readRootDeclaration(appDir) {
+  const pkg = readDeclaration(appDir);
+  if (!pkg) {
+    throw new Error(`fixture app at ${appDir} must declare esmx`);
+  }
+  return pkg;
+}
+describe("resolveMounts", () => {
+  it("should report E_DUP_PROVIDER when a layer self-provides over a used provider of the same (package, major)", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/base",
+      packageJson: {
+        name: "base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.21" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue-base",
+      packageJson: {
+        name: "vue-base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["base"], provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue-base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.2" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["vue-base"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const dupes = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_DUP_PROVIDER
+    );
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0].severity).toBe("error");
+    expect(dupes[0].module).toBe("vue-base");
+    expect(dupes[0].package).toBe("vue");
+    expect(dupes[0].found).toBe("base, vue-base");
+    expect(Object.keys(result.mounts).sort()).toEqual(["base", "vue-base"]);
+  });
+  it("should report E_DUP_PROVIDER when two distinct providers reach a consumer via separate subtrees", async () => {
+    const root = await fixtureRoot();
+    for (const [name, provides] of [
+      ["x", true],
+      ["y", true],
+      ["b1", false],
+      ["b2", false]
+    ]) {
+      writeFixturePackage(root, {
+        dir: `node_modules/${name}`,
+        packageJson: {
+          name,
+          version: "1.0.0",
+          esmx: provides ? { provides: ["vue"] } : { uses: [name === "b1" ? "x" : "y"] }
+        },
+        built: true
+      });
+    }
+    writeFixturePackage(root, {
+      dir: "node_modules/x/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.0" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/y/node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.0" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["b1", "b2"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const dupes = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_DUP_PROVIDER
+    );
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0].module).toBe("app");
+    expect(dupes[0].package).toBe("vue");
+    expect(dupes[0].found).toBe("x, y");
+  });
+  it("should report E_DUP_PROVIDER when a self-provider collides with a used provider of the same (package, major)", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/base",
+      packageJson: {
+        name: "base",
+        version: "1.0.0",
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.0" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.2" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["base"], provides: ["vue"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const dupes = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_DUP_PROVIDER
+    );
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0].module).toBe("app");
+    expect(dupes[0].package).toBe("vue");
+    expect(dupes[0].found).toBe("base, app");
+  });
+  it("should report E_TARGET_MISSING when a declared entry/exports target file is absent", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        esmx: {
+          entry: { client: "./src/entry.client.ts" },
+          exports: { "./widget": "./src/widget.ts" }
+        }
+      },
+      noSources: true
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const missing = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_TARGET_MISSING
+    );
+    expect(missing).toHaveLength(2);
+    expect(missing.every((d) => d.severity === "error")).toBe(true);
+    expect(missing.map((d) => d.found).sort()).toEqual([
+      "./src/entry.client.ts",
+      "./src/widget.ts"
+    ]);
+  });
+  it("should not report E_TARGET_MISSING when declared targets exist", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        esmx: { entry: { client: "./src/entry.client.ts" } }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    expect(
+      result.diagnostics.filter(
+        (d) => d.code === DiagnosticCode.E_TARGET_MISSING
+      )
+    ).toHaveLength(0);
+  });
+  it("should report E_CYCLE when the uses chain revisits a module", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/b",
+      packageJson: {
+        name: "b",
+        version: "1.0.0",
+        esmx: { uses: ["a"] }
+      },
+      built: true
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "a",
+      packageJson: {
+        name: "a",
+        version: "1.0.0",
+        esmx: { uses: ["b"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const cycles = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_CYCLE
+    );
+    expect(cycles).toHaveLength(1);
+    expect(cycles[0].severity).toBe("error");
+    expect(cycles[0].module).toBe("a");
+  });
+  it("should report E_NOT_LINKED for a uses entry with no mount", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        esmx: { uses: ["ghost"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const notLinked = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_NOT_LINKED
+    );
+    expect(notLinked).toHaveLength(1);
+    expect(notLinked[0].module).toBe("app");
+    expect(notLinked[0].package).toBe("ghost");
+    expect(result.mounts).toEqual({});
+  });
+  it("should report E_NOT_BUILT but keep declaration wiring", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/raw",
+      packageJson: {
+        name: "raw",
+        version: "1.0.0",
+        esmx: { provides: ["vue"] }
+      }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/raw/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.0" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["raw"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const notBuilt = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_NOT_BUILT
+    );
+    expect(notBuilt).toHaveLength(1);
+    expect(notBuilt[0].package).toBe("raw");
+    expect(result.mounts.raw.built).toBe(false);
+    expect(result.supply.vue).toEqual({
+      groups: [{ major: 3, provider: "raw", version: "3.4.0" }]
+    });
+  });
+  it("should report E_VERSION (intent) when the winner violates a layer range", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/base",
+      packageJson: {
+        name: "base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.0.0" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.0.5" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["base"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const versionErrors = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_VERSION
+    );
+    expect(versionErrors).toHaveLength(1);
+    expect(versionErrors[0].check).toBe("intent");
+    expect(versionErrors[0].module).toBe("app");
+    expect(versionErrors[0].package).toBe("vue");
+    expect(versionErrors[0].found).toBe("3.0.5");
+    expect(versionErrors[0].required).toBe("^3.4.0");
+  });
+  it("should report E_VERSION (intent) for used-module version vs range", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/shared",
+      packageJson: {
+        name: "shared",
+        version: "2.0.0",
+        esmx: {}
+      },
+      built: true
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { shared: "^1.0.0" },
+        esmx: { uses: ["shared"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const versionErrors = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_VERSION
+    );
+    expect(versionErrors).toHaveLength(1);
+    expect(versionErrors[0].check).toBe("intent");
+    expect(versionErrors[0].package).toBe("shared");
+    expect(versionErrors[0].found).toBe("2.0.0");
+  });
+  it("should skip the used-module version gate for workspace ranges", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/shared",
+      packageJson: {
+        name: "shared",
+        version: "2.0.0",
+        esmx: {}
+      },
+      built: true
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { shared: "workspace:^1.0.0" },
+        esmx: { uses: ["shared"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    expect(
+      result.diagnostics.filter(
+        (d) => d.code === DiagnosticCode.E_VERSION
+      )
+    ).toEqual([]);
+  });
+  it("should warn W_NO_RANGE when a layer receives a package without any range", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/base",
+      packageJson: {
+        name: "base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.21" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        esmx: { uses: ["base"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const noRange = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.W_NO_RANGE
+    );
+    expect(noRange).toHaveLength(1);
+    expect(noRange[0].severity).toBe("warning");
+    expect(noRange[0].module).toBe("app");
+    expect(noRange[0].package).toBe("vue");
+  });
+  it("should warn W_TYPE_DRIFT when the local devDependencies copy diverges from the winner", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/base",
+      packageJson: {
+        name: "base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.2" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        devDependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["base"] }
+      }
+    });
+    writeFixturePackage(root, {
+      dir: "app/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.0" }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const drift = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.W_TYPE_DRIFT
+    );
+    expect(drift).toHaveLength(1);
+    expect(drift[0].module).toBe("app");
+    expect(drift[0].package).toBe("vue");
+    expect(drift[0].found).toBe("3.4.0");
+    expect(drift[0].required).toBe("3.5.2");
+  });
+  it("should report E_PROTOCOL for a mounted manifest with a higher protocol", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/future",
+      packageJson: {
+        name: "future",
+        version: "1.0.0",
+        esmx: {}
+      },
+      manifest: { protocol: 3, name: "future" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        esmx: { uses: ["future"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const protocol = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_PROTOCOL
+    );
+    expect(protocol).toHaveLength(1);
+    expect(protocol[0].package).toBe("future");
+    expect(protocol[0].found).toBe("3");
+  });
+  it("should accept protocol 2 and protocol-less (pre-v2) manifests without E_PROTOCOL", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/modern",
+      packageJson: { name: "modern", version: "1.0.0", esmx: {} },
+      manifest: { protocol: 2, name: "modern" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/legacy",
+      packageJson: { name: "legacy", version: "1.0.0", esmx: {} },
+      manifest: { name: "legacy" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        esmx: { uses: ["modern", "legacy"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const protocol = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_PROTOCOL
+    );
+    expect(protocol).toEqual([]);
+  });
+  it("should honor envLinks overrides resolved relative to rootDir", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "shared",
+      packageJson: {
+        name: "shared",
+        version: "1.0.0",
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "shared/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.21" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["shared"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir), {
+      shared: "../shared/dist"
+    });
+    expect(result.mounts.shared).toEqual({
+      name: "shared",
+      root: path.join(root, "shared"),
+      artifactDir: path.join(root, "shared/dist"),
+      built: true
+    });
+    expect(result.supply.vue).toEqual({
+      groups: [{ major: 3, provider: "shared", version: "3.4.21" }]
+    });
+  });
+  it("should keep coexisting majors as isolated groups with W_MULTI_MAJOR and no E_VERSION", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/vue2-app",
+      packageJson: {
+        name: "vue2-app",
+        version: "1.0.0",
+        dependencies: { vue: "2.7.16" },
+        esmx: { provides: ["vue"] }
+      },
+      manifest: { provides: { vue: "2.7.16" } }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue2-app/node_modules/vue",
+      packageJson: { name: "vue", version: "2.7.16" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue3-base",
+      packageJson: {
+        name: "vue3-base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.5.0" },
+        esmx: { provides: ["vue"] }
+      },
+      manifest: { provides: { vue: "3.5.13" } }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue3-base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.13" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        peerDependencies: { vue: "^3.5.0" },
+        esmx: { uses: ["vue2-app", "vue3-base"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    expect(result.supply.vue).toEqual({
+      groups: [
+        { major: 3, provider: "vue3-base", version: "3.5.13" },
+        { major: 2, provider: "vue2-app", version: "2.7.16" }
+      ]
+    });
+    const errors = result.diagnostics.filter((d) => d.severity === "error");
+    expect(errors).toEqual([]);
+    const multiMajor = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.W_MULTI_MAJOR
+    );
+    expect(multiMajor).toHaveLength(1);
+    expect(multiMajor[0].package).toBe("vue");
+    expect(multiMajor[0].found).toContain("vue3-base");
+    expect(multiMajor[0].found).toContain("vue2-app");
+  });
+  it("should let different majors coexist across a uses chain with no E_DUP_PROVIDER", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/base",
+      packageJson: {
+        name: "base",
+        version: "1.0.0",
+        dependencies: { vue: "^2.6.0" },
+        esmx: { provides: ["vue"] }
+      },
+      manifest: { provides: { vue: "2.6.14" } }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/base/node_modules/vue",
+      packageJson: { name: "vue", version: "2.6.14" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue-base",
+      packageJson: {
+        name: "vue-base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["base"], provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue-base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.2" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["vue-base"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    expect(
+      result.diagnostics.filter(
+        (d) => d.code === DiagnosticCode.E_DUP_PROVIDER
+      )
+    ).toEqual([]);
+    expect(
+      result.diagnostics.filter((d) => d.severity === "error")
+    ).toEqual([]);
+    expect(result.supply.vue.groups).toHaveLength(2);
+    expect(
+      result.diagnostics.filter(
+        (d) => d.code === DiagnosticCode.W_MULTI_MAJOR
+      )
+    ).toHaveLength(1);
+  });
+  it("should validate intent against the group a layer wires to, not an unrelated major", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/vue2-app",
+      packageJson: {
+        name: "vue2-app",
+        version: "1.0.0",
+        dependencies: { vue: "2.7.16" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue2-app/node_modules/vue",
+      packageJson: { name: "vue", version: "2.7.16" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue3-base",
+      packageJson: {
+        name: "vue3-base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.5.0" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue3-base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.13" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^2.7.0" },
+        esmx: { uses: ["vue3-base", "vue2-app"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    expect(
+      result.diagnostics.filter(
+        (d) => d.code === DiagnosticCode.E_VERSION
+      )
+    ).toEqual([]);
+  });
+  it("should report E_VERSION (intent) when no major group satisfies the range", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/vue2-app",
+      packageJson: {
+        name: "vue2-app",
+        version: "1.0.0",
+        dependencies: { vue: "2.7.16" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue2-app/node_modules/vue",
+      packageJson: { name: "vue", version: "2.7.16" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue3-base",
+      packageJson: {
+        name: "vue3-base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.5.0" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue3-base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.13" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^4.0.0" },
+        esmx: { uses: ["vue2-app", "vue3-base"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const versionErrors = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_VERSION
+    );
+    expect(versionErrors).toHaveLength(1);
+    expect(versionErrors[0].check).toBe("intent");
+    expect(versionErrors[0].module).toBe("app");
+    expect(versionErrors[0].required).toBe("^4.0.0");
+  });
+  it("should resolve the hub-shaped topology (vue2 + multiple vue3 providers) with warnings only", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/shared",
+      packageJson: {
+        name: "shared",
+        version: "1.0.0",
+        dependencies: { unhead: "^3.1.3" },
+        esmx: { provides: ["unhead"] }
+      },
+      manifest: { provides: { unhead: "3.1.3" } }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/shared/node_modules/unhead",
+      packageJson: { name: "unhead", version: "3.1.3" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue2-app",
+      packageJson: {
+        name: "vue2-app",
+        version: "1.0.0",
+        dependencies: { vue: "2.7.16" },
+        esmx: { uses: ["shared"], provides: ["vue"] }
+      },
+      manifest: { provides: { vue: "2.7.16" } }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue2-app/node_modules/vue",
+      packageJson: { name: "vue", version: "2.7.16" }
+    });
+    const vue3Providers = ["vue3-app", "vite-vue-app", "rsbuild-vue-app"];
+    for (const name of vue3Providers) {
+      writeFixturePackage(root, {
+        dir: `node_modules/${name}`,
+        packageJson: {
+          name,
+          version: "1.0.0",
+          dependencies: { vue: "^3.5.0" },
+          esmx: { uses: ["shared"], provides: ["vue"] }
+        },
+        manifest: { provides: { vue: "3.5.40" } }
+      });
+      writeFixturePackage(root, {
+        dir: `node_modules/${name}/node_modules/vue`,
+        packageJson: { name: "vue", version: "3.5.40" }
+      });
+    }
+    const passiveApps = [];
+    for (let i = 0; i < 11; i++) {
+      const name = `app-${i}`;
+      passiveApps.push(name);
+      writeFixturePackage(root, {
+        dir: `node_modules/${name}`,
+        packageJson: {
+          name,
+          version: "1.0.0",
+          peerDependencies: { unhead: "^3.1.3" },
+          esmx: { uses: ["shared"] }
+        },
+        built: true
+      });
+    }
+    const appDir = writeFixturePackage(root, {
+      dir: "hub",
+      packageJson: {
+        name: "hub",
+        version: "1.0.0",
+        peerDependencies: { unhead: "^3.1.3", vue: "^3.5.34" },
+        esmx: {
+          uses: [
+            "shared",
+            ...passiveApps,
+            "vue2-app",
+            ...vue3Providers
+          ]
+        }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const dupes = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_DUP_PROVIDER
+    );
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0].module).toBe("hub");
+    expect(dupes[0].package).toBe("vue");
+    expect(dupes[0].found).toBe("vue3-app, vite-vue-app");
+    const codes = result.diagnostics.map((d) => d.code);
+    expect(codes).toContain(DiagnosticCode.W_MULTI_MAJOR);
+  });
+  it("should report a single de-duped E_DUP_PROVIDER for a 3-provider same-major collision", async () => {
+    const root = await fixtureRoot();
+    for (const name of ["pa", "pb", "pc"]) {
+      writeFixturePackage(root, {
+        dir: `node_modules/${name}`,
+        packageJson: {
+          name,
+          version: "1.0.0",
+          esmx: { provides: ["vue"] }
+        },
+        built: true
+      });
+      writeFixturePackage(root, {
+        dir: `node_modules/${name}/node_modules/vue`,
+        packageJson: { name: "vue", version: "3.5.0" }
+      });
+    }
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.5.0" },
+        esmx: { uses: ["pa", "pb", "pc"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const dupes = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_DUP_PROVIDER
+    );
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0].module).toBe("app");
+    expect(dupes[0].package).toBe("vue");
+    expect(dupes[0].found).toBe("pa, pb");
+  });
+  it("should withhold supply when a uses cycle also provides", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/a",
+      packageJson: {
+        name: "a",
+        version: "1.0.0",
+        esmx: { uses: ["b"], provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/a/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.0" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/b",
+      packageJson: {
+        name: "b",
+        version: "1.0.0",
+        esmx: { uses: ["a"], provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/b/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.0" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["a"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    expect(
+      result.diagnostics.some((d) => d.code === DiagnosticCode.E_CYCLE)
+    ).toBe(true);
+    expect(result.supply).toEqual({});
+  });
+  it("should report E_DUP_PROVIDER when base and a sibling both provide vue@3 in the same closure", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/base",
+      packageJson: {
+        name: "base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.21" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/sibling",
+      packageJson: {
+        name: "sibling",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/sibling/node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.2" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["base", "sibling"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    const dupes = result.diagnostics.filter(
+      (d) => d.code === DiagnosticCode.E_DUP_PROVIDER
+    );
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0].severity).toBe("error");
+    expect(dupes[0].module).toBe("app");
+    expect(dupes[0].package).toBe("vue");
+    expect(dupes[0].found).toBe("base, sibling");
+  });
+  it("should not report E_DUP_PROVIDER when the SAME provider reaches via two diamond paths", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/base",
+      packageJson: {
+        name: "base",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/base/node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.2" }
+    });
+    for (const name of ["left", "right"]) {
+      writeFixturePackage(root, {
+        dir: `node_modules/${name}`,
+        packageJson: {
+          name,
+          version: "1.0.0",
+          esmx: { uses: ["base"] }
+        },
+        built: true
+      });
+    }
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["left", "right"] }
+      }
+    });
+    const result = resolveMounts(appDir, readRootDeclaration(appDir));
+    expect(
+      result.diagnostics.filter(
+        (d) => d.code === DiagnosticCode.E_DUP_PROVIDER
+      )
+    ).toEqual([]);
+    expect(
+      result.diagnostics.filter((d) => d.severity === "error")
+    ).toEqual([]);
+    expect(result.supply.vue).toEqual({
+      groups: [{ major: 3, provider: "base", version: "3.5.2" }]
+    });
+  });
+});