@patchstack/connect 0.3.30 → 0.3.32

package/dist/index.d.ts

@@ -87,10 +87,45 @@ declare function scanLockfile(cwd: string): Promise<Manifest>;
 interface WirePackage {
     name: string;
     version: string;
+    /**
+     * Where this exact name+version is installed, repo-relative and sorted.
+     *
+     * The same package can be installed more than once at different versions — a workspace pinning an old
+     * copy under `apps/api/node_modules`, a transitive dependency getting its own nested install. Without
+     * the locations, `lodash@4.17.11` and `lodash@4.17.21` arrive as two bare pairs and nothing can say
+     * WHICH one the app's own import resolves to. A consumer then has to treat every installed version as
+     * if the code used it: it warns on a copy nothing reaches, or pins a rule to a route running the safe
+     * one — a rule that never fires while reporting as protection.
+     *
+     * Node resolves an import by walking up from the importing file, so the map's import sites plus these
+     * paths together answer the question. Neither half answers it alone.
+     *
+     * OPT-IN. Absent unless the caller asks for locations (`scan --install-paths`), and absent even then
+     * when the scan source does not record them — see `installPathsComplete`, which is what separates
+     * "not installed there" from "we were not told".
+     *
+     * Off by default because it changes what leaves the machine. The package's standing promise is that
+     * `scan` sends names and versions and no paths of any kind; locations are a real widening of that, and
+     * an upload that widens it should be an explicit choice rather than a consequence of upgrading.
+     */
+    paths?: string[];
 }
 interface WirePayload {
     ecosystem: Manifest['ecosystem'];
     packages: WirePackage[];
+    /**
+     * Whether every entry's `paths` is the complete set of locations for it.
+     *
+     * False when locations were not requested at all, when the scan source cannot supply them (a yarn.lock
+     * is flat — hoisting is decided at install time and the file does not record it; a v1 npm lockfile
+     * describes the dependency graph, not the tree), or when only some entries had one. A consumer MUST NOT
+     * read a missing or short `paths` as "installed nowhere else" while this is false; absence is then "not
+     * recorded", which is not an answer.
+     *
+     * The default is therefore `false`, and that is the safe direction: the field withholds a negative
+     * rather than granting one.
+     */
+    installPathsComplete: boolean;
 }
 interface NormalizeStats {
     uniqueNames: number;
@@ -101,7 +136,14 @@ interface NormalizeResult {
     payload: WirePayload;
     stats: NormalizeStats;
 }
-declare function buildWirePayload(manifest: Manifest): NormalizeResult;
+interface WireOptions {
+    /**
+     * Include each package's install location. Off by default — see `WirePackage.paths`: it widens what
+     * `scan` transmits, so it is the caller's explicit choice, not a side effect of upgrading.
+     */
+    installPaths?: boolean;
+}
+declare function buildWirePayload(manifest: Manifest, options?: WireOptions): NormalizeResult;
 declare function compareVersions(a: string, b: string): number;
 
 declare const DEFAULT_ENDPOINT = "https://api.patchstack.com/monitor/pulse/manifest";
@@ -214,18 +256,26 @@ interface StackDescriptor {
     /** Hosting-related build-environment variable NAMES (never their values). */
     hostingEnvKeys: string[];
 }
+/**
+ * An environment, described structurally so it needs no ambient types.
+ *
+ * `@types/node` is not a dependency of this package, so nothing in its public surface may name
+ * `NodeJS.ProcessEnv`: a consumer without those types cannot compile against a signature that does.
+ * `process.env` satisfies this, and so does a plain object.
+ */
+type EnvLike = Record<string, string | undefined>;
 /**
  * Return the sorted NAMES of hosting-related environment variables present in
  * `env`. Only names are surfaced — never values — so a build fingerprint can
  * distinguish "deployed on Cloudflare" from "deployed on Vercel" without ever
  * disclosing a secret.
  */
-declare function collectHostingEnvKeys(env?: NodeJS.ProcessEnv): string[];
+declare function collectHostingEnvKeys(env?: EnvLike): string[];
 /**
  * Derive a {@link StackDescriptor} from the wire packages and the build
  * environment. Never throws: an unrecognised stack just yields nulls.
  */
-declare function detectStack(packages: readonly WirePackage[], env?: NodeJS.ProcessEnv): StackDescriptor;
+declare function detectStack(packages: readonly WirePackage[], env?: EnvLike): StackDescriptor;
 /** True when the descriptor carries no useful signal (nothing worth injecting). */
 declare function isEmptyStack(stack: StackDescriptor): boolean;
 
@@ -270,6 +320,11 @@ declare function ensureSourceWidget(cwd: string, siteUuid: string): SourceWidget
 interface ScanAndReportOptions {
     cwd?: string;
     config?: Config;
+    /**
+     * Include each package's install location in the uploaded payload. Off by default: it widens what
+     * leaves the machine, so it is an explicit choice rather than something an upgrade turns on.
+     */
+    installPaths?: boolean;
 }
 interface ScanAndReportResult {
     manifest: Manifest;

package/dist/index.js

@@ -325,7 +325,7 @@ async function walkNodeModules(cwd) {
     seen.set(await realpath(cwd), -1);
   } catch {
   }
-  return dedupeByShallowest(await walk(root, 0, seen));
+  return dedupeByShallowest(await walk(root, 0, seen, cwd));
 }
 function dedupeByShallowest(found) {
   const best = /* @__PURE__ */ new Map();
@@ -336,7 +336,7 @@ function dedupeByShallowest(found) {
   return [...best.values()].map(({ entry }) => entry);
 }
 var CONCURRENCY = 32;
-async function walk(dir, depth, seen) {
+async function walk(dir, depth, seen, root) {
   let names;
   try {
     names = await readdir(dir);
@@ -348,7 +348,7 @@ async function walk(dir, depth, seen) {
     const fullPath = path3.join(dir, name);
     const resolved = await claim(fullPath, seen, depth);
     if (resolved === null) return [];
-    if (PACKAGE_STORE_DIRS.has(name)) return walk(fullPath, depth, seen);
+    if (PACKAGE_STORE_DIRS.has(name)) return walk(fullPath, depth, seen, root);
     if (name.startsWith("@")) {
       let subNames;
       try {
@@ -361,16 +361,16 @@ async function walk(dir, depth, seen) {
         const scopedDir = path3.join(fullPath, sub);
         const scopedReal = await claim(scopedDir, seen, depth);
         if (scopedReal === null) return [];
-        return packageAndNested(scopedDir, scopedReal, depth, seen);
+        return packageAndNested(scopedDir, scopedReal, depth, seen, root);
       });
       return scoped.flat();
     }
-    return packageAndNested(fullPath, resolved, depth, seen);
+    return packageAndNested(fullPath, resolved, depth, seen, root);
   });
   return perEntry.flat();
 }
-async function packageAndNested(pkgDir, resolved, depth, seen) {
-  const [own, nested] = await Promise.all([readPackage(pkgDir, depth), walkNested(pkgDir, depth, seen)]);
+async function packageAndNested(pkgDir, resolved, depth, seen, root) {
+  const [own, nested] = await Promise.all([readPackage(pkgDir, depth, root), walkNested(pkgDir, depth, seen, root)]);
   return own === null ? nested : [{ entry: own, realpath: resolved, depth }, ...nested];
 }
 async function mapLimit(items, fn) {
@@ -385,7 +385,10 @@ async function mapLimit(items, fn) {
   await Promise.all(workers);
   return results;
 }
-async function readPackage(pkgDir, depth) {
+function installLocation(root, pkgDir, impl = path3) {
+  return impl.relative(root, pkgDir).split(impl.sep).join("/");
+}
+async function readPackage(pkgDir, depth, root) {
   let raw;
   try {
     raw = await readFile4(path3.join(pkgDir, "package.json"), "utf8");
@@ -404,14 +407,14 @@ async function readPackage(pkgDir, depth) {
   if (typeof parsed.version !== "string" || parsed.version.length === 0) {
     return null;
   }
-  return { name: parsed.name, version: parsed.version, direct: depth === 0 };
+  return { name: parsed.name, version: parsed.version, path: installLocation(root, pkgDir), direct: depth === 0 };
 }
-async function walkNested(pkgDir, depth, seen) {
+async function walkNested(pkgDir, depth, seen, root) {
   const nested = path3.join(pkgDir, "node_modules");
   if (await claim(nested, seen, depth + 1) === null) {
     return [];
   }
-  return walk(nested, depth + 1, seen);
+  return walk(nested, depth + 1, seen, root);
 }
 async function claim(dir, seen, depth) {
   let resolved;
@@ -1054,21 +1057,33 @@ async function exists(filePath) {
 }
 
 // src/normalize.ts
-function buildWirePayload(manifest) {
+function buildWirePayload(manifest, options = {}) {
+  const withPaths = options.installPaths === true;
   const seen = /* @__PURE__ */ new Map();
   const wirePackages = [];
+  const byIdentity = /* @__PURE__ */ new Map();
+  let entriesWithoutPath = 0;
   for (const entry of manifest.packages) {
+    const identity = `${entry.name}@${entry.version}`;
+    const location = withPaths && entry.path !== void 0 && entry.path !== "" ? entry.path : void 0;
+    if (location === void 0) entriesWithoutPath++;
+    const existing = byIdentity.get(identity);
+    if (existing) {
+      if (location !== void 0) addPath(existing, location);
+      continue;
+    }
     const versions = seen.get(entry.name);
     if (versions) {
-      if (versions.has(entry.version)) {
-        continue;
-      }
       versions.add(entry.version);
     } else {
       seen.set(entry.name, /* @__PURE__ */ new Set([entry.version]));
     }
-    wirePackages.push({ name: entry.name, version: entry.version });
+    const wire = { name: entry.name, version: entry.version };
+    if (location !== void 0) addPath(wire, location);
+    byIdentity.set(identity, wire);
+    wirePackages.push(wire);
   }
+  for (const wire of wirePackages) wire.paths?.sort();
   wirePackages.sort((a, b) => {
     if (a.name === b.name) {
       return compareVersions(a.version, b.version);
@@ -1082,7 +1097,18 @@ function buildWirePayload(manifest) {
     }
   }
   return {
-    payload: { ecosystem: manifest.ecosystem, packages: wirePackages },
+    payload: {
+      ecosystem: manifest.ecosystem,
+      packages: wirePackages,
+      // Every entry had a location, so a missing path anywhere means the package is not installed there.
+      // One entry without one forfeits that for the whole payload: a consumer reading a short `paths` has
+      // no way to tell which entry was the incomplete one.
+      //
+      // No separate check for "locations were not requested": with them off every entry counts as without
+      // one, so this is already false — which is the default, and the safe direction. An explicit
+      // `withPaths &&` here was a guard no test could distinguish from its absence.
+      installPathsComplete: entriesWithoutPath === 0 && manifest.packages.length > 0
+    },
     stats: {
       uniqueNames: seen.size,
       duplicateNames,
@@ -1090,6 +1116,10 @@ function buildWirePayload(manifest) {
     }
   };
 }
+function addPath(wire, installPath) {
+  if (wire.paths === void 0) wire.paths = [installPath];
+  else if (!wire.paths.includes(installPath)) wire.paths.push(installPath);
+}
 function compareVersions(a, b) {
   if (a === b) {
     return 0;
@@ -1665,7 +1695,7 @@ async function scanAndReport(options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const config = options.config ?? await resolveConfig({ cwd });
   const manifest = await scanLockfile(cwd);
-  const { payload, stats } = buildWirePayload(manifest);
+  const { payload, stats } = buildWirePayload(manifest, { installPaths: options.installPaths === true });
   const response = await postManifest(config, payload);
   if (config.siteUuid === null && response.uuid !== void 0 && response.uuid.length > 0) {
     await persistSiteUuid(cwd, response.uuid);