Compat Flag

Look up compatibility flag: $ARGUMENTS

If no argument is provided (empty or blank), list all compatibility flags:

1. Use the compat-date-at tool (no arguments) to get the full list of flags with their enable dates, categories, and annotations. This is faster and more accurate than manually reading the capnp file.

2. For each flag, also extract a one-line summary from the comment in src/workerd/io/compatibility-date.capnp.

3. Output a summary table grouped by category (streams, nodejs, containers, general, etc.):

   Flag	Enable date	Description
   flag_name	2025-01-15	Brief description

   Include the total count of compatibility flags.

If an argument is provided, look up that specific flag:

1. Use the compat-date-at tool with flag: "<argument>" to get the flag's metadata (enable/disable names, enable date, annotations). Then read the capnp source for the comment.

2. Extract flag metadata from the tool output and capnp definition:

   • Field name and number
   • $compatEnableFlag name
   • $compatDisableFlag name (if present)
   • $compatEnableDate (if set)
   • Whether it has $experimental annotation
   • The comment block describing the flag

3. Find C++ usage sites. Search for the getter (e.g., getTextDecoderReplaceSurrogates()) across the codebase:

   Copy

   grep -rn "getTextDecoderReplaceSurrogates\|text_decoder_replace_surrogates" src/
   

4. Find tests. Search for the snake_case flag name in .wd-test and test .js files:

   Copy

   grep -rn "text_decoder_replace_surrogates" src/ --include='*.wd-test' --include='*-test.js' --include='*-test.ts'
   

5. Output:

   • Flag: enable name / disable name
   • Enable date: date or "not set (must be explicitly enabled)"
   • Description: from the capnp comment
   • Usage sites: file:line list of where the flag is checked in C++
   • Tests: file:line list of tests that exercise this flag
   • Annotations: experimental, neededByFl, impliedByAfterDate, etc.
   • If the flag is not found, suggest checking for typos and list flags with similar names