fix(esbuild): honor package.patterns negations in packaged artifacts - #13795

Summary

• Honor package.patterns negation patterns (!...) when the built-in esbuild build packages function artifacts — both with package.individually (per-function zips) and for combined-service packaging
• Function-level patterns are merged after service-level patterns (function wins on conflict), matching the merge order documented for classic packaging; without individually, function-level patterns are ignored, consistent with classic packaging, which already warns about that combination
• Fully excluded node_modules subtrees leave no empty directory entries in the zip
• The compiled handler bundle, its sourcemap (when emitted), and package.json/lockfile are always packaged and cannot be excluded via patterns
• Observability: a per-artifact Excluded <N> entries from <zip> via package.patterns info line (visible with --verbose), a once-per-run warning when patterns exclude everything under node_modules while packages: external is active, and debug traces of the merged pattern list and included/excluded entry counts
• New pure helper packages/serverless/lib/utils/package-patterns.js mirrors classic packaging's ordered last-match-wins pattern semantics; a parity test suite runs the helper and the real classic resolveFilePathsFromPatterns against the same fixture trees and fails CI on any drift
• Docs: docs/sf/providers/aws/guide/building.md gains a "Packaging Patterns" section stating which parts of an esbuild artifact patterns apply to
• Classic (non-esbuild) packaging source is untouched; artifacts for configs without negation patterns remain content-identical

Root cause

With build.esbuild active, package.patterns were only used as a positive glob to add extra files from the source directory. Negation patterns match nothing in a positive glob, so they were silently ignored, and the entire shared .serverless/build/node_modules tree was copied into every function artifact via zip.directory() with no filtering. This contradicted the packaging docs ("Packaging functions separately"), which state that per-function patterns merge with service-wide patterns and support ! exclusions.

The fix applies the ordered pattern toggle (last match wins, same semantics as classic packaging) as a predicate over the deterministic sorted entry walk introduced in #13794, and runs the additional-include list through the same compiled toggle, so a function-level negation can also drop a service-level include. Filtering happens after the sort, so entry-order determinism is preserved (pinned by 6-run hash-stability tests with filtering active). Patterns cannot suppress the fail-fast contract: an unreadable file under node_modules still fails packaging with CANNOT_READ_FILE even when patterns exclude it (test-enforced on both packaging paths).

Test plan

• 61 new unit tests across 3 suites: helper semantics (package-patterns.test.js), classic-engine parity (package-patterns-parity.test.js), and artifact filtering incl. whole-zip sha256 identity for pattern-less configs, 6-run hash stability with filtering active, directory-entry pruning, warning dedupe, unreadable-entry fail-fast, and _packageAll (package-patterns-filtering.test.js)
• Full unit suite green: 191 suites, 3697 tests; all determinism/fail-fast suites from fix(esbuild): make packaged zip entry order deterministic #13794 untouched and passing
• Live A/B packaging against main: the function with negations loses exactly the 416 targeted entries (2361 → 1945 zip entries), zero collateral; the function without patterns produces a byte-identical artifact (whole-zip sha256 equal between the main CLI and this branch's CLI)
• Hash stability with negations at scale: a ~2,700-entry service packaged 3× with a !node_modules/<dep>/** negation — hashes constant across runs, entry-list diff shows exactly that dependency's subtree (+ its directory entry) removed and nothing else
• Exclude-everything warning fires exactly once per run (both functions met the trigger; one line printed), visible without --verbose
• Lint and Prettier clean on all changed files
• No classic packaging source file modified (git status on packages/serverless/lib/plugins/package/ clean)

Coverage notes, for reviewer awareness:

• The parity suite does not cover devDependencyExcludeSet ordering (untested on both engines) or directory-entry pruning (classic packaging enumerates files only, so zip directory entries have no classic counterpart to compare against; the pruning behavior is pinned by dedicated esbuild-side tests instead).
• The Excluded <N> entries line is emitted at the info level, so it appears only with --verbose — consistent with classic packaging's exclusion logging.
• Directory includes (a defensively-handled branch that globby's onlyFiles default makes unreachable from user config) intentionally receive no pattern predicate; commented at both call sites.

How to test

Use a project with build.esbuild + packages: external, package.individually: true, and per-function negation patterns:

build:
  esbuild:
    bundle: true
    packages: external

package:
  individually: true

functions:
  function1:
    handler: src/fn1.handler
  function2:
    handler: src/fn2.handler
    package:
      patterns:
        - '!node_modules/fastify/**'
        - '!node_modules/serverless-http/**'

where both functions depend on fastify and serverless-http among other dependencies.

# 1. Bug on the released CLI: negations are silently ignored
rm -rf .serverless
serverless package
unzip -l .serverless/*function2.zip | grep -cE "node_modules/(fastify|serverless-http)/"
# -> 416 (entries the patterns should have excluded are all present)

# 2. Fix on this branch (CLI run from source)
rm -rf .serverless
node <path-to-this-checkout>/packages/sf-core/bin/sf-core.js package
unzip -l .serverless/*function2.zip | grep -cE "node_modules/(fastify|serverless-http)/"
# -> 0
unzip -l .serverless/*function2.zip | grep -E "node_modules/(fastify|serverless-http)/$"
# -> no output: no empty directory entries left behind
unzip -l .serverless/*function1.zip | tail -2
# -> same entry count as before the fix: a function without patterns is untouched

# 3. Exclusion visibility (info level, requires --verbose)
rm -rf .serverless
node <path-to-this-checkout>/packages/sf-core/bin/sf-core.js package --verbose 2>&1 | grep "via package.patterns"
# -> Excluded 416 entries from <service>-function2.zip via package.patterns

# 4. Exclude-everything warning: temporarily add a service-level pattern
#      package:
#        patterns:
#          - '!node_modules/**'
#    and repackage. Exactly one warning prints (no --verbose needed):
#    "package.patterns exclude everything under node_modules, but "packages: external"
#     requires dependencies in the artifact. If dependencies are provided another way
#     (e.g. a Lambda layer) or this exclusion predates build.esbuild, review or remove
#     these patterns."

# 5. Unit tests
npm run test:unit -w @serverless/framework -- package-patterns
# -> 3 suites, 61 tests

Release note callout (behavior-activating fix)

This fix activates configuration that was previously inert. Any existing package.patterns negations in a build.esbuild service — patterns that have had no effect until now — take effect on the next deploy and remove the matched files from the artifacts.

Two configurations deserve explicit attention:

• Exclude-everything: !node_modules/** combined with packages: external (common in Lambda-layer setups, or carried over from before adopting build.esbuild) now produces artifacts without their dependencies. The new once-per-run warning flags exactly this case.
• Cherry-picking (activates silently): exclude-everything plus re-includes, e.g. !node_modules/** + node_modules/some-dep/**. Re-include patterns match only the named package's own files — never its transitive dependencies, which live as sibling directories. These are the documented semantics (classic packaging has always worked this way), but the re-include list has not been enforced while build.esbuild ignored patterns, so lists written before that period may no longer cover everything the kept packages need. Verify the list still includes the transitive dependencies of every package you keep, or the function fails at invocation with Cannot find module. No warning covers this case, since partial exclusion is indistinguishable from intended use.

Recommendation: ship in the same minor release as #13794 with a prominent release-note entry asking users to review existing negation patterns under build.esbuild before upgrading. This change adds no independent artifact churn on top of #13794: configurations without negation patterns produce byte-identical artifacts to that base, so the two changes share a single "artifacts re-upload once on the first post-upgrade deploy" story.

Related

Closes #12813
Closes #12742

Summary by CodeRabbit

• New Features

  • Added support for package.patterns when packaging esbuild artifacts.
  • Patterns can include or exclude dependencies, additional files, and directories, with ordered re-inclusion support.
  • Added documentation explaining how packaging patterns affect build artifacts.

• Bug Fixes

  • Improved packaging consistency and archive determinism.
  • Preserved symlinks and required build outputs during filtering.
  • Added clearer diagnostics for packaging patterns and missing external dependencies.