@dependably/npm-check 1.7.0

package/src/package-json-validator.js

@@ -0,0 +1,356 @@
+// src/package-json-validator.js
+// Standalone validation for a package.json manifest, mirroring validator.js's
+// contract: validatePackageJson(packageJson, options) => { valid, errors, warnings, info }.
+// Errors/warnings are { message, code } (errors are PackageJsonValidationError instances).
+
+import { walkOverrides } from './overrides.js';
+
+export class PackageJsonValidationError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'PackageJsonValidationError';
+    this.code = code;
+  }
+}
+
+// npm package-name rules (subset of validate-npm-package-name; no new deps):
+// optional @scope/, lowercase, url-safe, can't start with . or _.
+const NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+// Legacy variant for dependency keys: npm's registry still hosts mixed-case names
+// published before the lowercase-only rule (e.g. JSONStream). Case-insensitive so
+// those names are not flagged PJ_INVALID_DEP_NAME. The own-package `name` field
+// still uses the strict NAME_RE (new uploads must be lowercase).
+const LEGACY_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i;
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+const DEP_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'];
+
+/**
+ * Accept what npm accepts as a dependency "range": semver ranges, exact versions,
+ * `*`, dist-tags (latest), the npm:/file:/git:/github:/workspace:/http(s): protocols,
+ * and `owner/repo` GitHub shorthand.
+ */
+function isValidRange(range) {
+  if (typeof range !== 'string') return false;
+  const r = range.trim();
+  if (r === '' || r === '*' || r === 'latest' || r === 'x') return true;
+  if (/^(npm|file|git|git\+ssh|git\+https|git\+http|github|http|https|workspace|catalog|jsr):/i.test(r)) return true;
+  if (/^[\w.-]+\/[\w.#/-]+$/.test(r)) return true; // owner/repo[#ref] shorthand
+  if (/^[a-z][a-z0-9._-]*$/i.test(r)) return true; // dist-tag (latest, next, beta, canary, ...)
+  // caret/tilde/comparator/exact/x-ranges/||/hyphen/v-prefixed ranges
+  return /^[v\d~^<>=*xX][\w.\-+~^<>=|\s*]*$/.test(r);
+}
+
+// Each section helper takes the manifest plus the shared { errors, warnings }
+// sink and pushes its findings, keeping validatePackageJson a flat checklist.
+
+// --- name ---
+function validateName(packageJson, isPrivate, errors, warnings) {
+  if (packageJson.name === undefined) {
+    // private / workspace-root packages may legitimately omit name → warn, not error
+    if (isPrivate) {
+      warnings.push({ code: 'PJ_MISSING_NAME', message: 'no "name" field (allowed for private packages)' });
+    } else {
+      errors.push(new PackageJsonValidationError('package.json is missing "name"', 'PJ_MISSING_NAME'));
+    }
+  } else if (typeof packageJson.name !== 'string' || !NAME_RE.test(packageJson.name)) {
+    errors.push(new PackageJsonValidationError(`invalid package name "${packageJson.name}"`, 'PJ_INVALID_NAME'));
+  } else if (packageJson.name.length > 214) {
+    errors.push(new PackageJsonValidationError('package name exceeds 214 characters', 'PJ_NAME_TOO_LONG'));
+  }
+}
+
+// --- version ---
+function validateVersion(packageJson, isPrivate, errors, warnings) {
+  if (packageJson.version === undefined) {
+    if (isPrivate) {
+      warnings.push({ code: 'PJ_MISSING_VERSION', message: 'no "version" field (allowed for private packages)' });
+    } else {
+      errors.push(new PackageJsonValidationError('package.json is missing "version"', 'PJ_MISSING_VERSION'));
+    }
+  } else if (typeof packageJson.version !== 'string' || !SEMVER_RE.test(packageJson.version)) {
+    errors.push(new PackageJsonValidationError(`invalid version "${packageJson.version}" (expected semver)`, 'PJ_INVALID_VERSION'));
+  }
+}
+
+// --- dependency names + ranges across all four sections ---
+function validateDependencySections(packageJson, errors) {
+  for (const section of DEP_SECTIONS) {
+    const deps = packageJson[section];
+    if (deps === undefined) continue;
+    if (typeof deps !== 'object' || deps === null || Array.isArray(deps)) {
+      errors.push(new PackageJsonValidationError(`"${section}" must be an object`, 'PJ_INVALID_DEP_SECTION'));
+      continue;
+    }
+    for (const [name, range] of Object.entries(deps)) {
+      if (!LEGACY_NAME_RE.test(name)) {
+        errors.push(new PackageJsonValidationError(`invalid dependency name "${name}" in ${section}`, 'PJ_INVALID_DEP_NAME'));
+      }
+      if (!isValidRange(range)) {
+        errors.push(new PackageJsonValidationError(`invalid version range "${range}" for "${name}" in ${section}`, 'PJ_INVALID_DEP_RANGE'));
+      }
+    }
+  }
+}
+
+// --- scripts shape (object of string commands) ---
+function validateScripts(packageJson, errors) {
+  if (packageJson.scripts === undefined) return;
+  if (typeof packageJson.scripts !== 'object' || packageJson.scripts === null || Array.isArray(packageJson.scripts)) {
+    errors.push(new PackageJsonValidationError('"scripts" must be an object', 'PJ_INVALID_SCRIPTS'));
+    return;
+  }
+  for (const [k, v] of Object.entries(packageJson.scripts)) {
+    if (typeof v !== 'string') {
+      errors.push(new PackageJsonValidationError(`script "${k}" must be a string`, 'PJ_INVALID_SCRIPT_VALUE'));
+    }
+  }
+}
+
+// --- license (warn-level) ---
+function validateLicense(packageJson, isPrivate, warnings) {
+  if (packageJson.license === undefined && packageJson.licenses === undefined) {
+    if (!isPrivate) {
+      warnings.push({ code: 'PJ_MISSING_LICENSE', message: 'no "license" field (use a valid SPDX identifier)' });
+    }
+  } else if (packageJson.license !== undefined && typeof packageJson.license !== 'string') {
+    warnings.push({ code: 'PJ_INVALID_LICENSE', message: '"license" should be an SPDX string (object/array form is deprecated)' });
+  } else if (typeof packageJson.license === 'string' && /^see\s+license/i.test(packageJson.license)) {
+    warnings.push({ code: 'PJ_NONSTANDARD_LICENSE', message: `non-SPDX license "${packageJson.license}"` });
+  }
+}
+
+// --- bin / main / exports sanity (types only; FS existence is out of scope) ---
+function validateEntryPoints(packageJson, errors) {
+  if (packageJson.main !== undefined && typeof packageJson.main !== 'string') {
+    errors.push(new PackageJsonValidationError('"main" must be a string', 'PJ_INVALID_MAIN'));
+  }
+  if (packageJson.bin !== undefined && typeof packageJson.bin !== 'string' &&
+      (typeof packageJson.bin !== 'object' || packageJson.bin === null || Array.isArray(packageJson.bin))) {
+    errors.push(new PackageJsonValidationError('"bin" must be a string or an object', 'PJ_INVALID_BIN'));
+  }
+  if (packageJson.exports !== undefined &&
+      typeof packageJson.exports !== 'object' && typeof packageJson.exports !== 'string') {
+    errors.push(new PackageJsonValidationError('"exports" must be a string or an object', 'PJ_INVALID_EXPORTS'));
+  }
+}
+
+// Pull the glob list out of a workspaces field: a bare array, or { packages: [] }.
+function workspaceGlobs(ws) {
+  if (Array.isArray(ws)) return ws;
+  if (ws && typeof ws === 'object' && Array.isArray(ws.packages)) return ws.packages;
+  return null;
+}
+
+// --- workspaces shape (array of strings, or { packages: [...] }) ---
+function validateWorkspaces(packageJson, errors) {
+  if (packageJson.workspaces === undefined) return;
+  const arr = workspaceGlobs(packageJson.workspaces);
+  if (!arr) {
+    errors.push(new PackageJsonValidationError('"workspaces" must be an array or { packages: [] }', 'PJ_INVALID_WORKSPACES'));
+  } else if (!arr.every((p) => typeof p === 'string')) {
+    errors.push(new PackageJsonValidationError('"workspaces" entries must be strings (glob patterns)', 'PJ_INVALID_WORKSPACE_ENTRY'));
+  }
+}
+
+// Helpers for the `pnpm` field's sub-key types.
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+
+// pnpm-specific manifest fields and the type each must have. `peerDependencyRules`
+// is an object; `onlyBuiltDependencies`/`neverBuiltDependencies` are string arrays;
+// the rest are objects. Surfaced for both flavors (the field is harmless on npm,
+// and validating it where present is always useful).
+const PNPM_FIELD_TYPES = {
+  overrides: isPlainObject,
+  packageExtensions: isPlainObject,
+  peerDependencyRules: isPlainObject,
+  patchedDependencies: isPlainObject,
+  allowedDeprecatedVersions: isPlainObject,
+  onlyBuiltDependencies: isStringArray,
+  neverBuiltDependencies: isStringArray,
+  ignoredBuiltDependencies: isStringArray,
+  updateConfig: isPlainObject,
+  auditConfig: isPlainObject,
+  supportedArchitectures: isPlainObject
+};
+
+// --- overrides ranges (npm `overrides` + pnpm.overrides) ---
+// walkOverrides descends the nested npm form and the flat pnpm form and skips
+// `$`-references; each remaining leaf must be a valid range specifier.
+function validateOverrideRanges(overrides, label, errors) {
+  for (const { path, range } of walkOverrides(overrides)) {
+    if (!isValidRange(range)) {
+      errors.push(new PackageJsonValidationError(
+        `invalid override range "${range}" at ${label}/${path}`, 'PJ_INVALID_OVERRIDE_RANGE'));
+    }
+  }
+}
+
+function validateOverrides(packageJson, errors) {
+  if (packageJson.overrides !== undefined) {
+    if (!isPlainObject(packageJson.overrides)) {
+      errors.push(new PackageJsonValidationError('"overrides" must be an object', 'PJ_INVALID_OVERRIDES'));
+    } else {
+      validateOverrideRanges(packageJson.overrides, 'overrides', errors);
+    }
+  }
+  // pnpm.overrides is type-checked in validatePnpmField; validate its ranges here
+  // (only when it's actually an object, to avoid double-reporting a type error).
+  const pnpmOverrides = packageJson.pnpm && packageJson.pnpm.overrides;
+  if (isPlainObject(pnpmOverrides)) {
+    validateOverrideRanges(pnpmOverrides, 'pnpm.overrides', errors);
+  }
+}
+
+// --- range-carrying pnpm sub-fields (validation only; these ranges are loose
+// BY DESIGN — packageExtensions patches upstream metadata, allowedVersions /
+// allowedDeprecatedVersions are allowances — so we validate syntax but never
+// flag/pin them as "unpinned" the way overrides/deps are) ---
+
+// Validate a flat { name: range } map's range values.
+function validateRangeMap(map, label, errors) {
+  if (!isPlainObject(map)) return; // shape handled by the caller / type check; absent → nothing
+  for (const [name, range] of Object.entries(map)) {
+    if (!isValidRange(range)) {
+      const shown = typeof range === 'string' ? range : JSON.stringify(range);
+      errors.push(new PackageJsonValidationError(
+        `invalid version range "${shown}" for "${name}" in ${label}`, 'PJ_INVALID_RANGE'));
+    }
+  }
+}
+
+// pnpm.packageExtensions: { "selector@range": { dependencies|peerDependencies:
+// {name: range}, peerDependenciesMeta: {...} } } — the inner dep maps carry real
+// ranges that pnpm injects into the graph, so validate them.
+function validatePackageExtensions(packageExtensions, errors) {
+  if (!isPlainObject(packageExtensions)) return;
+  for (const [selector, ext] of Object.entries(packageExtensions)) {
+    if (!isPlainObject(ext)) {
+      errors.push(new PackageJsonValidationError(
+        `"pnpm.packageExtensions.${selector}" must be an object`, 'PJ_INVALID_PKG_EXTENSION'));
+      continue;
+    }
+    // pnpm packageExtensions extend all four dependency-map fields.
+    for (const depKey of ['dependencies', 'optionalDependencies', 'peerDependencies']) {
+      if (ext[depKey] === undefined) continue;
+      if (!isPlainObject(ext[depKey])) {
+        errors.push(new PackageJsonValidationError(
+          `"pnpm.packageExtensions.${selector}.${depKey}" must be an object`, 'PJ_INVALID_PKG_EXTENSION'));
+      } else {
+        validateRangeMap(ext[depKey], `pnpm.packageExtensions.${selector}.${depKey}`, errors);
+      }
+    }
+  }
+}
+
+function validatePnpmRanges(packageJson, errors) {
+  const pnpm = packageJson.pnpm;
+  if (!isPlainObject(pnpm)) return;
+  validatePackageExtensions(pnpm.packageExtensions, errors);
+  if (isPlainObject(pnpm.peerDependencyRules)) {
+    // `peerDependencyRules` itself is type-checked in validatePnpmField, but its
+    // nested `allowedVersions` sub-map is not — flag a wrong-typed one here.
+    const allowedVersions = pnpm.peerDependencyRules.allowedVersions;
+    if (allowedVersions !== undefined && !isPlainObject(allowedVersions)) {
+      errors.push(new PackageJsonValidationError(
+        '"pnpm.peerDependencyRules.allowedVersions" must be an object', 'PJ_INVALID_PNPM_FIELD'));
+    } else {
+      validateRangeMap(allowedVersions, 'pnpm.peerDependencyRules.allowedVersions', errors);
+    }
+  }
+  validateRangeMap(pnpm.allowedDeprecatedVersions, 'pnpm.allowedDeprecatedVersions', errors);
+}
+
+// --- bundleDependencies / bundledDependencies (array of package names that ship
+// INSIDE the tarball). npm accepts either spelling, and a boolean (bundle all /
+// none). Validate array-of-valid-names and warn when a name isn't declared in
+// dependencies/optionalDependencies (npm requires it). ---
+function collectDeclaredDeps(packageJson) {
+  const declared = new Set();
+  for (const section of ['dependencies', 'optionalDependencies']) {
+    if (isPlainObject(packageJson[section])) {
+      for (const name of Object.keys(packageJson[section])) declared.add(name);
+    }
+  }
+  return declared;
+}
+
+function validateBundledName(name, field, declared, errors, warnings) {
+  if (typeof name !== 'string' || !LEGACY_NAME_RE.test(name)) {
+    errors.push(new PackageJsonValidationError(
+      `invalid bundled dependency name ${JSON.stringify(name)} in ${field}`, 'PJ_INVALID_BUNDLE_DEP_NAME'));
+  } else if (!declared.has(name)) {
+    warnings.push({ code: 'PJ_BUNDLE_DEP_NOT_IN_DEPS',
+      message: `bundled dependency "${name}" is not listed in dependencies/optionalDependencies` });
+  }
+}
+
+function validateBundleDependencies(packageJson, errors, warnings) {
+  const declared = collectDeclaredDeps(packageJson);
+  for (const field of ['bundleDependencies', 'bundledDependencies']) {
+    const value = packageJson[field];
+    if (value === undefined || typeof value === 'boolean') continue; // boolean = bundle all/none
+    if (!Array.isArray(value)) {
+      errors.push(new PackageJsonValidationError(
+        `"${field}" must be an array of package names (or a boolean)`, 'PJ_INVALID_BUNDLE_DEPS'));
+      continue;
+    }
+    for (const name of value) validateBundledName(name, field, declared, errors, warnings);
+  }
+}
+
+// --- pnpm field (overrides / packageExtensions / build-script allowlists / …) ---
+function validatePnpmField(packageJson, errors, warnings) {
+  const pnpm = packageJson.pnpm;
+  if (pnpm === undefined) return;
+  if (!isPlainObject(pnpm)) {
+    errors.push(new PackageJsonValidationError('"pnpm" must be an object', 'PJ_INVALID_PNPM'));
+    return;
+  }
+  for (const [key, value] of Object.entries(pnpm)) {
+    const validator = PNPM_FIELD_TYPES[key];
+    if (!validator) {
+      warnings.push({ code: 'PJ_UNKNOWN_PNPM_KEY', message: `unrecognized pnpm config key "pnpm.${key}"` });
+      continue;
+    }
+    if (!validator(value)) {
+      const expected = validator === isStringArray ? 'an array of strings' : 'an object';
+      errors.push(new PackageJsonValidationError(`"pnpm.${key}" must be ${expected}`, 'PJ_INVALID_PNPM_FIELD'));
+    }
+  }
+}
+
+export function validatePackageJson(packageJson, options = {}) {
+  const errors = [];
+  const warnings = [];
+  const info = {};
+
+  if (!packageJson || typeof packageJson !== 'object' || Array.isArray(packageJson)) {
+    errors.push(new PackageJsonValidationError('package.json is not an object', 'PJ_NOT_OBJECT'));
+    return { valid: false, errors, warnings, info };
+  }
+
+  const isPrivate = packageJson.private === true;
+  info.private = isPrivate;
+
+  validateName(packageJson, isPrivate, errors, warnings);
+  validateVersion(packageJson, isPrivate, errors, warnings);
+
+  // --- private flag type ---
+  if (packageJson.private !== undefined && typeof packageJson.private !== 'boolean') {
+    errors.push(new PackageJsonValidationError('"private" must be a boolean', 'PJ_INVALID_PRIVATE'));
+  }
+
+  validateDependencySections(packageJson, errors);
+  validateScripts(packageJson, errors);
+  validateLicense(packageJson, isPrivate, warnings);
+  validateEntryPoints(packageJson, errors);
+  validateWorkspaces(packageJson, errors);
+  validatePnpmField(packageJson, errors, warnings);
+  validateOverrides(packageJson, errors);
+  validatePnpmRanges(packageJson, errors);
+  validateBundleDependencies(packageJson, errors, warnings);
+
+  const valid = errors.length === 0 && !(options.strictMode && warnings.length > 0);
+  return { valid, errors, warnings, info };
+}