@socketsecurity/lib 6.0.6 → 6.0.7

package/dist/packages/licenses.js

@@ -33,7 +33,6 @@ const fileReferenceRegExp = /^SEE LICEN[CS]E IN (.+)$/;
 *   // incompatible contains only the GPL-3.0 node
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function collectIncompatibleLicenses(licenseNodes) {
 	const result = [];
 	for (let i = 0, { length } = licenseNodes; i < length; i += 1) {
@@ -51,7 +50,6 @@ function collectIncompatibleLicenses(licenseNodes) {
 *   collectLicenseWarnings(nodes) // ['Package is unlicensed']
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function collectLicenseWarnings(licenseNodes) {
 	const warnings = new require_primordials_map_set.MapCtor();
 	for (let i = 0, { length } = licenseNodes; i < length; i += 1) {
@@ -73,9 +71,8 @@ function collectLicenseWarnings(licenseNodes) {
 *   // node.type === 'License'
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function createAstNode(rawNode) {
-	return /* @__PURE__ */ require_objects_predicates.hasOwn(rawNode, "license") ? /* @__PURE__ */ createLicenseNode(rawNode) : /* @__PURE__ */ createBinaryOperationNode(rawNode);
+	return require_objects_predicates.hasOwn(rawNode, "license") ? createLicenseNode(rawNode) : createBinaryOperationNode(rawNode);
 }
 /**
 * Create a binary operation AST node.
@@ -91,7 +88,6 @@ function createAstNode(rawNode) {
 *   // node.type === 'BinaryOperation'
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function createBinaryOperationNode(rawNodeParam) {
 	let left;
 	let right;
@@ -103,7 +99,7 @@ function createBinaryOperationNode(rawNodeParam) {
 		type: BINARY_OPERATION_NODE_TYPE,
 		get left() {
 			if (left === void 0) {
-				left = /* @__PURE__ */ createAstNode(rawLeft);
+				left = createAstNode(rawLeft);
 				rawLeft = void 0;
 			}
 			return left;
@@ -111,7 +107,7 @@ function createBinaryOperationNode(rawNodeParam) {
 		conjunction,
 		get right() {
 			if (right === void 0) {
-				right = /* @__PURE__ */ createAstNode(rawRight);
+				right = createAstNode(rawRight);
 				rawRight = void 0;
 			}
 			return right;
@@ -127,7 +123,6 @@ function createBinaryOperationNode(rawNodeParam) {
 *   // node.type === 'License' && node.license === 'MIT'
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function createLicenseNode(rawNode) {
 	return {
 		__proto__: null,
@@ -144,7 +139,6 @@ function createLicenseNode(rawNode) {
 *   // ast is a BinaryOperation node with MIT and Apache-2.0 leaves
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function parseSpdxExp(spdxExp) {
 	try {
 		return (0, src_external_spdx_expression_parse.default)(spdxExp);
@@ -161,16 +155,23 @@ function parseSpdxExp(spdxExp) {
 *   // [{ license: 'MIT' }]
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function resolvePackageLicenses(licenseFieldValue, where) {
-	if (licenseFieldValue === "UNLICENSED" || licenseFieldValue === "UNLICENCED") return [{ license: "UNLICENSED" }];
+	if (licenseFieldValue === "UNLICENCED" || licenseFieldValue === "UNLICENSED") return [{ license: "UNLICENSED" }];
 	const match = require_primordials_regexp.RegExpPrototypeExec(fileReferenceRegExp, licenseFieldValue);
 	if (match) return [{
 		license: licenseFieldValue,
-		inFile: /* @__PURE__ */ require_paths_normalize.normalizePath((/* @__PURE__ */ require_node_path.getNodePath()).relative(where, match[1] || ""))
+		inFile: require_paths_normalize.normalizePath(require_node_path.getNodePath().relative(where, match[1] || ""))
 	}];
 	const licenseNodes = [];
-	if (/* @__PURE__ */ parseSpdxExp(licenseFieldValue)) {}
+	const ast = parseSpdxExp(licenseFieldValue);
+	if (ast) visitLicenses(ast, { License(node) {
+		const { license } = node;
+		if (license.startsWith("LicenseRef") || license.startsWith("DocumentRef")) {
+			licenseNodes.length = 0;
+			return false;
+		}
+		licenseNodes.push(node);
+	} });
 	return licenseNodes;
 }
 /**
@@ -190,9 +191,8 @@ function resolvePackageLicenses(licenseFieldValue, where) {
 *   // licenses === ['MIT', 'Apache-2.0']
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function visitLicenses(ast, visitor) {
-	const queue = [[/* @__PURE__ */ createAstNode(ast), void 0]];
+	const queue = [[createAstNode(ast), void 0]];
 	let pos = 0;
 	let { length: queueLength } = queue;
 	while (pos < queueLength) {
@@ -200,7 +200,7 @@ function visitLicenses(ast, visitor) {
 		const { 0: node, 1: parent } = queue[pos++];
 		const { type } = node;
 		const visitorRecord = visitor;
-		if (typeof visitorRecord[type] === "function" && /* @__PURE__ */ require_objects_predicates.hasOwn(visitor, type)) {
+		if (typeof visitorRecord[type] === "function" && require_objects_predicates.hasOwn(visitor, type)) {
 			if (type === LICENSE_NODE_TYPE) {
 				const licenseVisitor = visitorRecord["License"];
 				if (typeof licenseVisitor === "function" && licenseVisitor(node, parent) === false) break;

package/dist/packages/manifest.js

@@ -23,9 +23,9 @@ src_external_npm_package_arg = require_runtime.__toESM(src_external_npm_package_
 * @file Package manifest and packument fetching utilities.
 */
 const abortSignal = require_process_abort.getAbortSignal();
-const packageDefaultNodeRange = /* @__PURE__ */ require_constants_packages.getPackageDefaultNodeRange();
-const PACKAGE_DEFAULT_SOCKET_CATEGORIES = /* @__PURE__ */ require_constants_packages.getPackageDefaultSocketCategories();
-const packumentCache = /* @__PURE__ */ require_constants_packages.getPackumentCache();
+const packageDefaultNodeRange = require_constants_packages.getPackageDefaultNodeRange();
+const PACKAGE_DEFAULT_SOCKET_CATEGORIES = require_constants_packages.getPackageDefaultSocketCategories();
+const packumentCache = require_constants_packages.getPackumentCache();
 const pkgScopePrefixRegExp = /^@socketregistry\//;
 /**
 * Create a package.json object for a Socket registry package.
@@ -38,14 +38,13 @@ const pkgScopePrefixRegExp = /^@socketregistry\//;
 *   })
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function createPackageJson(sockRegPkgName, directory, options) {
 	const { dependencies, description, engines, exports: entryExportsRaw, files, keywords, main, overrides, resolutions, sideEffects, socket, type, version } = {
 		__proto__: null,
 		...options
 	};
 	const name = `@socketregistry/${sockRegPkgName.replace(pkgScopePrefixRegExp, "")}`;
-	const entryExports = /* @__PURE__ */ require_packages_exports.resolvePackageJsonEntryExports(entryExportsRaw);
+	const entryExports = require_packages_exports.resolvePackageJsonEntryExports(entryExportsRaw);
 	const githubUrl = `https://github.com/${require_constants_socket.SOCKET_GITHUB_ORG}/${require_constants_socket.SOCKET_REGISTRY_REPO_NAME}`;
 	return {
 		__proto__: null,
@@ -61,13 +60,13 @@ function createPackageJson(sockRegPkgName, directory, options) {
 			directory
 		},
 		...type ? { type } : {},
-		.../* @__PURE__ */ require_objects_predicates.isPlainObject(entryExports) ? { exports: { ...entryExports } } : {},
+		...require_objects_predicates.isPlainObject(entryExports) ? { exports: { ...entryExports } } : {},
 		...entryExports ? {} : { main: `${main ?? "./index.js"}` },
 		sideEffects: sideEffects !== void 0 && !!sideEffects,
-		.../* @__PURE__ */ require_objects_predicates.isPlainObject(dependencies) ? { dependencies: { ...dependencies } } : {},
-		.../* @__PURE__ */ require_objects_predicates.isPlainObject(overrides) ? { overrides: { ...overrides } } : {},
-		.../* @__PURE__ */ require_objects_predicates.isPlainObject(resolutions) ? { resolutions: { ...resolutions } } : {},
-		.../* @__PURE__ */ require_objects_predicates.isPlainObject(engines) ? { engines: require_primordials_object.ObjectFromEntries((/* @__PURE__ */ require_objects_sort.objectEntries(engines)).map((pair) => {
+		...require_objects_predicates.isPlainObject(dependencies) ? { dependencies: { ...dependencies } } : {},
+		...require_objects_predicates.isPlainObject(overrides) ? { overrides: { ...overrides } } : {},
+		...require_objects_predicates.isPlainObject(resolutions) ? { resolutions: { ...resolutions } } : {},
+		...require_objects_predicates.isPlainObject(engines) ? { engines: require_primordials_object.ObjectFromEntries(require_objects_sort.objectEntries(engines).map((pair) => {
 			const strKey = String(pair[0]);
 			const result = [strKey, pair[1]];
 			if (strKey === "node") {
@@ -80,7 +79,7 @@ function createPackageJson(sockRegPkgName, directory, options) {
 			return result;
 		})) } : { engines: { node: packageDefaultNodeRange } },
 		files: require_arrays_predicates.isArray(files) ? files.slice() : ["*.d.ts", "*.js"],
-		.../* @__PURE__ */ require_objects_predicates.isPlainObject(socket) ? { socket: { ...socket } } : { socket: { categories: PACKAGE_DEFAULT_SOCKET_CATEGORIES } }
+		...require_objects_predicates.isPlainObject(socket) ? { socket: { ...socket } } : { socket: { categories: PACKAGE_DEFAULT_SOCKET_CATEGORIES } }
 	};
 }
 /**
@@ -91,7 +90,6 @@ function createPackageJson(sockRegPkgName, directory, options) {
 *   const manifest = await fetchPackageManifest('lodash@4.17.21')
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 async function fetchPackageManifest(pkgNameOrId, options) {
 	const pacoteOptions = {
 		__proto__: null,
@@ -108,11 +106,11 @@ async function fetchPackageManifest(pkgNameOrId, options) {
 	} catch {}
 	if (signal?.aborted) return;
 	if (result) {
-		if (/* @__PURE__ */ require_packages_validation.isRegistryFetcherType((0, src_external_npm_package_arg.default)(pkgNameOrId, pacoteOptions.where).type)) return result;
+		if (require_packages_validation.isRegistryFetcherType((0, src_external_npm_package_arg.default)(pkgNameOrId, pacoteOptions.where).type)) return result;
 	}
 	if (result) {
 		const typedResult = result;
-		return await /* @__PURE__ */ fetchPackageManifest(`${typedResult.name}@${typedResult.version}`, pacoteOptions);
+		return await fetchPackageManifest(`${typedResult.name}@${typedResult.version}`, pacoteOptions);
 	}
 }
 /**
@@ -123,7 +121,6 @@ async function fetchPackageManifest(pkgNameOrId, options) {
 *   const packument = await fetchPackagePackument('lodash')
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 async function fetchPackagePackument(pkgNameOrId, options) {
 	try {
 		return await src_external_pacote.default.packument(pkgNameOrId, {

package/dist/packages/metadata-extensions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Package-extension lookup: match a package name + version against the
+ *   `packageExtensions` overrides table (the same data pnpm/yarn use to patch
+ *   missing dependency metadata) and merge the matching entries.
+ */
+/**
+ * Find package extensions for a given package.
+ *
+ * @example
+ *   ;```typescript
+ *   const extensions = findPackageExtensions('my-pkg', '1.0.0')
+ *   ```
+ */
+export declare function findPackageExtensions(pkgName: string, pkgVer: string): unknown;

package/dist/packages/metadata-extensions.js

@@ -0,0 +1,43 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_objects_mutate = require('../objects/mutate.js');
+const require_constants_packages = require('../constants/packages.js');
+let src_external_semver = require("../external/semver");
+src_external_semver = require_runtime.__toESM(src_external_semver);
+
+//#region src/packages/metadata-extensions.ts
+/**
+* @file Package-extension lookup: match a package name + version against the
+*   `packageExtensions` overrides table (the same data pnpm/yarn use to patch
+*   missing dependency metadata) and merge the matching entries.
+*/
+const packageExtensions = require_constants_packages.getPackageExtensions();
+/**
+* Find package extensions for a given package.
+*
+* @example
+*   ;```typescript
+*   const extensions = findPackageExtensions('my-pkg', '1.0.0')
+*   ```
+*/
+function findPackageExtensions(pkgName, pkgVer) {
+	let result;
+	for (const entry of packageExtensions) {
+		const selector = String(entry[0]);
+		const ext = entry[1];
+		const lastAtSignIndex = selector.lastIndexOf("@");
+		if (pkgName === selector.slice(0, lastAtSignIndex)) {
+			const range = selector.slice(lastAtSignIndex + 1);
+			if (src_external_semver.satisfies(pkgVer, range)) {
+				if (result === void 0) result = {};
+				if (typeof ext === "object" && ext !== null) require_objects_mutate.merge(result, ext);
+			}
+		}
+	}
+	return result;
+}
+
+//#endregion
+exports.findPackageExtensions = findPackageExtensions;

package/dist/packages/normalize.js

@@ -9,7 +9,7 @@ const require_primordials_object = require('../primordials/object.js');
 const require_objects_mutate = require('../objects/mutate.js');
 const require_constants_socket = require('../constants/socket.js');
 const require_regexps_escape = require('../regexps/escape.js');
-const require_packages_operations = require('./operations.js');
+const require_packages_metadata_extensions = require('./metadata-extensions.js');
 let src_external_normalize_package_data = require("../external/normalize-package-data");
 src_external_normalize_package_data = require_runtime.__toESM(src_external_normalize_package_data);
 
@@ -30,7 +30,6 @@ function getEscapedScopeRegExp() {
 *   const normalized = normalizePackageJson(pkgJson)
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function normalizePackageJson(pkgJson, options) {
 	const { preserve } = {
 		__proto__: null,
@@ -47,8 +46,8 @@ function normalizePackageJson(pkgJson, options) {
 	];
 	(0, src_external_normalize_package_data.default)(pkgJson);
 	if (pkgJson.name && pkgJson.version) {
-		const extensions = /* @__PURE__ */ require_packages_operations.findPackageExtensions(pkgJson.name, pkgJson.version);
-		if (extensions && typeof extensions === "object") /* @__PURE__ */ require_objects_mutate.merge(pkgJson, extensions);
+		const extensions = require_packages_metadata_extensions.findPackageExtensions(pkgJson.name, pkgJson.version);
+		if (extensions && typeof extensions === "object") require_objects_mutate.merge(pkgJson, extensions);
 	}
 	for (const { 0: key, 1: value } of preserved) pkgJson[key] = value;
 	return pkgJson;
@@ -62,7 +61,6 @@ function normalizePackageJson(pkgJson, options) {
 *   resolveEscapedScope('lodash') // undefined
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function resolveEscapedScope(sockRegPkgName) {
 	return require_primordials_regexp.RegExpPrototypeExec(getEscapedScopeRegExp(), sockRegPkgName)?.[0] || void 0;
 }
@@ -74,11 +72,10 @@ function resolveEscapedScope(sockRegPkgName) {
 *   resolveOriginalPackageName('@socketregistry/is-number') // 'is-number'
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function resolveOriginalPackageName(sockRegPkgName) {
 	const name = require_primordials_string.StringPrototypeStartsWith(sockRegPkgName, `${"@socketregistry"}/`) ? sockRegPkgName.slice(require_constants_socket.SOCKET_REGISTRY_SCOPE.length + 1) : sockRegPkgName;
-	const escapedScope = /* @__PURE__ */ resolveEscapedScope(name);
-	return escapedScope ? `${/* @__PURE__ */ unescapeScope(escapedScope)}/${require_primordials_string.StringPrototypeSlice(name, escapedScope.length)}` : name;
+	const escapedScope = resolveEscapedScope(name);
+	return escapedScope ? `${unescapeScope(escapedScope)}/${require_primordials_string.StringPrototypeSlice(name, escapedScope.length)}` : name;
 }
 /**
 * Convert escaped scope to standard npm scope format.
@@ -88,7 +85,6 @@ function resolveOriginalPackageName(sockRegPkgName) {
 *   unescapeScope('babel__') // '@babel'
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function unescapeScope(escapedScope) {
 	if (escapedScope.length < "__".length) return `@${escapedScope}`;
 	return `@${escapedScope.slice(0, -"__".length)}`;

package/dist/packages/provenance.js

@@ -3,11 +3,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
 const require_primordials_buffer = require('../primordials/buffer.js');
-const require_primordials_string = require('../primordials/string.js');
 const require_abort_signal = require('../abort/signal.js');
+const require_primordials_string = require('../primordials/string.js');
 const require_primordials_array = require('../primordials/array.js');
-const require_primordials_object = require('../primordials/object.js');
 const require_primordials_json = require('../primordials/json.js');
+const require_primordials_object = require('../primordials/object.js');
 const require_objects_predicates = require('../objects/predicates.js');
 const require_constants_agents = require('../constants/agents.js');
 const require_constants_packages = require('../constants/packages.js');
@@ -21,7 +21,7 @@ src_external_make_fetch_happen = require_runtime.__toESM(src_external_make_fetch
 */
 const SLSA_PROVENANCE_V0_2 = "https://slsa.dev/provenance/v0.2";
 const SLSA_PROVENANCE_V1_0 = "https://slsa.dev/provenance/v1";
-let _fetcher;
+let cachedFetcher;
 /**
 * Comparator ordering two trust statuses by ascending trust level. Sorts an
 * array of statuses lowest-trust-first; negate for highest-first.
@@ -50,7 +50,6 @@ function didTrustDecrease(prev, next) {
 *   const provenance = await fetchPackageProvenance('lodash', '4.17.21')
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 async function fetchPackageProvenance(pkgName, pkgVersion, options) {
 	const { signal, timeout = 1e4 } = {
 		__proto__: null,
@@ -58,7 +57,7 @@ async function fetchPackageProvenance(pkgName, pkgVersion, options) {
 	};
 	if (signal?.aborted) return;
 	const compositeSignal = require_abort_signal.createCompositeAbortSignal(signal, require_abort_signal.createTimeoutSignal(timeout));
-	const fetcher = /* @__PURE__ */ getFetcher();
+	const fetcher = getFetcher();
 	try {
 		const response = await fetcher(`${require_constants_agents.NPM_REGISTRY_URL}/-/npm/v1/attestations/${encodeURIComponent(pkgName)}@${encodeURIComponent(pkgVersion)}`, {
 			method: "GET",
@@ -72,8 +71,8 @@ async function fetchPackageProvenance(pkgName, pkgVersion, options) {
 * Find the first attestation with valid provenance data.
 */
 function findProvenance(attestations) {
-	for (const attestation of attestations) {
-		const att = attestation;
+	for (let i = 0, { length } = attestations; i < length; i += 1) {
+		const att = attestations[i];
 		try {
 			let predicate = att.predicate;
 			if (!predicate && att.bundle?.dsseEnvelope?.payload) try {
@@ -100,13 +99,12 @@ function getAttestations(attestationData) {
 		return att.predicateType === SLSA_PROVENANCE_V0_2 || att.predicateType === SLSA_PROVENANCE_V1_0;
 	});
 }
-/*@__NO_SIDE_EFFECTS__*/
 function getFetcher() {
-	if (_fetcher === void 0) _fetcher = src_external_make_fetch_happen.default.defaults({
-		cachePath: /* @__PURE__ */ require_constants_packages.getPacoteCachePath(),
+	if (cachedFetcher === void 0) cachedFetcher = src_external_make_fetch_happen.default.defaults({
+		cachePath: require_constants_packages.getPacoteCachePath(),
 		cache: "force-cache"
 	});
-	return _fetcher;
+	return cachedFetcher;
 }
 /**
 * Convert raw attestation data to user-friendly provenance details.
@@ -174,15 +172,15 @@ function getTrustStatus(meta) {
 		trustedPublisher: false,
 		stagedPublish: false
 	};
-	if (!/* @__PURE__ */ require_objects_predicates.isObject(meta)) return status;
+	if (!require_objects_predicates.isObject(meta)) return status;
 	const npmUser = require_primordials_object.ObjectHasOwn(meta, "_npmUser") ? meta["_npmUser"] : void 0;
-	if (/* @__PURE__ */ require_objects_predicates.isObject(npmUser)) {
+	if (require_objects_predicates.isObject(npmUser)) {
 		if (require_primordials_object.ObjectHasOwn(npmUser, "approver") && npmUser["approver"]) status.stagedPublish = true;
 		if (require_primordials_object.ObjectHasOwn(npmUser, "trustedPublisher") && npmUser["trustedPublisher"]) status.trustedPublisher = true;
 	}
 	const dist = require_primordials_object.ObjectHasOwn(meta, "dist") ? meta["dist"] : void 0;
-	const attestations = /* @__PURE__ */ require_objects_predicates.isObject(dist) && require_primordials_object.ObjectHasOwn(dist, "attestations") ? dist["attestations"] : void 0;
-	if (/* @__PURE__ */ require_objects_predicates.isObject(attestations) && require_primordials_object.ObjectHasOwn(attestations, "provenance") && attestations["provenance"]) status.provenance = true;
+	const attestations = require_objects_predicates.isObject(dist) && require_primordials_object.ObjectHasOwn(dist, "attestations") ? dist["attestations"] : void 0;
+	if (require_objects_predicates.isObject(attestations) && require_primordials_object.ObjectHasOwn(attestations, "provenance") && attestations["provenance"]) status.provenance = true;
 	return status;
 }
 /**
@@ -190,15 +188,15 @@ function getTrustStatus(meta) {
 */
 function isTrustedPublisher(value) {
 	if (typeof value !== "string" || !value) return false;
-	let url = /* @__PURE__ */ require_url_parse.parseUrl(value);
+	let url = require_url_parse.parseUrl(value);
 	let hostname = url?.hostname;
 	if (!url && require_primordials_string.StringPrototypeIncludes(value, "@")) {
 		const firstPart = require_primordials_string.StringPrototypeSplit(value, "@")[0];
-		if (firstPart) url = /* @__PURE__ */ require_url_parse.parseUrl(firstPart);
+		if (firstPart) url = require_url_parse.parseUrl(firstPart);
 		if (url) hostname = url.hostname;
 	}
 	if (!url) {
-		const httpsUrl = /* @__PURE__ */ require_url_parse.parseUrl(`https://${value}`);
+		const httpsUrl = require_url_parse.parseUrl(`https://${value}`);
 		if (httpsUrl) hostname = httpsUrl.hostname;
 	}
 	if (hostname) return hostname === "github.com" || require_primordials_string.StringPrototypeEndsWith(hostname, ".github.com") || hostname === "gitlab.com" || require_primordials_string.StringPrototypeEndsWith(hostname, ".gitlab.com");

package/dist/packages/read.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file Read + parse a package.json. The package-aware layer over
+ *   `fs/read-json`: resolves a dir-or-file path to its package.json, parses,
+ *   and optionally normalizes or returns an editable instance.
+ */
+import type { NormalizeOptions, PackageJson, ReadPackageJsonOptions } from './types';
+/**
+ * Read and parse a package.json file asynchronously.
+ *
+ * @example
+ *   ;```typescript
+ *   const pkgJson = await readPackageJson('/tmp/my-project')
+ *   console.log(pkgJson?.name)
+ *   ```
+ */
+export declare function readPackageJson(filepath: string, options?: ReadPackageJsonOptions): Promise<PackageJson | undefined>;
+/**
+ * Read and parse package.json from a file path synchronously.
+ *
+ * @example
+ *   ;```typescript
+ *   const pkgJson = readPackageJsonSync('/tmp/my-project')
+ *   console.log(pkgJson?.name)
+ *   ```
+ */
+export declare function readPackageJsonSync(filepath: string, options?: NormalizeOptions & {
+    editable?: boolean | undefined;
+    throws?: boolean | undefined;
+}): PackageJson | undefined;

package/dist/packages/read.js

@@ -0,0 +1,66 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_fs_read_json = require('../fs/read-json.js');
+const require_paths_packages = require('../paths/packages.js');
+const require_packages_normalize = require('./normalize.js');
+const require_packages_edit = require('./edit.js');
+
+//#region src/packages/read.ts
+/**
+* @file Read + parse a package.json. The package-aware layer over
+*   `fs/read-json`: resolves a dir-or-file path to its package.json, parses,
+*   and optionally normalizes or returns an editable instance.
+*/
+/**
+* Read and parse a package.json file asynchronously.
+*
+* @example
+*   ;```typescript
+*   const pkgJson = await readPackageJson('/tmp/my-project')
+*   console.log(pkgJson?.name)
+*   ```
+*/
+async function readPackageJson(filepath, options) {
+	const { editable, normalize, throws, ...normalizeOptions } = {
+		__proto__: null,
+		...options
+	};
+	const pkgJson = await require_fs_read_json.readJson(require_paths_packages.resolvePackageJsonPath(filepath), { throws });
+	if (pkgJson) {
+		if (editable) return await require_packages_edit.toEditablePackageJson(pkgJson, {
+			path: filepath,
+			normalize,
+			...normalizeOptions
+		});
+		return normalize ? require_packages_normalize.normalizePackageJson(pkgJson, normalizeOptions) : pkgJson;
+	}
+}
+/**
+* Read and parse package.json from a file path synchronously.
+*
+* @example
+*   ;```typescript
+*   const pkgJson = readPackageJsonSync('/tmp/my-project')
+*   console.log(pkgJson?.name)
+*   ```
+*/
+function readPackageJsonSync(filepath, options) {
+	const { editable, normalize, throws, ...normalizeOptions } = {
+		__proto__: null,
+		...options
+	};
+	const pkgJson = require_fs_read_json.readJsonSync(require_paths_packages.resolvePackageJsonPath(filepath), { throws });
+	if (pkgJson) {
+		if (editable) return require_packages_edit.toEditablePackageJsonSync(pkgJson, {
+			path: filepath,
+			normalize,
+			...normalizeOptions
+		});
+		return normalize ? require_packages_normalize.normalizePackageJson(pkgJson, normalizeOptions) : pkgJson;
+	}
+}
+
+//#endregion
+exports.readPackageJson = readPackageJson;
+exports.readPackageJsonSync = readPackageJsonSync;

package/dist/packages/specs.d.ts

@@ -1,6 +1,17 @@
 /**
- * @file Package spec parsing and GitHub URL utilities.
+ * @file Package spec parsing, name resolution, and GitHub URL utilities.
  */
+/**
+ * Get the release tag for a version.
+ *
+ * @example
+ *   ;```typescript
+ *   getReleaseTag('lodash@latest') // 'latest'
+ *   getReleaseTag('@scope/pkg@beta') // 'beta'
+ *   getReleaseTag('lodash') // ''
+ *   ```
+ */
+export declare function getReleaseTag(spec: string): string;
 /**
  * Extract user and project from GitHub repository URL.
  *
@@ -54,3 +65,39 @@ export declare function isGitHubTgzSpec(spec: unknown, where?: string): boolean;
  *   ```
  */
 export declare function isGitHubUrlSpec(spec: unknown, where?: string): boolean;
+/**
+ * Slugify an npm package name into a hyphenated identifier suitable for
+ * User-Agent tokens, log namespaces, file paths, and other contexts where `@`
+ * and `/` are not welcome.
+ *
+ * @example
+ *   ;```typescript
+ *   pkgNameToSlug('@socketsecurity/lib') // 'socketsecurity-lib'
+ *   pkgNameToSlug('@cyclonedx/cdxgen') // 'cyclonedx-cdxgen'
+ *   pkgNameToSlug('lodash') // 'lodash'
+ *   ```
+ */
+export declare function pkgNameToSlug(pkgName: string): string;
+/**
+ * Resolve full package name from a PURL object with custom delimiter.
+ *
+ * @example
+ *   ;```typescript
+ *   resolvePackageName({ name: 'core', namespace: '@babel' }) // '@babel/core'
+ *   resolvePackageName({ name: 'lodash' }) // 'lodash'
+ *   ```
+ */
+export declare function resolvePackageName(purlObj: {
+    name: string;
+    namespace?: string | undefined;
+}, delimiter?: string): string;
+/**
+ * Convert npm package name to Socket registry format with delimiter.
+ *
+ * @example
+ *   ;```typescript
+ *   resolveRegistryPackageName('@babel/core') // 'babel__core'
+ *   resolveRegistryPackageName('lodash') // 'lodash'
+ *   ```
+ */
+export declare function resolveRegistryPackageName(pkgName: string): string;