docs: emit a JSON API manifest from the Doxygen XML (EQL v3)

[coderdan]

Adds a structured eql-manifest.json to the docs pipeline, alongside the existing API.md. Targets eql_v3.

Why

The docs V2 EQL reference is hand-written and drifts from the shipped surface (fabricated function names, stale payload, wrong domain names have all slipped in). This exposes the source of truth as machine-readable data so the docs can be generated and verified against it (docs generation, drift-linting, agents).

What it does

tasks/docs/generate/xml-to-json.py + docs:generate:json builds docs/api/json/eql-manifest.json from two authoritative sources:

1. Functions/operators — from the Doxygen XML, reusing xml-to-markdown.py's process_function (same XML, same SQL-via-Doxygen quirk handling), so the manifest and the Markdown reference can't diverge.

2. Encrypted domains / variant matrix — the core of the v3 surface. Read straight from the Rust catalog via eql-codegen dump-catalog (which already serializes eql_domains::CATALOG to JSON) — not by parsing the generated SQL. So it carries authoritative type tokens (integer/bigint/boolean, confirming the docs' int4/int8/bool are drift) and the exact SQL operators each domain supports (supportedOperators), which is more accurate than deriving from CHECK keys (e.g. _ord correctly reports =/<> too, since ORE collapses to equality). json.sh emits eql-catalog.json and feeds it to the converter — no Rust changes needed; dump-catalog already exists.

Packaged into eql-docs-<tag>.{zip,tar.gz} and generated in release-eql.yml. Additive — the Markdown path is unchanged. test_xml_to_json.py covers both parts.

Sample output (verified against the real v3 source)

{
  "name": "eql", "version": "3.0.0", "generatedFrom": "doxygen-xml + catalog",
  "counts": { "functions": 984, "domains": 48 },
  "functions": [ { "name": "hmac_256", "signature": "hmac_256(jsonb)", "returns": {"type":"text"} } ],
  "domains": [
    { "name": "eql_v3.text_search", "type": "text", "variant": "search", "base": "jsonb",
      "capabilities": ["equality","order","match"],
      "supportedOperators": ["=","<>","<","<=",">",">=","@>","<@"] },
    { "name": "eql_v3.integer_ord", "type": "integer", "variant": "ord",
      "capabilities": ["equality","order"], "supportedOperators": ["=","<>","<","<=",">",">="] },
    { "name": "eql_v3.boolean", "type": "boolean", "variant": "", "capabilities": ["storage"], "supportedOperators": [] }
  ]
}

Follow-ups (not in this PR)

• Hand-written jsonb domains — json / jsonb_entry / jsonb_query live in hand-written SQL (not the catalog), so they're not in the 48 catalog domains. A small addition (their own source) can fold them in.
• The catalog dump could also expose per-domain terms + extractor functions (Term::json_key/extractor/ctor) — a few lines in dump.rs — enriching the manifest further.
• Payload schemas — the versioned eql-payload-*.schema.json could be referenced from the manifest so the payload reference is generated too.

Consumed by the docs side (generator + drift-lint) — cipherstash/docs#46.

https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b0e33b9b-5879-4a93-b03e-be2563e581d9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/eql-manifest-generator

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}