@seorii/libcollect 0.1.0 → 1.0.0

package/include-deps.mjs

@@ -6,10 +6,12 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import semver from "semver";
 
-const DEFAULT_CONCURRENCY = 10;
+const DEFAULT_CONCURRENCY = 50;
 const DEFAULT_SOURCE_SECTIONS = ["dependencies", "optionalDependencies", "peerDependencies"];
 const DEFAULT_INCLUDE_TYPES = ["peerDependency", "optionalDependency", "bundledDependency"];
 const REGISTRY_BASE = "https://registry.npmjs.org";
+const FETCH_RETRY_COUNT = 3;
+const FETCH_RETRY_BASE_DELAY_MS = 250;
 
 function createLimiter(maxConcurrency) {
   let activeCount = 0;
@@ -38,7 +40,13 @@ function createLimiter(maxConcurrency) {
   };
 }
 
-function createRegistryContext(concurrency = DEFAULT_CONCURRENCY) {
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function createRegistryContext(concurrency = DEFAULT_CONCURRENCY, logger = null) {
   const safeConcurrency =
     Number.isFinite(concurrency) && concurrency > 0 ? Math.floor(concurrency) : DEFAULT_CONCURRENCY;
 
@@ -47,20 +55,42 @@ function createRegistryContext(concurrency = DEFAULT_CONCURRENCY) {
     fetchLimit: createLimiter(safeConcurrency),
     metaCache: new Map(),
     resolvedCache: new Map(),
+    warnings: [],
+    logger,
   };
 }
 
 async function fetchJson(url, registryContext) {
   return registryContext.fetchLimit(async () => {
-    const res = await fetch(url, {
-      headers: { accept: "application/json" },
-    });
+    for (let attempt = 0; attempt <= FETCH_RETRY_COUNT; attempt += 1) {
+      let failureMessage = null;
 
-    if (!res.ok) {
-      throw new Error(`HTTP ${res.status} for ${url}`);
-    }
+      try {
+        const res = await fetch(url, {
+          headers: { accept: "application/json" },
+        });
 
-    return res.json();
+        if (res.ok) {
+          return res.json();
+        }
+
+        failureMessage = `HTTP ${res.status} for ${url}`;
+      } catch (error) {
+        failureMessage = error instanceof Error ? error.message : String(error);
+      }
+
+      if (attempt === FETCH_RETRY_COUNT) {
+        throw new Error(failureMessage);
+      }
+
+      const delayMs = FETCH_RETRY_BASE_DELAY_MS * 2 ** attempt;
+      if (typeof registryContext.logger === "function") {
+        registryContext.logger(
+          `[libcollect] registry fetch failed, retrying ${attempt + 1}/${FETCH_RETRY_COUNT} in ${delayMs}ms: ${failureMessage}`,
+        );
+      }
+      await sleep(delayMs);
+    }
   });
 }
 
@@ -99,12 +129,87 @@ function rangeMentionsPrerelease(range) {
   return /-\w/.test(String(range || ""));
 }
 
+function splitDisjunctiveRange(range) {
+  return String(range || "")
+    .split("||")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
 function getAllVersions(meta) {
   return Object.keys(meta.versions || {})
     .filter((version) => !!semver.valid(version))
     .sort(semver.rcompare);
 }
 
+function getPrereleaseChannel(version) {
+  const prerelease = semver.prerelease(version);
+  if (!prerelease || prerelease.length === 0) {
+    return null;
+  }
+
+  return String(prerelease[0] || "")
+    .split("-")[0]
+    .trim() || null;
+}
+
+function findFallbackVersionFromMeta(meta, wanted) {
+  const target = String(wanted || "").trim();
+  if (!semver.valid(target)) {
+    return null;
+  }
+
+  const targetChannel = getPrereleaseChannel(target);
+  if (!targetChannel) {
+    return null;
+  }
+
+  return (
+    getAllVersions(meta).find((version) => {
+      if (!semver.prerelease(version)) {
+        return false;
+      }
+
+      return (
+        semver.major(version) === semver.major(target) &&
+        semver.minor(version) === semver.minor(target) &&
+        semver.patch(version) === semver.patch(target) &&
+        getPrereleaseChannel(version) === targetChannel
+      );
+    }) || null
+  );
+}
+
+function versionSatisfiesWanted(version, wanted, meta) {
+  const target = String(wanted || "latest").trim() || "latest";
+  const distTags = meta["dist-tags"] || {};
+
+  if (target === "latest" || target === "*") {
+    return true;
+  }
+
+  const parts = splitDisjunctiveRange(target);
+  if (parts.length > 1) {
+    return parts.some((part) => versionSatisfiesWanted(version, part, meta));
+  }
+
+  if (distTags[target]) {
+    return version === distTags[target];
+  }
+
+  if (meta.versions?.[target]) {
+    return version === target;
+  }
+
+  if (!semver.validRange(target)) {
+    return false;
+  }
+
+  return semver.satisfies(version, target, {
+    includePrerelease: rangeMentionsPrerelease(target),
+  });
+}
+
 function pickVersionFromMeta(meta, wanted) {
   const versions = getAllVersions(meta);
   const distTags = meta["dist-tags"] || {};
@@ -122,13 +227,7 @@ function pickVersionFromMeta(meta, wanted) {
     return target;
   }
 
-  if (!semver.validRange(target)) {
-    return null;
-  }
-
-  return semver.maxSatisfying(versions, target, {
-    includePrerelease: rangeMentionsPrerelease(target),
-  });
+  return versions.find((version) => versionSatisfiesWanted(version, target, meta)) || null;
 }
 
 async function resolveVersion(name, wanted, registryContext) {
@@ -157,6 +256,14 @@ async function resolveVersion(name, wanted, registryContext) {
     const resolvedVersion = pickVersionFromMeta(meta, wanted);
 
     if (!resolvedVersion) {
+      const fallbackVersion = findFallbackVersionFromMeta(meta, wanted);
+      if (fallbackVersion) {
+        registryContext.warnings.push(
+          `${name}: requested ${wanted} is unavailable in the registry, using nearest published ${fallbackVersion} instead.`,
+        );
+        return fallbackVersion;
+      }
+
       throw new Error(`Cannot resolve version: ${name}@${wanted || "latest"}`);
     }
 
@@ -280,36 +387,44 @@ async function walkNode(name, wanted, edgeType, parent, registryContext, visited
     return makeSkippedNode(name, wanted, edgeType, parent, "non-registry spec");
   }
 
-  const alias = parseAliasSpec(wanted);
-  if (alias) {
-    const resolvedAlias = await resolveVersion(name, wanted, registryContext);
+  try {
+    const alias = parseAliasSpec(wanted);
+    if (alias) {
+      const resolvedAlias = await resolveVersion(name, wanted, registryContext);
+      return buildNodeFromPackage(
+        resolvedAlias.actualName,
+        name,
+        wanted,
+        resolvedAlias.version,
+        edgeType,
+        parent,
+        registryContext,
+        visited,
+        {
+          actualName: resolvedAlias.actualName,
+          aliased: true,
+        },
+      );
+    }
+
+    const resolvedVersion = await resolveVersion(name, wanted, registryContext);
     return buildNodeFromPackage(
-      resolvedAlias.actualName,
+      name,
       name,
       wanted,
-      resolvedAlias.version,
+      resolvedVersion,
       edgeType,
       parent,
       registryContext,
       visited,
-      {
-        actualName: resolvedAlias.actualName,
-        aliased: true,
-      },
     );
-  }
+  } catch (error) {
+    if (edgeType !== "root" && isVersionResolutionError(error)) {
+      return makeSkippedNode(name, wanted, edgeType, parent, "unresolvable version");
+    }
 
-  const resolvedVersion = await resolveVersion(name, wanted, registryContext);
-  return buildNodeFromPackage(
-    name,
-    name,
-    wanted,
-    resolvedVersion,
-    edgeType,
-    parent,
-    registryContext,
-    visited,
-  );
+    throw error;
+  }
 }
 
 function flattenTree(tree) {
@@ -354,7 +469,8 @@ function flattenTree(tree) {
 }
 
 async function collectNpmDeps(rootName, rootVersion = "latest", options = {}) {
-  const registryContext = options.registryContext || createRegistryContext(options.concurrency);
+  const registryContext =
+    options.registryContext || createRegistryContext(options.concurrency, options.logger);
   const visited = new Set();
   const tree = await walkNode(rootName, rootVersion, "root", null, registryContext, visited);
   const flat = flattenTree(tree);
@@ -375,6 +491,26 @@ function dedupe(items) {
   return [...new Set(items.filter(Boolean))];
 }
 
+function logProgress(logger, message) {
+  if (typeof logger !== "function") {
+    return;
+  }
+
+  logger(`[libcollect] ${message}`);
+}
+
+function shouldLogStep(index, total, step = 25) {
+  return index === 1 || index === total || index % step === 0;
+}
+
+function isVersionResolutionError(error) {
+  return (
+    error instanceof Error &&
+    (error.message.startsWith("Cannot resolve version:") ||
+      error.message.startsWith("Missing version metadata:"))
+  );
+}
+
 function getLibcollectConfig(pkg) {
   const raw = pkg.libcollect && typeof pkg.libcollect === "object" ? pkg.libcollect : {};
 
@@ -475,34 +611,57 @@ function addCandidate(candidates, node, extra = {}) {
   if (node.aliased || extra.aliased) candidate.aliased = true;
 }
 
-async function collectCandidates(pkg, config, registryContext) {
+async function collectCandidates(pkg, config, registryContext, logger) {
   const { roots, manualDependencies } = buildSourceRoots(pkg, config);
   const candidates = new Map();
   const warnings = [];
   const includeTypeSet = new Set(config.includeDependencyTypes);
 
-  for (const root of roots) {
+  logProgress(
+    logger,
+    `collecting dependency graph from ${roots.length} root(s) with concurrency ${registryContext.concurrency}`,
+  );
+
+  for (const [index, root] of roots.entries()) {
+    const rootProgress = `${index + 1}/${roots.length}`;
+    logProgress(logger, `root ${rootProgress}: ${root.name}@${root.range} (${root.sourceSection})`);
+
     if (root.sourceSection !== "dependencies") {
       if (isNonRegistrySpec(root.range)) {
         warnings.push(
           `${root.name}: ${root.sourceSection}에 있는 non-registry spec(${root.range})은 dependencies로 자동 승격하지 않았습니다.`,
         );
       } else {
-        const resolvedRoot = await resolveVersion(root.name, root.range, registryContext);
-        addCandidate(
-          candidates,
-          {
-            name: root.name,
-            requested: root.range,
-            version: typeof resolvedRoot === "string" ? resolvedRoot : resolvedRoot.version,
-            actualName: typeof resolvedRoot === "string" ? null : resolvedRoot.actualName || null,
-            dependencyType: "sourceSection",
-          },
-          {
-            sourceSection: root.sourceSection,
-            aliased: !!(typeof resolvedRoot !== "string" && resolvedRoot.actualName),
-          },
-        );
+        try {
+          const resolvedRoot = await resolveVersion(root.name, root.range, registryContext);
+          addCandidate(
+            candidates,
+            {
+              name: root.name,
+              requested: root.range,
+              version: typeof resolvedRoot === "string" ? resolvedRoot : resolvedRoot.version,
+              actualName: typeof resolvedRoot === "string" ? null : resolvedRoot.actualName || null,
+              dependencyType: "sourceSection",
+            },
+            {
+              sourceSection: root.sourceSection,
+              aliased: !!(typeof resolvedRoot !== "string" && resolvedRoot.actualName),
+            },
+          );
+        } catch (error) {
+          if (!isVersionResolutionError(error)) {
+            throw error;
+          }
+
+          warnings.push(
+            `${root.name}: ${root.sourceSection}에 있는 spec(${root.range})을 registry에서 찾지 못해 자동 승격하지 않았습니다.`,
+          );
+          logProgress(
+            logger,
+            `root ${rootProgress} skipped source-section promotion: unresolved version ${root.range}`,
+          );
+          continue;
+        }
       }
     }
 
@@ -510,13 +669,30 @@ async function collectCandidates(pkg, config, registryContext) {
       warnings.push(
         `${root.name}: root spec(${root.range})는 registry 기반이 아니어서 하위 dep 탐색을 건너뛰었습니다.`,
       );
+      logProgress(logger, `root ${rootProgress} skipped graph walk: non-registry spec ${root.range}`);
       continue;
     }
 
-    const result = await collectNpmDeps(root.name, root.range, {
-      registryContext,
-      concurrency: config.concurrency,
-    });
+    let result;
+
+    try {
+      result = await collectNpmDeps(root.name, root.range, {
+        registryContext,
+        concurrency: config.concurrency,
+      });
+    } catch (error) {
+      if (!isVersionResolutionError(error)) {
+        throw error;
+      }
+
+      warnings.push(
+        `${root.name}: root spec(${root.range})을 registry에서 찾지 못해 하위 dep 탐색을 건너뛰었습니다.`,
+      );
+      logProgress(logger, `root ${rootProgress} skipped graph walk: unresolved version ${root.range}`);
+      continue;
+    }
+
+    const candidateCountBefore = candidates.size;
 
     for (const node of result.flat) {
       if (node.skipped) {
@@ -532,6 +708,13 @@ async function collectCandidates(pkg, config, registryContext) {
 
       addCandidate(candidates, node);
     }
+
+    logProgress(
+      logger,
+      `root ${rootProgress} done: walked ${result.flat.length} node(s), ${
+        candidates.size - candidateCountBefore
+      } new candidate(s)`,
+    );
   }
 
   return { candidates, warnings, manualDependencies, roots };
@@ -548,14 +731,11 @@ async function resolvePreferredSpec(name, candidate, pkg, config, registryContex
 
   const meta = await getPackageMeta(targetName, registryContext);
   const versions = getAllVersions(meta);
-  const includePrerelease = normalizedRanges.some(rangeMentionsPrerelease);
 
   const commonVersion = versions.find((version) =>
     normalizedRanges.every((range) => {
       if (range === "latest" || range === "*") return true;
-      if (meta.versions?.[range]) return version === range;
-      if (!semver.validRange(range)) return false;
-      return semver.satisfies(version, range, { includePrerelease });
+      return versionSatisfiesWanted(version, range, meta);
     }),
   );
 
@@ -594,27 +774,46 @@ function diffKeys(beforeObj, afterObj) {
 
 export async function includeDependencies(
   packageJsonPath = path.resolve(process.cwd(), "package.json"),
+  options = {},
 ) {
+  const logger = typeof options.logger === "function" ? options.logger : null;
+  logProgress(logger, `reading ${packageJsonPath}`);
+
   const rawText = await fs.readFile(packageJsonPath, "utf8");
   const pkg = JSON.parse(rawText);
   const config = getLibcollectConfig(pkg);
-  const registryContext = createRegistryContext(config.concurrency);
+  const registryContext = createRegistryContext(config.concurrency, logger);
   const beforeDependencies = { ...pkg.dependencies };
 
+  logProgress(
+    logger,
+    `config loaded: source sections [${config.sourceSections.join(", ")}], include types [${config.includeDependencyTypes.join(", ")}]`,
+  );
+
   const { candidates, warnings, manualDependencies, roots } = await collectCandidates(
     pkg,
     config,
     registryContext,
+    logger,
   );
 
   const autoIncludedDependencies = {};
   const versionConflictWarnings = [];
+  const pendingCandidates = [...candidates.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .filter(([name]) => !manualDependencies[name]);
 
-  for (const [name, candidate] of [...candidates.entries()].sort(([a], [b]) =>
-    a.localeCompare(b),
-  )) {
-    if (manualDependencies[name]) {
-      continue;
+  logProgress(
+    logger,
+    `selecting preferred specs for ${pendingCandidates.length} auto-include candidate(s)`,
+  );
+
+  for (const [index, [name, candidate]] of pendingCandidates.entries()) {
+    if (shouldLogStep(index + 1, pendingCandidates.length)) {
+      logProgress(
+        logger,
+        `spec selection ${index + 1}/${pendingCandidates.length}: ${name}`,
+      );
     }
 
     const spec = await resolvePreferredSpec(name, candidate, pkg, config, registryContext);
@@ -643,7 +842,9 @@ export async function includeDependencies(
     exactVersions: config.exactVersions,
   };
 
+  logProgress(logger, `writing backup to ${packageJsonPath}.bak`);
   await fs.writeFile(`${packageJsonPath}.bak`, rawText, "utf8");
+  logProgress(logger, `writing updated package.json`);
   await fs.writeFile(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
 
   const { added, removed } = diffKeys(beforeDependencies, nextDependencies);
@@ -654,7 +855,7 @@ export async function includeDependencies(
     roots,
     added,
     removed,
-    warnings: [...warnings, ...versionConflictWarnings],
+    warnings: [...warnings, ...versionConflictWarnings, ...registryContext.warnings],
     autoIncludedCount: Object.keys(autoIncludedDependencies).length,
     dependencyCount: Object.keys(nextDependencies).length,
   };
@@ -684,7 +885,9 @@ async function runCli() {
   }
 
   try {
-    const result = await includeDependencies();
+    const result = await includeDependencies(undefined, {
+      logger: (message) => console.log(message),
+    });
     console.log(
       `[libcollect] roots: ${result.roots.map((x) => `${x.name}@${x.range}`).join(", ")}`,
     );