Declared cross-repo links file for contracts static extraction can't see (example: stitched GraphQL + Lighthouse)

[jmverges]

In #1568 you asked for a small public example of a missing cross-project relationship before committing to a design. That thread is about framework forks; this is the service-oriented case, following #561 (closed with an invitation to continue in Discussions) and the storage direction in #576 and #932.

Setup. A polyrepo: several Laravel services exposing GraphQL with Lighthouse, a schema-stitching gateway in front, Vue clients. Minimal example, three folders indexed as three projects: https://github.com/jmverges/cbm-stitched-graphql-example

The relationship. web/src/graphql/recentOrders.js reads Order.total, Order.buyer and Customer.name. In the service they are served by Order::getTotalCentsAttribute() (@rename(attribute: "total_cents")), Order::customer() (@belongsTo) and Customer::getDisplayNameAttribute(). "Who reads Order.total, and which PHP serves it?" needs client file -> schema field -> PHP method, across repos, through a gateway that hides which service answers.

What 0.11.0 extracts (exact commands in the README):

• acme-api: the schema becomes Class/Field nodes and the PHP methods are there, but there is no edge from a field to the method that serves it, and no Route/HANDLES.
• acme-web: no GRAPHQL_CALLS. Same result after padding the project past the 50-file parallel threshold: the emitter fires on a resolved callee whose qualified name contains a GraphQL library token (a local gql() does produce an edge), not on gql imported from graphql-tag.
• Cross-repo pass: cross_graphql_calls: 0.
• Even with a client edge, it would point at __graphql__<operation text>, and I could not find anything that emits a server-side GraphQL Route + HANDLES, so for GraphQL the pass has nothing to pair today.

Why not a pass for this. The mapping is framework semantics: Lighthouse directives, Eloquent accessor naming, schema stitching. A parser per framework is the combinatorial problem you described in #561. We already compute these links with a small tool of our own and write them into the per-project databases after each index. That works, but as you explained in #576 the next index run erases them, so we redo it after every reindex.

Proposal: a declared links file read during indexing. An opt-in file in the repo, e.g. .cbmlinks.json (sketch in the example's proposal/links.json), with entries {route, role: handler|caller, file, symbol}. A pipeline pass turns them into the same Route + HANDLES / *_CALLS edges the indexer already builds (including the operation-style property the cross-repo pass reads), so the existing pass pairs them by Route qualified name and they survive a reindex by construction. The route key is whatever both sides declare; for GraphQL we use __graphql__Type.field, a different granularity from the operation-text key the extractor uses, so declared keys would stay separate from extracted ones. Along the lines of #932: paths must stay inside the project, unresolved symbols are reported, and staleness is detectable (the file's hash recorded with the index generation).

This is different from #292 (teaching the extractor more call patterns) and from the runtime trace model from #612 (observations kept out of the static graph): it is for links that are known statically but not derivable from source alone.

Does this shape fit what you had in mind? If so, I'm happy to prototype it within the contribution guidelines, or to adapt the format to whatever you prefer.

Drafted with AI assistance (Claude); I reviewed it and ran the example myself.

[DeusData]

Thank you for the concrete public example and the careful distinction between declared static relationships, extracted edges, and runtime traces. That makes the proposal much easier to evaluate. The declared-link format and how it coexists with extracted GraphQL keys still need a maintainer design decision; this reply is not approval of a new format or a request to build the prototype. The example already supplies useful detail for that decision.