P0: Preserve route assembly and qualified dependency provenance

[shaggitza]

Priority

P0 — route identity and dependency propagation correctness.

Problem

Endpoint materialization discards the provenance that assembled a public route, and dependency analysis does not consistently preserve FastAPI dependency identity.

Evidence:

• src/fastapi_endpoint_detector/parser/secure_ast_extractor.py:394-453,2391-2579
• src/fastapi_endpoint_detector/models/endpoint.py:135-226
• src/fastapi_endpoint_detector/parser/fastapi_extractor.py:169-208
• src/fastapi_endpoint_detector/analyzer/mypy_analyzer.py:719-797,799-963,1092-1108

Reproduced failures:

• Editing include_router(..., prefix='/old') can change every public route without a changed handler seed.
• Multiline route decorators, import retargets, re-exports, class bases, module globals, and __all__ changes were often missed.
• An app-level Depends(app_dep) was visible as a short runtime dependency name, but changing its transitive helper produced no endpoint candidate and was orphaned.
• Router/include-level dependencies, callable instances, dependency factories, partials, and duplicate short names cannot be represented safely by list[str].

Required design

Add immutable, side-qualified registration provenance to native endpoints:

• route decorator or imperative registration occurrence;
• include/mount edge chain and prefix expressions;
• selected app/factory/bootstrap root;
• app/router/include/route dependency expressions;
• baseline/target side and endpoint lifecycle.

Add an AST change-to-owner pass for complete decorator/signature spans, assignment RHS spans, import bindings, exports, class bases/decorators, and route assembly edges. Store qualified callable dependency evidence; runtime mode should traverse FastAPI's recursive dependant graph.

Acceptance criteria

• Prefix, mount, include, registration-order, factory-return, and bootstrap changes affect exactly their descendant endpoints.
• App, router, include, route, Security, Annotated, nested, duplicate-name, override, factory, partial, and callable-instance dependencies have tests.
• Multiline route/decorator/global/base/import/export changes receive structural ownership evidence.
• Ambiguous or dynamic assembly/dependency expressions remain LOW/conditional, never guessed.
• Report output distinguishes removed/renamed endpoints from runnable target endpoints.

Related: #104, #107.

[shaggitza]

Phase 1 merged in #299 (a37edb1). #277 remains open for secure-AST route assembly/source ownership and lifecycle work.

Completed the runtime dependency-identity foundation:

• added optional frozen schema-v1 EndpointDependencyGraph evidence while preserving legacy Endpoint.dependencies unchanged;
• records ordered declared FastAPI dependency occurrences with physical callable/source identity, assembly/parameter/nested scope, Security scopes, cache semantics, nesting, duplicate occurrences, partial/callable structure, and graph-local limitations;
• distinguishes not-collected, established-empty, conditional, and unavailable graphs without weakening route discovery;
• recursively traverses effective Dependant graphs with deterministic depth/node/work/metadata caps, cycle handling, malformed-shape isolation, and minimum/current FastAPI compatibility;
• keeps wrappers, partials, callable instances, dynamic shapes, and visible overrides conservative rather than guessing effective providers;
• seeds mypy only from exact project-local function/bound-method occurrences whose physical runtime source overlaps the unique typed definition;
• includes the complete graph in mypy cache identity, preventing stale no-graph/runtime-graph reuse;
• exposes dependency evidence in JSON/YAML, bumps public inventory/report schema to 3 and private runtime protocol to 2, and documents the additive contract.

This closes the concrete app/include-level propagation false negative: POST /items is now correctly affected through check_scope -> get_current_user -> decode_token.

Validation:

• terminal independent review returned PASS with no remaining blocker/high finding;
• 70 resource-isolated repository test files passed locally; the two known host-sensitive broker files were deferred to CI;
• CI run 30475508302 passed Ruff, strict mypy, FastAPI 0.100 compatibility, Python 3.10/3.11/3.12 tests and coverage, and package build.

Remaining #277 phases include secure-AST dependency-expression provenance, native route/include/mount/root assembly occurrences, AST structural change ownership, dependency overrides/effective-provider evidence, and baseline/target endpoint lifecycle reconciliation.

[shaggitza]

Phase 2 merged in PR #300 (ed4737e): immutable side-qualified native root/object/registration/include/mount provenance, occurrence-sensitive endpoint identity, structural target/baseline ownership, schema-v4 JSON/YAML output, and strict provenance invariants. Independent terminal review and full Python 3.10–3.12 CI passed. #277 remains open for broader lifecycle reconciliation and later provenance phases.