refactor(registry): isolate scanned metadata to the selected application

[yeongseon]

Context

Architecture follow-up (not a P1; no failure in the common single-app layout).

@openapi registers into a process-wide registry at import time, and scan_endpoint_metadata() still writes into that global registry. So:

azure-functions-openapi generate --app my_module:app_a

imports my_module (registering @openapi metadata from every app defined there) and then scans app_a. The effective spec is closer to "all @openapi imported from module + metadata discovered from app_a" than to "spec for app_a". For a module defining both app_a and app_b, selecting app_a can still leak app_b's decorator metadata into the output.

#324 already introduced registry injection (registry= on generate_openapi_spec / collect_spec_warnings, with _collect_* falling back to _default_registry), so the plumbing exists to finish per-app isolation.

Acceptance Checklist

• Support scan_endpoint_metadata(app, registry=...) writing discovered operations into an injected/isolated registry rather than the global one.
• Provide a path for the CLI --app module:app_x to build a spec scoped to operations belonging to the selected app.
• Tests: a module with two apps, each with @openapi handlers, yields a spec containing only the selected app's operations.
• Preserve backward compatibility for the common single-app function_app.py layout (global registry default).
• Coverage stays >= 95%.

Out of scope

• Removing the global registry entirely.
• The empty-discovery warning wording (tracked separately).

References

• PR refactor(core): decouple spec generation and registry from the Azure Functions SDK #324 (registry injection groundwork)
• src/azure_functions_openapi/spec.py (_collect_skew_warnings, _collect_discovery_warnings global fallback)

[yeongseon]

Proposed implementation plan (for approval)

Findings

• Spec layer already injectable (from refactor(core): decouple spec generation and registry from the Azure Functions SDK #324): generate_openapi_spec(registry=...), collect_spec_warnings(registry=...), and all _collect_* warning helpers honor an injected registry. No change needed there.
• Decorator writes global at import: @openapi records into the process-wide registry before any app object exists. This is intrinsic and stays (removing the global is explicitly out of scope).
• Gaps to close:
  1. bridge.scan_endpoint_metadata() and its internal helpers reference the module-global registry directly (incl. registry.lock, find_by_function_id, set, add_discovery_warning).
  2. CLI never builds/passes an isolated registry — it scans + generates against the global one.

Design decision (the crux)

An isolated registry alone is insufficient, because @openapi metadata for every app in the module is already in the global registry at import. scan_endpoint_metadata(app_a) iterates only app_a's function builders, so it is the one place that knows which handlers belong to app_a (via canonical_function_id).

Approach: seed-on-scan. When scan_endpoint_metadata(app, registry=isolated) is called with an injected registry:

• For each discovered handler on app, look up its canonical @openapi entry in the global registry by _function_id and copy it into isolated (deep copy).
• Register the endpoint-metadata / binding operations into isolated (same logic, just parametrized target registry).
• Route add_discovery_warning to isolated.

Result: isolated contains exactly (app_a's @openapi entries) + (app_a's discovered operations) → generate_openapi_spec(registry=isolated) yields an app_a-only spec. Global path unchanged (default registry=None → global), preserving the single-app function_app.py layout.

Changes

1. bridge.py: thread an optional registry: OpenAPIRegistry | None = None param through scan_endpoint_metadata and internal helpers; default None resolves to the global singleton (mirrors spec.py's _default_registry pattern). Add the seed-from-global step keyed on _function_id.
2. cli.py handle_generate: when --app module:variable is given, build a fresh OpenAPIRegistry(), pass it to scan_endpoint_metadata(...), then thread it into generate_openapi_spec(..., registry=...) and collect_spec_warnings(..., registry=...). Bare --app module (no variable) keeps global behavior for back-compat. Consider an opt-in guard if isolation changes output for edge cases.
3. registry.py: no API change expected (seeding uses existing snapshot/find_by_function_id/set). May add a small seed_from(other, function_ids) helper if it keeps bridge cleaner.

Tests

• Module defining app_a + app_b, each with @openapi handlers → generating for app_a yields only app_a operations (regression for the leak).
• Single-app layout unchanged (global default) — existing tests must stay green.
• Discovery warning lands in the isolated registry, not the global one.
• Coverage stays >= 95%.

Open questions for reviewer

1. CLI default: make isolation the default for --app module:variable, or gate behind a flag (e.g. --isolate-app) to avoid any behavior change for existing users? I lean default-on for module:variable since that path already implies "spec for this app".
2. Seed scope: seed only entries whose _function_id matches discovered handlers. Programmatic register_openapi_metadata entries (_function_id = "programmatic.*") are not tied to an app object — should those be excluded from isolated specs, or always carried over? Proposed: exclude (they aren't part of the selected app), but flag for confirmation.

Please confirm Q1/Q2 (or the overall approach) and I'll implement.

[yeongseon]

Severity update: the leak is malformed, not just extra

Reproduced on main. Module defines two apps, each with an @openapi handler; the CLI imports the module (both register globally at import) then scans only the selected app:

# twoapp.py
@app_a.route(route="a/one", methods=["GET"])   @openapi(...) def a_one(req): ...
@app_b.route(route="b/one", methods=["POST"])  @openapi(...) def b_one(req): ...

scan_endpoint_metadata(app_a, route_prefix="/api"); generate_openapi_spec(...)
# path: /api/a/one methods: ['get']
# path: /api/b_one methods: ['get']    <-- leaked AND malformed

b_one	real runtime	generated spec
path	/api/b/one	/api/b_one (function name)
method	POST	GET (default)

Because app_b was never scanned, its leaked entry never received route/method reconciliation — the @openapi-registered route=None, method=None fell back to the function name and the GET default. So the spec documents a non-existent endpoint (GET /api/b_one), which is materially worse than "extra operations". It also triggers merely by importing any module that has @openapi handlers for a second app — not only in explicit multi-app modules.

Recommendation

• Re-examine priority given the "fabricated endpoint" impact.
• If full isolation is too heavy near-term, a cheap interim guard: emit a structured warning for any spec entry that was registered but never reconciled during scan (method is None after scan), so CI (--fail-on-warnings) catches the malformed leak.

(Full isolation plan for this issue remains posted above; still blocked on Q1/Q2.)