doc: add bfcli matcher hook compatibility table

[LiuHuaize]

Summary

• add a generated matcher-to-hook compatibility section to doc/usage/bfcli.rst
• derive the compatibility matrix from src/libbpfilter/matcher.c so the docs follow unsupported_hooks
• wire the generator into doc/CMakeLists.txt and commit the generated include

Fixes #481

Testing

• python3 -m py_compile doc/generate_matcher_hook_compat.py
• python3 doc/generate_matcher_hook_compat.py --matcher-c src/libbpfilter/matcher.c --matcher-h src/libbpfilter/include/bpfilter/matcher.h --hook-h src/libbpfilter/include/bpfilter/hook.h --output doc/usage/_generated/bfcli_matcher_hook_compatibility.rst --check

Notes

• Full Sphinx/Doxygen doc build was not run locally because this environment does not have cmake, ninja, sphinx-build, or doxygen installed.

[github-actions]

Claude review of PR #503 (f574d46)

Must fix

• Generated RST committed alongside auto-regeneration — doc/usage/_generated/bfcli_matcher_hook_compatibility.rst:1 — The file is both committed and auto-regenerated by add_custom_command, producing git-dirty state on every doc build. Pick one approach: either don't commit and generate into the build tree, or commit and replace auto-regeneration with a CI staleness check.

Suggestions

• Table readability for long hook lists — doc/generate_matcher_hook_compat.py:155 — Matchers supporting all 14 hooks produce 400+ character cells. Consider a grid matrix, showing only unsupported hooks, or a bulleted sub-list.
• Wire --check mode into CI — doc/generate_matcher_hook_compat.py:240 — The script supports --check for staleness detection but nothing invokes it.
• Brace-depth parser fragile with comments/strings — doc/generate_matcher_hook_compat.py:88 — _extract_initializer_blocks does character-level brace counting that would break on braces inside comments or string literals. Document this limitation.
• _read_hook_macros should validate results — doc/generate_matcher_hook_compat.py:72 — Silently returns empty dict if macros move out of matcher.c, producing an incorrect table with no warning.
• _expand_hooks lacks cycle detection — doc/generate_matcher_hook_compat.py:176 — Recursive macro expansion with no seen set guard; a circular macro reference would cause a RecursionError with an unhelpful traceback.
• --check crashes on missing output file — doc/generate_matcher_hook_compat.py:300 — _read(args.output) raises an unhandled FileNotFoundError when the output file does not exist; should print a clear message and return 1.
• Staleness check runs late in CI — .github/workflows/ci.yaml:212 — The check is in the doc job which depends on test and benchmark, delaying feedback when the generated table is stale.
• Silent failure for non-BF_FLAGS unsupported_hooks — doc/generate_matcher_hook_compat.py:157 — _extract_unsupported_hooks only matches .unsupported_hooks = BF_FLAGS(...). If a future matcher uses a different expression, the function silently returns [] and the table incorrectly shows "None". Add a fallback warning when .unsupported_hooks is present but doesn't match BF_FLAGS(...).
• Matchers missing from _bf_matcher_metas shown as compatible — doc/generate_matcher_hook_compat.py:251 — Matchers present in bf_matcher_type enum and _bf_matcher_type_strs but absent from _bf_matcher_metas silently get an empty unsupported list, producing incorrect "None" rows. Consider warning when matcher_order entries are in matcher_names but absent from matcher_blocks.

Nits

• Section placement interrupts matcher flow — doc/usage/bfcli.rst:524 — "Hook Compatibility" sits between generic syntax and "Meta", breaking the reading flow. Consider placing after all per-protocol sections.
• Python lines exceed 80 chars — doc/generate_matcher_hook_compat.py — Several lines exceed the project's 80-character convention.
• Module docstring mentions inverse but table shows unsupported — doc/generate_matcher_hook_compat.py:8 — Docstring says "supported hooks are computed from the inverse" but the table renders unsupported hooks directly.
• Unrelated blank line removal — doc/usage/bfcli.rst — First hunk removes a blank line between sections, unrelated to the feature addition.
• 8-core-ubuntu for lightweight CI job — .github/workflows/ci.yaml:28 — The check-generated-docs job runs a simple Python script but uses an expensive 8-core self-hosted runner. A standard ubuntu-latest would suffice.
• Missing copyright header — doc/generate_matcher_hook_compat.py:2 — The script has the SPDX license identifier but is missing the standard Copyright (c) ... Meta Platforms, Inc. line found in other project files.

Workflow run

[yaakov-stein]

Hi, thanks for working on this and welcome to the repo! This will be a really helpful addition! I have a few high-level comments/questions before getting into the details:

1. I'm thinking that the proper approach here is to add the code that generates the file and then generate the file as a part of make doc as opposed to having the generated code live in the repo. This is similar to how it's already done for other generated code in the repo and should simplify things (don't need to check the diff at CI time).

2. As opposed to writing a parser and manually parsing the relevant source files (seems prone to error), we should be able to use bf_matcher_get_meta (public) and we can rely on the exact same code that is used directly in the repo. This should make the generation simpler and less fragile.

Let me know what you think of those points!

[qdeslandes]

Sending the PR back to the contributor for them to notice @yaakov-stein's comment.

[qdeslandes]

@LiuHuaize it's been 2 weeks, do you intent to update this PR? :)