Filters

Cut 187,000 modules down to the ones you care about.

A release contains around 187,000 modules. Roughly 11% of them have anything to do with WhatsApp’s protocol. The rest are buttons, icons, analytics, and code belonging to Facebook and Instagram, which share the same bundle.

Without a filter, comparing two releases produces tens of thousands of entries. Filters are what make results readable.

Built-in filters

Filter	What it keeps	Good for
default	The protocol surface, about 11%	Comparing releases
all	Everything	Checking whether a filter hid your answer
protocol	Only confirmed protocol modules	Short, high-signal results
schemas	.pb, .proto and .graphql	New data fields and server queries
wam	Analytics events and enums	The earliest sign of an unreleased feature

cellar filter list

The difference is not subtle. Searching for Passkey without a filter returns 193 modules, mostly Facebook’s business login screens. With --filter protocol it returns 12, which are the entire feature.

default deliberately skips .pb and .graphql files. They are generated, and a text comparison of them is noise. If you are hunting for a new protobuf field, use --filter schemas, or you will conclude that nothing changed.

Check before you trust

cellar filter test default --bundle latest

filter `default` on whatsapp-1044822804: keeps 18761 of 172040 modules (10.9%)
  dropped by dependsOnExcluded: 25095
  dropped by exclude: 58397
  dropped by hardExclude: 69787

kept, for example:
  WAWebSendMsgStanza
  WASmaxInIqCallReceiptResponse
  …

dropped, for example:
  AACDestinationGuidanceCardContainer.react   {"pattern":"\\.react$","reason":"hardExclude"}
  AAAMediaPickerVisibilityAction              {"module":"Laminar","reason":"dependsOn"}

Every dropped module reports why it was dropped, so an unexpectedly empty result is explainable rather than mysterious.

Making your own

Built-in filters are read only. Copy one and edit the copy.

cellar filter fork protocol newsletters
cellar filter show newsletters > newsletters.json
# edit, then:
cellar filter set newsletters --from newsletters.json

A filter is JSON, and a partial document is treated as an edit, so you only send the fields you want to change.

{
  "description": "Newsletter and channel surface only",
  "include": ["^WAWebNewsletter", "Newsletter"],
  "defaultVerdict": "drop"
}

echo '{"include":["Newsletter"],"defaultVerdict":"drop"}' | cellar filter set mine --from -

Deleting a filter that shadows a built-in restores the built-in.

cellar filter rm newsletters

How matching works

Four lists of regular expressions, checked in order. The first match wins.

1. hardExclude

   Dropped no matter what, even if the include list also matches. This exists for file types handled better by other means, like .pb schemas.

2. include

   Kept, overriding the exclude list. WAWebSendMessageAction matches the generic “ends in Action” exclusion, but it is exactly what you want, so the include list rescues it.

3. exclude

   Dropped.

4. defaultVerdict

   What happens to anything no list matched. keep makes a deny list, which is what default is. drop makes an allow list, which is what protocol is.

With excludeDependentsOfExcluded, anything that depends on a dropped module is also dropped, following the chain as far as it goes. Modules matched by include are exempt, since you asked for them explicitly.

Two more lists tune the comparison rather than the selection:

• noiseDeps lists dependencies whose coming and going says nothing, so they are left out of reported dependency changes.
• noiseCode lists patterns for compiler output, so a module whose entire change is build noise gets counted as noise instead of reported.

The default filter’s rules come from ProtoCocktail’s wa-diff-analyzer, built up by hand against real bundles over a long period. It encodes a lot of accumulated knowledge about which module name means what.