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

package/dist/declaration/resolver.mjs

@@ -0,0 +1,430 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MANIFEST_PROTOCOL_VERSION } from "../manifest-json.mjs";
+import { readPackageRecord } from "./reader.mjs";
+import { parseSemver, satisfiesRange } from "./semver.mjs";
+import { DiagnosticCode } from "./types.mjs";
+function resolvePackageDir(fromDir, name) {
+  let dir = path.resolve(fromDir);
+  for (; ; ) {
+    const candidate = path.join(dir, "node_modules", name);
+    if (fs.existsSync(path.join(candidate, "package.json"))) {
+      return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+function resolveInstalledVersion(fromDir, packageName) {
+  const packageDir = resolvePackageDir(fromDir, packageName);
+  if (!packageDir) {
+    return null;
+  }
+  const record = readPackageRecord(packageDir);
+  return record && record.version !== "" ? record.version : null;
+}
+function readManifestInfo(artifactDir) {
+  let json;
+  try {
+    json = JSON.parse(
+      fs.readFileSync(
+        path.join(artifactDir, "client/manifest.json"),
+        "utf-8"
+      )
+    );
+  } catch {
+    return null;
+  }
+  if (typeof json !== "object" || json === null) {
+    return null;
+  }
+  const manifest = json;
+  const protocol = typeof manifest.protocol === "number" ? manifest.protocol : 1;
+  return { protocol };
+}
+function isWorkspacePlaceholderRange(range) {
+  return /^(workspace|file|link|portal):/.test(range);
+}
+function majorKeyOf(version) {
+  const parsed = version ? parseSemver(version) : null;
+  return parsed ? String(parsed.major) : "unknown";
+}
+function sortedMajorKeys(groups) {
+  return Object.keys(groups).sort((a, b) => {
+    if (a === "unknown") {
+      return 1;
+    }
+    if (b === "unknown") {
+      return -1;
+    }
+    return Number(b) - Number(a);
+  });
+}
+function mergeGrouped(into, from, onConflict) {
+  for (const [packageName, groups] of Object.entries(from)) {
+    const target = into[packageName] ?? (into[packageName] = {});
+    for (const [majorKey, winner] of Object.entries(groups)) {
+      const existing = target[majorKey];
+      if (existing) {
+        if (existing.provider !== winner.provider) {
+          onConflict(
+            packageName,
+            majorKey,
+            existing.provider,
+            winner.provider
+          );
+        }
+        continue;
+      }
+      target[majorKey] = winner;
+    }
+  }
+}
+export function selectSupplyGroup(entry, range) {
+  if (entry.groups.length === 0) {
+    return null;
+  }
+  if (range === void 0 || isWorkspacePlaceholderRange(range)) {
+    return entry.groups[0];
+  }
+  let unknownFallback = null;
+  for (const group of entry.groups) {
+    const satisfied = group.version ? satisfiesRange(group.version, range) : null;
+    if (satisfied === true) {
+      return group;
+    }
+    if (satisfied === null && unknownFallback === null) {
+      unknownFallback = group;
+    }
+  }
+  return unknownFallback ?? entry.groups[0];
+}
+export function resolveMounts(rootDir, rootPackage, envLinks) {
+  const diagnostics = [...rootPackage.diagnostics];
+  const mounts = {};
+  const records = /* @__PURE__ */ new Map([
+    [rootPackage.name, rootPackage]
+  ]);
+  const supplyMemo = /* @__PURE__ */ new Map();
+  const usedSupplyMemo = /* @__PURE__ */ new Map();
+  const visiting = /* @__PURE__ */ new Set();
+  let cyclic = false;
+  const reportedDupes = /* @__PURE__ */ new Set();
+  function reportDupProvider(consumer, packageName, majorKey, existing, incoming) {
+    const key = `${packageName}@${majorKey}`;
+    if (reportedDupes.has(key)) {
+      return;
+    }
+    reportedDupes.add(key);
+    diagnostics.push({
+      code: DiagnosticCode.E_DUP_PROVIDER,
+      severity: "error",
+      module: consumer,
+      package: packageName,
+      found: `${existing}, ${incoming}`,
+      message: `Package "${packageName}" (major ${majorKey}) is provided by both "${existing}" and "${incoming}" in the closure of "${consumer}" \u2014 a shared dependency must have a single owner.`,
+      fix: `Consolidate "${packageName}" into one shared module that both consume via "uses", or give one copy a distinct package identity (an npm alias provided under its own name) if same-major coexistence is intended.`
+    });
+  }
+  function mountUsed(name, consumer) {
+    const known = records.get(name);
+    if (known) {
+      return known;
+    }
+    let packageRoot = null;
+    let artifactDir = null;
+    const envLink = envLinks?.[name];
+    if (envLink !== void 0) {
+      artifactDir = path.isAbsolute(envLink) ? envLink : path.resolve(rootDir, envLink);
+      packageRoot = path.dirname(artifactDir);
+    } else {
+      const resolved = resolvePackageDir(consumer.root, name);
+      if (resolved) {
+        packageRoot = fs.realpathSync(resolved);
+        artifactDir = path.join(packageRoot, "dist");
+      }
+    }
+    const record = packageRoot ? readPackageRecord(packageRoot) : null;
+    if (!record || !artifactDir || !packageRoot) {
+      diagnostics.push({
+        code: DiagnosticCode.E_NOT_LINKED,
+        severity: "error",
+        module: consumer.name,
+        package: name,
+        message: `Module "${consumer.name}" uses "${name}" but it is absent from the mount table (not installed and no explicit link).`,
+        fix: `Install "${name}" into node_modules, or add an explicit links entry pointing at its artifact directory.`
+      });
+      return null;
+    }
+    diagnostics.push(...record.diagnostics);
+    const built = fs.existsSync(
+      path.join(artifactDir, "client/manifest.json")
+    );
+    if (!built) {
+      diagnostics.push({
+        code: DiagnosticCode.E_NOT_BUILT,
+        severity: "error",
+        module: consumer.name,
+        package: name,
+        message: `Module "${name}" is mounted at ${artifactDir} but has no built artifact (dist/client/manifest.json missing). Manifest-dependent checks are skipped.`,
+        fix: `Build "${name}" first, then rebuild "${consumer.name}".`
+      });
+    } else {
+      const info = readManifestInfo(artifactDir);
+      if (info && info.protocol > MANIFEST_PROTOCOL_VERSION) {
+        diagnostics.push({
+          code: DiagnosticCode.E_PROTOCOL,
+          severity: "error",
+          module: consumer.name,
+          package: name,
+          found: String(info.protocol),
+          required: `<= ${MANIFEST_PROTOCOL_VERSION}`,
+          message: `Module "${name}" was built with manifest protocol ${info.protocol}, but this linker supports up to ${MANIFEST_PROTOCOL_VERSION}.`,
+          fix: `Upgrade esmx in "${consumer.name}", or rebuild "${name}" with a toolchain emitting protocol <= ${MANIFEST_PROTOCOL_VERSION}.`
+        });
+      }
+    }
+    mounts[name] = { name, root: packageRoot, artifactDir, built };
+    records.set(name, record);
+    return record;
+  }
+  function checkUsedVersion(consumer, used) {
+    const range = consumer.dependencies[used.name] ?? consumer.peerDependencies[used.name] ?? consumer.devDependencies[used.name];
+    if (range === void 0 || isWorkspacePlaceholderRange(range)) {
+      return;
+    }
+    if (used.private) {
+      return;
+    }
+    const satisfied = satisfiesRange(used.version, range);
+    if (satisfied === false) {
+      diagnostics.push({
+        code: DiagnosticCode.E_VERSION,
+        severity: "error",
+        module: consumer.name,
+        package: used.name,
+        check: "intent",
+        found: used.version,
+        required: range,
+        message: `Module "${consumer.name}" requires "${used.name}@${range}" but the mounted module is version ${used.version}.`,
+        fix: `Update the "${used.name}" range in "${consumer.name}" dependencies, or mount a matching version.`
+      });
+    }
+  }
+  function supplyOf(record) {
+    const memoized = supplyMemo.get(record.name);
+    if (memoized) {
+      return memoized;
+    }
+    if (visiting.has(record.name)) {
+      cyclic = true;
+      diagnostics.push({
+        code: DiagnosticCode.E_CYCLE,
+        severity: "error",
+        module: record.name,
+        message: `The uses chain revisits module "${record.name}" \u2014 a uses cycle is an architecture error.`,
+        fix: `Break the cycle by removing one of the "uses" edges that closes it.`
+      });
+      return {};
+    }
+    visiting.add(record.name);
+    const onConflict = (packageName, majorKey, existing, incoming) => reportDupProvider(
+      record.name,
+      packageName,
+      majorKey,
+      existing,
+      incoming
+    );
+    const fromUses = {};
+    for (const usedName of record.declaration?.uses ?? []) {
+      const used = mountUsed(usedName, record);
+      if (!used) {
+        continue;
+      }
+      checkUsedVersion(record, used);
+      mergeGrouped(fromUses, supplyOf(used), onConflict);
+    }
+    usedSupplyMemo.set(record.name, fromUses);
+    const merged = {};
+    mergeGrouped(merged, fromUses, onConflict);
+    for (const provided of record.declaration?.provides ?? []) {
+      const version = resolveInstalledVersion(record.root, provided);
+      const majorKey = majorKeyOf(version);
+      const existing = merged[provided]?.[majorKey];
+      if (existing && existing.provider !== record.name) {
+        reportDupProvider(
+          record.name,
+          provided,
+          majorKey,
+          existing.provider,
+          record.name
+        );
+        continue;
+      }
+      merged[provided] = {
+        ...merged[provided],
+        [majorKey]: { provider: record.name, version }
+      };
+    }
+    visiting.delete(record.name);
+    supplyMemo.set(record.name, merged);
+    return merged;
+  }
+  const targetChecks = [];
+  const rootEntry = rootPackage.declaration.entry;
+  if (rootEntry?.client) {
+    targetChecks.push(["entry.client", rootEntry.client]);
+  }
+  if (rootEntry?.server) {
+    targetChecks.push(["entry.server", rootEntry.server]);
+  }
+  for (const [name, value] of Object.entries(
+    rootPackage.declaration.exports ?? {}
+  )) {
+    if (typeof value === "string") {
+      targetChecks.push([`exports['${name}']`, value]);
+    } else {
+      if (typeof value.client === "string") {
+        targetChecks.push([`exports['${name}'].client`, value.client]);
+      }
+      if (typeof value.server === "string") {
+        targetChecks.push([`exports['${name}'].server`, value.server]);
+      }
+    }
+  }
+  for (const [label, relativePath] of targetChecks) {
+    if (!fs.existsSync(path.resolve(rootPackage.root, relativePath))) {
+      diagnostics.push({
+        code: DiagnosticCode.E_TARGET_MISSING,
+        severity: "error",
+        module: rootPackage.name,
+        found: relativePath,
+        message: `Declared ${label} target "${relativePath}" does not exist in module "${rootPackage.name}".`,
+        fix: `Create the file, or fix the path in the "esmx" declaration.`
+      });
+    }
+  }
+  const groupedSupply = supplyOf(rootPackage);
+  if (cyclic) {
+    return { supply: {}, mounts, diagnostics };
+  }
+  const supply = {};
+  for (const [packageName, groups] of Object.entries(groupedSupply)) {
+    supply[packageName] = {
+      groups: sortedMajorKeys(groups).map((majorKey) => ({
+        major: majorKey === "unknown" ? "unknown" : Number(majorKey),
+        provider: groups[majorKey].provider,
+        version: groups[majorKey].version
+      }))
+    };
+  }
+  for (const [packageName, entry] of Object.entries(supply)) {
+    if (entry.groups.length < 2) {
+      continue;
+    }
+    const summary = entry.groups.map(
+      (group) => `${group.major} \u2192 "${group.provider}"@${group.version ?? "unresolved"}`
+    ).join(", ");
+    diagnostics.push({
+      code: DiagnosticCode.W_MULTI_MAJOR,
+      severity: "warning",
+      module: rootPackage.name,
+      package: packageName,
+      found: summary,
+      message: `Package "${packageName}" has coexisting major versions: ${summary}. Each major is an isolated island with its own winner; every consumer wires to the group satisfying its own range.`,
+      fix: `No action needed if coexistence is intended. Otherwise align the providers' installed "${packageName}" majors.`
+    });
+  }
+  function wiredGroupFor(record, packageName, entry) {
+    if (record.declaration?.provides?.includes(packageName)) {
+      const selfKey = majorKeyOf(
+        resolveInstalledVersion(record.root, packageName)
+      );
+      const own = entry.groups.find(
+        (group) => String(group.major) === selfKey
+      );
+      if (own) {
+        return own;
+      }
+    }
+    const range = record.dependencies[packageName] ?? record.peerDependencies[packageName];
+    return selectSupplyGroup(entry, range);
+  }
+  for (const record of records.values()) {
+    for (const [packageName, entry] of Object.entries(supply)) {
+      const range = record.dependencies[packageName] ?? record.peerDependencies[packageName];
+      if (range === void 0 || isWorkspacePlaceholderRange(range)) {
+        continue;
+      }
+      const group = wiredGroupFor(record, packageName, entry);
+      if (!group?.version) {
+        continue;
+      }
+      const satisfied = satisfiesRange(group.version, range);
+      if (satisfied === false) {
+        diagnostics.push({
+          code: DiagnosticCode.E_VERSION,
+          severity: "error",
+          module: record.name,
+          package: packageName,
+          check: "intent",
+          found: group.version,
+          required: range,
+          message: `Layer "${record.name}" declares "${packageName}@${range}" but its wired group winner "${group.provider}" resolves ${group.version}.`,
+          fix: `Update the "${packageName}" range in "${record.name}", or change the winning provider's installed version.`
+        });
+      }
+    }
+  }
+  for (const record of records.values()) {
+    const usedSupply = usedSupplyMemo.get(record.name);
+    if (!usedSupply) {
+      continue;
+    }
+    for (const packageName of Object.keys(usedSupply)) {
+      const hasRange = packageName in record.dependencies || packageName in record.peerDependencies || packageName in record.devDependencies;
+      if (hasRange) {
+        continue;
+      }
+      diagnostics.push({
+        code: DiagnosticCode.W_NO_RANGE,
+        severity: "warning",
+        module: record.name,
+        package: packageName,
+        message: `Layer "${record.name}" receives "${packageName}" from its uses chain but declares no version range for it.`,
+        fix: `Add "${packageName}" to "${record.name}" dependencies or peerDependencies with the intended range.`
+      });
+    }
+  }
+  for (const record of records.values()) {
+    for (const [packageName, entry] of Object.entries(supply)) {
+      if (!(packageName in record.devDependencies)) {
+        continue;
+      }
+      const group = wiredGroupFor(record, packageName, entry);
+      if (!group?.version) {
+        continue;
+      }
+      const localVersion = resolveInstalledVersion(
+        record.root,
+        packageName
+      );
+      if (localVersion && localVersion !== group.version) {
+        diagnostics.push({
+          code: DiagnosticCode.W_TYPE_DRIFT,
+          severity: "warning",
+          module: record.name,
+          package: packageName,
+          found: localVersion,
+          required: group.version,
+          message: `Layer "${record.name}" types against its local "${packageName}@${localVersion}" but the code runs on the wired group winner's ${group.version}.`,
+          fix: `Align the "${packageName}" devDependencies copy in "${record.name}" with the winner's version ${group.version}.`
+        });
+      }
+    }
+  }
+  return { supply, mounts, diagnostics };
+}

package/dist/declaration/resolver.test.d.ts

@@ -0,0 +1 @@
+export {};