#1154

docs(reference): generate checked blessed_core compatibility surface inventory

Openiamgpwants to merge intofrom

Builds the checked inventory that ADR 0053 exit criterion 10 asks for (decision 2 compatibility surface).

What changed

  • scripts/generate_reference_docs.py writes docs/reference/generated/compatibility-surface.json alongside the existing references. It reuses the CLI and HTTP builders' data rather than parsing Click or FastAPI again.
  • The inventory covers the blessed_core profile only:
    • CLI command paths and parameters (help text dropped) for commands owned by blessed_core packages: 135
    • /api/v1 methods and paths plus GET /health: 166
    • phlo.__all__, excluding underscore-prefixed names such as __version__: 65
    • entry-point groups from PLUGIN_FAMILIES plus phlo.plugins.observatory and phlo.project_templates: 15 groups, 46 entry points declared by blessed_core distributions
    • hook event classes in phlo.hooks.events: 11, plus envelope version 1.0
    • release_set.schemas: configuration 1, database 5
  • cli.json gains a package field per command: the distribution whose module defines the command callback. This is what lets the inventory drop commands from preview and supported_optional packages (mcp, sling, transform, alerts, and so on).
  • The support matrix page has a short section explaining the file, how to regenerate it, and that a diff is an ADR 0053 decision 4 review item.

How it is checked

make docs-reference-check (part of make check and the CI Python lane step "Check generated reference documentation") regenerates and fails when the file is stale. I checked this by temporarily adding a name to phlo.__all__: the check failed and listed only compatibility-surface.json.

Verification

  • make check: all lanes passed except a C901 complexity finding in cli_docs, since fixed. ruff check, the C901 check, generate_reference_docs.py --check and tests/tooling/test_generate_reference_docs.py (15 passed) re-run green.
  • make docs-build, codespell, markdown links, validate_support_manifest.py.

Notes

  • Entry points come from installed distribution metadata, the same environment that produces cli.json and http-api.json.
  • Hook event types are the event classes. Event type strings are open-ended, so the classes are listed instead.
  • Parallel removals of the deprecated 0.19.0 names will shrink python_api. Whichever PR lands second regenerates the file.

Activity

313
coldtea-pr-lens[bot]3h ago

NOTE

The title starts with docs(reference):, so PR Lens left this pull request undrawn. Comment @pr-lens draw to draw it

github.comment.notice: false in .github/pr-lens.yml turns this note off

phlo-agent[bot]3h ago

No blocking findings. The generated inventory matches ADR 0053 exit criterion 10, and the committed data is internally consistent with its sources.

Checked

  • Full diff at 07e86df: the new builder, the package field added to cli.json, the committed compatibility-surface.json, the support-matrix section, and the new test.
  • Counts agree with the file's contents: 135 CLI paths, 166 HTTP routes, 65 phlo.__all__ names, 15 entry-point groups, 46 entry points, 11 hook event types, envelope 1.0, and configuration=1/database=5 taken from registry/support/v1.json.
  • CLI ownership is derived from the callback's top-level module via packages_distributions(), with the editable phlo root named explicitly because that install has no top_level.txt. Commands from phlo-airbyte, phlo-alerting, phlo-clickhouse, phlo-mcp, phlo-sling, and phlo-transform drop out by package, and the test asserts those exclusions plus the /api/v1 + /health HTTP filter.
  • Entry points are limited to the 15 groups decision 2 names; excluding phlo.plugins.dagster is deliberate and asserted.
  • Wiring is accurate: make docs-reference-check is part of make check (Makefile:15) and the CI quality job (ci.yml:210). At this SHA the quality job's "Check generated reference documentation", Ruff (including C901), ty, the docs build, and the core test shards' test steps all passed, so the committed file is fresh in CI's environment.

Non-blocking wording note — docs/reference/support-matrix.md:9-13 says the file lists "the ADR 0053 decision 2 surface" and that a diff to it should be reviewed as a covered-surface change. The file is the exit-criterion-10 subset: decision 2 also covers HTTP request/response schemas, status codes, error envelope, pagination and authorisation actions; the CLI JSON envelope and exit status; phlo.plugins.base, capability specs and service.yaml; project layout/configuration shape; and the support manifest shape. None of those are recorded here, so a green diff could be read as full decision-2 coverage. Suggest describing it as the exit-criterion-10 inventory of those surfaces, leaving the rest to their decision-2 references.

Remaining validation — The API package tests and the workspace coverage shards were still running when I checked; they exercise this change only through the shared tooling suite, whose test step passed in the core shards.