fix(functions): warn when a functions lockfile omits peer dependencies

[IzaakGough]

Fixes #5673.

The problem

The build server runs npm ci with npm's default legacy-peer-deps=false. A lockfile resolved with that setting enabled omits the peer dependencies npm would otherwise install, so the build fails with Missing: <package> from lock file even though the local install succeeded.

A stock firebase init functions project is enough to hit it: jest is a peer dependency of the scaffolded firebase-functions-test, and npm ci validates the whole tree before dropping devDependencies, so a dev-only package fails a production deploy.

Until now the only signal was a multi-minute Cloud Build round trip returning several hundred lines of raw npm output. The workaround that spread through the issue was deleting package-lock.json, which only works because the builder then falls back to npm install.

The change

Warn before upload. warnIfLockfileOmitsPeerDeps reads the lockfile and reports non-optional peer dependencies it does not contain, resolving each peer the way npm does. Reading the artifact rather than npm's config matters: npm install --legacy-peer-deps produces exactly this lockfile while leaving nothing behind in config, so a config-based check is blind to it and simultaneously warns people whose lockfile is fine. Runs on the deploy path only, spawns nothing, and is wrapped so it can never fail a deploy.

The warning is suppressed when the functions directory ships an .npmrc enabling legacy-peer-deps, since that file is uploaded and the build server honors it, unless functions.ignore excludes it.

Explain the failure when it happens anyway. printLockfileErrors matches npm's out-of-sync error and leads with the far more common cause, a lockfile that is simply out of date, mentioning legacy-peer-deps second.

Verification

Reproduced against real deploys. A lockfile from npm install --legacy-peer-deps fails the build with the issue's exact error; adding only functions/.npmrc with legacy-peer-deps=true, lockfile byte-identical, makes the same deploy succeed.

The warning was exercised end to end against the built CLI: a lockfile missing jest warns while npm config get legacy-peer-deps reads false; a clean lockfile stays silent; a shipping .npmrc suppresses it; adding .npmrc to functions.ignore restores it.

No false positives against firebase-tools' own 1859-entry npm-shrinkwrap.json or a clean install of the same package.json.

Scope

Does not cover the other cause in that issue thread, where the lockfile was written by a different npm major than the build server uses (string-width-cjs and friends). The improved build failure message applies there; the pre-upload check does not.

[wiz-9635d3485b]

Wiz Scan Summary

Scanner	Findings
Vulnerabilities	-
Sensitive Data	-
Secrets	-
IaC Misconfigurations	-
SAST Findings	3  1
Software Management Findings	-
Total	3  1

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try the Wiz Code extension for VS Code, JetBrains, or Visual Studio.

[gemini-code-assist]

Code Review

This pull request adds warnings and clearer error messages when Cloud Functions deployments fail due to npm lockfile mismatches, specifically when legacy-peer-deps is enabled locally but not on the build server. It introduces local validation to warn users before deployment and enhances error reporting to print actionable troubleshooting steps if npm ci fails. The review feedback highlights several violations of the repository's style guide regarding the use of any as an escape hatch in reporter.ts, validate.ts, and the test suite, suggesting type-safe alternatives such as custom interfaces, intersection types, and proper error narrowing.

[gemini-code-assist]

Using as any violates the repository style guide rule against using any as an escape hatch. Since err is guaranteed to be a DeploymentError when called from printLockfileErrors, we can type the parameter more precisely and define a clean interface for the nested error structure to achieve full type safety.

interface DetailedError {
  message?: string;
  original?: DetailedError;
  context?: {
    body?: {
      error?: {
        message?: string;
      };
    };
  };
}

/** Collects every message in an error's cause chain so we can pattern match on them. */
function errorMessages(err: DeploymentError): string {
  const original = err.original as DetailedError | undefined;
  return [
    err.message,
    original?.message,
    original?.original?.message,
    original?.context?.body?.error?.message,
  ]
    .filter(Boolean)
    .join(" ");
}

References

1. Never use any or unknown as an escape hatch. Define proper interfaces/types or use type guards. ^(link)

[gemini-code-assist]

Avoid using any in the catch clause. Typing the caught error as unknown and narrowing it (or using safe checks) is more type-safe and adheres to the repository style guide.

  try {
    return /^\s*legacy-peer-deps\s*=/m.test(fs.readFileSync(npmrc, "utf8"));
  } catch (e: unknown) {
    const message = e instanceof Error ? e.message : String(e);
    logger.debug("Failed to read .npmrc in functions source directory:", message);
    return false;
  }

References

1. Never use any or unknown as an escape hatch. Define proper interfaces/types or use type guards. ^(link)

[gemini-code-assist]

Avoid using as any to attach custom properties to an Error object. Using an intersection type is a cleaner and type-safe alternative that adheres to the repository style guide.

Suggested change

	it("finds lockfile errors nested in the original error", () => {
	const rawError = new Error("Deployment failed") as any;
	rawError.original = {
	message:
	"npm ERR! `npm ci` can only install packages when your package.json and " +
	"package-lock.json are in sync. Missing: p-limit@2.3.0 from lock file",
	};
	it("finds lockfile errors nested in the original error", () => {
	const rawError = new Error("Deployment failed") as Error & { original?: unknown };
	rawError.original = {
	message:
	"npm ERR! `npm ci` can only install packages when your package.json and " +
	"package-lock.json are in sync. Missing: p-limit@2.3.0 from lock file",
	};

References

1. Never use any or unknown as an escape hatch. Define proper interfaces/types or use type guards. ^(link)