Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

19.9 KB
Raw Blame

Workspace contract matching reference

How a workspace names, reads and matches cross-repo contracts, for when you need to know why a link did or did not form. Start from Extraction Diagnostics, which names the reason for each unmatched consumer. The support matrix of frameworks and libraries is in API Contract Extraction. The pipeline behind it, and how to add a dialect or a service-name source, is in architecture/workspace.md.

How a contract and a link were made

Every contract carries an origin and every link a strategy, each from a closed vocabulary with exactly one confidence per value, the rule GRAPH.md applies to call edges. A link's confidence is its weaker end's times its strategy's factor, and its match_type follows from the strategy.

Confidence Contract origin What was established
0.90 idl An OpenAPI or proto document declares the operation
0.90 package_export A published package exports the symbol another repo imports
0.85 route_registration A framework registers the route, handler, server or hub in code
0.85 typed_client The parsed index types the receiver as an HTTP client
0.85 ddl SQL DDL or a migration creates or alters the table
0.85 explicit_table An ORM model names its table explicitly
0.75 client_call A known client, broker, socket or query-builder call names the destination
0.75 instance_base A call on a client instance whose base URL the file reads
0.70 dataflow The destination was traced across statements to the call
0.70 sql_string A table named inside SQL text in a string
0.65 name_heuristic Only a callee or receiver name says it is a client call
0.60 name_convention A naming convention: an ORM's default table name, a unique short type name
Factor Link strategy match_type What joined the two ends
1.0 exact_id exact Both name the same normalized id, method and service wildcards included
1.0 pattern_matched exact The consumer's subscription pattern matches the provider's name
1.0 binding_routed exact A queue bound to the provider's exchange, with a routing key it receives
1.0 shared_table exact A service that only models a table, to the one service defining its schema
1.0 service_mapped exact The consumer's host or base token maps to the providing service
1.0 unique_path exact The consumer's base is unread and one service serves the path
0.6 ambiguous_path candidate The base is unread and several services of one repo serve the path; linked to each
0.6 prefix_stripped candidate Matched only after stripping mount, version or base prefixes
0.5 host_only candidate The host names a workspace service, but no route there serves the path; a service-level edge
1.0 gateway_route exact A gateway's config forwards the path to the service: the gateway's own edge, and a call through it linked on the forwarded path
1.0 manual manual Declared in the workspace config

A new dialect picks an existing origin, not a number. A system-graph edge carries the strategy of the link that gave it its confidence, and manifest for a package dependency.

Sockets

An endpoint is identified by its path (socket::/hubs/game); a message by its event within a scope, socket::<scope>#<event>, where the scope is a socket.io namespace (/ unless the file names one) or a broadcast channel. Channels keep the wire prefix Pusher gives them (private-orders.{param}), and Echo's event names are read the way Echo formats them, so .listen('OrderShipped') meets a Laravel event class App\Events\OrderShipped and .listen('.order.shipped') meets broadcastAs() returning order.shipped. The emitting side is the provider. socket.io, amqplib's publish/consume, BullMQ, Redis and NestJS calls are read only in a file importing the library, since emit, on, publish and subscribe are common method names.

Topics and queues

A topic, queue or exchange name is read the way a URL is: a literal, or a name the same file assigns exactly once to a literal (Python, Go, Java, PHP class constants, and JS/TS const including object and enum members such as QUEUES.ticketSold), is resolved; a name built at runtime is skipped, not guessed. An SQS queue URL is named by its last path segment and an SNS topic ARN by its last field. A subscription by pattern (NATS orders.* / orders.>, Redis psubscribe, Kafka topicPattern) links to every publisher whose name it matches. A Laravel job dispatched without a queue runs on the queue its class declares (public $queue, $this->onQueue(), viaQueue()), found by the class's fully qualified name; one left on the connection's default queue is not recorded, since every app has one. A Laravel job class links only to a Laravel dispatch of that class: a raw publish (amqplib sendToQueue) on a queue of the same name is not the job envelope its worker reads. RabbitMQ publishers name an exchange and a routing key while consumers name a queue, so a queue binding found anywhere in the workspace connects the two: each consumer of the bound queue links to the exchange's publishers whose routing key the binding pattern accepts (* and # follow topic-exchange rules; an empty key or pattern matches everything, while a key the source does not settle matches nothing). Such a link carries the exchange as its contract_id and the queue as consumer_contract_id. When no consumer of the bound queue is found, the binding site itself is linked. A publish to the default exchange (publish('', 'jobs')) is a publish to the queue jobs.

Data contracts

Data/DB contracts use the id scheme data::<table> and render as a db edge in the system graph. An ORM model with no explicit table name takes its library's default: the Prisma model name, the TypeORM class name in snake case, the Sequelize model name pluralized, the Eloquent class name in snake case and plural. A service that only models a table (an ORM class, no migration) is linked to the service whose migration or DDL defines that table's schema, when exactly one service defines it; two services that each migrate a table of one name are read as separate databases and not linked. A table on an embedded database (SQLite) links only within its own repo, on either side: a reader or declaration in a file that opens one, and every table in a repo whose code names an embedded engine and no server database (Postgres, MySQL, SQL Server), since that file is the repo's own database. The consumer side (SQL string matching) is heuristic and lower-confidence than the ORM-based providers; unlike HTTP and gRPC, there is no field-level breaking-change diffing for data contracts, only table/route-level removal.

HTTP routes and calls

HTTP routes are matched on their full path: a router mount prefix (APIRouter(prefix=...), include_router(prefix=...), Express app.use('/x', router), Go route groups, Laravel Route::prefix(...)->group(...) and Route::group(['prefix' => ...]), Fastify register(plugin, {prefix}), Koa new Router({prefix}) and nested router.use(), hapi register({plugin, routes: {prefix}})) is stitched onto each handler path before matching. A Fastify, Koa or hapi prefix that does not resolve to a string, or a plugin mounted at two different prefixes, leaves those routes out rather than at a guessed path. Laravel's routes/api.php is served under /api unless bootstrap/app.php (apiPrefix) or a route provider says otherwise, and Route::resource / apiResource expand into the routes they register. A NestJS route is served at the app's setGlobalPrefix (unless its exclude list names the route), then its URI version (enableVersioning, @Version), then the @Controller prefix. A call through an axios, ky, got or ofetch instance is read with the instance's baseURL / prefixUrl, also when another file imports the instance. An Angular HttpClient call is read on any receiver typed or injected as HttpClient, with environment.apiUrl folded from src/environments/ and class fields built on it; a base an interceptor prepends is not read. A Node request call reads a URL or an options object held in a local (var options = { uri, method }), and a base from a module.exports = { ... } module it requires (endpoints.cartsUrl). A C# HttpClient call takes the BaseAddress its typed (AddHttpClient<T>), named (AddHttpClient("name") with CreateClient("name")) or Refit (AddRefitClient<T>, RestService.For<T>) registration sets in the same repo; a type registered twice with different or unreadable bases takes none. A call to a method whose body sends its string parameter through HttpClient is read with the URL that body builds. A client call whose base URL is an unresolved placeholder (fetch(\${API_BASE}/users`)) matches on the host-relative path; the link is **exact** when exactly one workspace service provides that path (unique_path) and a lower-confidence **candidate** when several services of one repo serve it (ambiguous_path). A call whose route two or more repos serve, with no host or base naming one, links to none of them and is reported as ambiguous_provider. A generic operational path (/health, /healthz, /ready, /metrics, /status, /version, /actuator/info`, the root) names no service, so it links only to the repo its host or base resolves to or, with neither, to a server in the caller's own repo; it never links to another repo by path alone.

Service names

A consumer that names its target (http://catalogue:8080/..., ${CATALOGUE_URL}/...) is resolved to a repo in this order: a contracts.service_bases entry, a repo alias (also as the leading label of <name>.svc.cluster.local), then the service-name map the workspace reads from its own config. A host the map places links with strategy service_mapped; when no route in that repo serves the path, the call becomes a host_only service-level edge in the system graph (kept in service_links, apart from route links). The consumer's meta records target_via (the source) and target_evidence (the file).

Source Files read Name Repo
aspire_apphost AppHost.cs, Program.cs holding DistributedApplication.CreateBuilder AddProject("catalog-api", "../Catalog.API"), or AddProject<Projects.X>(...) through the AppHost's <ProjectReference> The project's directory
compose docker-compose*.yml, compose*.yml Service name, container_name, hostname; environment keys whose value is an address. ${VAR-default} and ${VAR:-default} read as the default build context (or its Dockerfile's directory), else an image basename equal to a repo alias. A missing or empty context (an uninitialised submodule) counts as no build
k8s_service *.yaml under k8s/, deploy/, manifests/, ... kind: Service metadata.name A selector or label value equal to a repo alias, else the manifest's repo when it declares no other Service
spring_application_name application / bootstrap .yml or .properties spring.application.name The module the file sits in
spring_base_path .yml, .yaml, .properties under resources/, config/, configs/ or shared/ server.servlet.context-path, server.context-path, spring.webflux.base-path: a base path, not a name A module's own src/main/resources/application or bootstrap file (not a profile file): that module. A config server's <app>.yml: the service named <app>
spring_gateway application / bootstrap in a module's resources, or a config-server file named *gateway*, *zuul*, *proxy*, *edge* (.yml or .properties) holding routes Spring Cloud Gateway routes[] (lb://name, http://host) and Zuul zuul.routes A gateway route (below)
dockerfile_env Dockerfile, Dockerfile.*, *.Dockerfile holding ENV ENV keys whose value is an address (CATALOGUE_HOST=catalogue) The host the value names
env_file .env, .env.*, *.env (what a compose env_file: names) Keys whose value is an address; no other value is kept The host the value names
nginx *.conf, *.conf.template, *.conf.tmpl holding proxy_pass Prefix location blocks with proxy_pass to a host, an upstream of one host, or an envsubst ${X_HOST} in a template A gateway route (below)
ocelot ocelot*.json, configuration.json holding UpstreamPathTemplate Ocelot Routes (or ReRoutes): ServiceName, or the one host in DownstreamHostAndPorts A gateway route (below)
yarp appsettings*.json, yarp*.json holding ReverseProxy YARP Routes and the one host their cluster's Destinations name A gateway route (below)
yarp_forwarder Program.cs, Startup.cs holding MapForwarder The destination host of MapForwarder(pattern, destination[, template]) A gateway route (below)

A base path prefixes every Spring route of its module before matching, so @PostMapping("/users") under context-path: /uaa is POST /uaa/users. A module given two different base paths gets none.

Each repo is walked once per update for these file names; test, example and build-output directories are skipped, and so is any file the code-origin classifier calls test, docs or example, vendored or generated (a compose file under docs/, demo/ or e2e-tests/). Files at the workspace root are read too. A name two files place in different repos is left unmapped rather than guessed. To override or fill a gap, add the host or base token to service_bases, which always wins.

A gateway source states routes rather than names: a path prefix the gateway forwards to a service, and the path it forwards (Spring StripPrefix, PrefixPath and a RewritePath=/x/?(?<s>.*), /y/${s}; Zuul stripPrefix). An nginx proxy_pass with a path replaces the location prefix with that path; one without passes the request path unchanged. The nginx gateway is the repo holding the file. The gateway is the repo holding an application file in its module's own resources, or for a config server's gateway.yml the app its name spells. Each route is a gateway_route edge from the gateway to the service. A route whose forwarded path or target is not read (a Host or Method predicate, SetPath, a service outside the workspace, a prefix sent two ways) rewrites no call but keeps a shorter prefix from claiming the paths under it. A call that reaches the gateway (its host names the gateway, or a relative call from the gateway's own pages) is rewritten by the longest matching prefix and linked to the route's service on the forwarded path; when no route there serves it, it becomes a host_only edge to that service. Ocelot, YARP PathPattern and MapForwarder templates rewrite the prefix when both templates end in the same variables (/catalog-api/{everything} to /{everything}); any other template is a blocker. Blockers alone at one prefix each keep their edge.

Contracts over REST

GET /api/workspace/contracts lists contracts and links, filterable by contract_type, repo and role. Each contract carries its line, its ingestion symbol id and the extractor's meta; each link carries both symbol ids and both service boundaries. The request/response schema is not on the list, because it runs to full inline type declarations and only one is ever needed at a time: fetch it with GET /api/workspace/contracts/detail?repo=<alias>&file=<path>&id=<contract-id>, which returns that one contract with its schema, its links, and its unmatched reason. All three parameters are required, since a contract id alone is not unique across repos.

Package matching

npm and composer dependencies match in two ways: a local path (file: specs, workspace globs, composer path repositories) that resolves into a sibling repo, or a package name that exactly one sibling repo publishes. For npm, a repo publishes its root package.json and its declared workspace members, so a vendored or fixture package.json never claims a name. For composer, every composer.json up to three directories deep counts, outside vendor/, hidden directories, tests, fixtures and examples, which covers split packages such as src/Illuminate/Support/composer.json. A name two repos publish links to neither.

Python dependencies match the same way. A repo publishes the distribution its root pyproject.toml names and those of its [tool.uv.workspace] members. A dependency is read from each of those projects' pyproject.toml ([project] dependencies and optional dependencies, Poetry dependencies and groups) and the requirements*.txt beside it, and names compare in their PEP 503 spelling (Acme.Core is acme-core). A Poetry path dependency or a [tool.uv.sources] path source resolves by its path alone. Lock files and setup.cfg are not read.

Maven matching is filesystem-only and coordinate-based. Repowise resolves local reactor modules, local parents, properties, and dependency-management versions, then links an active direct compile/runtime dependency only when exactly one selected workspace project publishes that groupId:artifactId. Test, provided, system, optional, profile-only, ambiguous, and external dependencies do not create production package edges. Bounded diagnostics retain the reason for Maven non-matches. When a repository has a root pom.xml, only that declared reactor is eligible; unrelated nested example or fixture POMs are not treated as producers.

This does not execute Maven, read user settings, download artifacts, resolve plugins/transitive dependencies/imported BOMs, or infer generated sources. A Maven package edge is also not a published symbol-level code API or a runnable Maven target recommendation; those capabilities are reported separately and remain unsupported.

OpenAPI comparison boundary

The breaking-change guard diffs OpenAPI schemas within this boundary.

OpenAPI comparison covers the common supported subset of 3.0.x, 3.1.x, and 3.2.x: JSON/YAML documents; path/query/header/cookie parameters using OpenAPI's default style, explode, and allowReserved behavior; one application/json request body; exactly one explicit JSON 2xx response; recursive objects and arrays; exact primitive types; requiredness; normalized nullability; finite homogeneous scalar enums; and bounded same-document JSON Pointer references. Request rules describe values the provider accepts; response rules describe values consumers may receive, so requiredness, nullability, enum values, and constrained/unconstrained enum transitions reverse between the two sides. Operation removal remains the transport-neutral contract rule.

Only complete sides with the same schema source and comparison-fidelity key are field-diffed. Unsupported/unresolved nodes, extraction-strategy changes, and response-selection changes become warning-level uncertainty, never shortened schemas or false removals. Remote/cross-file references, composition, additional-properties semantics, arbitrary JSON Schema constraints, non-JSON or ambiguous media, multiple materially different success responses, and OpenAPI 2.0 are outside this boundary. No network dereferencing occurs.

Test impact over REST

GET /api/workspace/test-impact?repo=<alias>&file=<path>. Repeat file for several changed files in the same repo. The response carries the same fields the --format json output has: recommendations (each with its consumer repo, the consumer_files and bound consumer_symbol_ids that reached the test, basis, via, confidence and the contract ids that produced it), unresolved with a reason per link, files_analyzed with the state each landed on, and the summary counts. Over the API an empty answer's summary.reason is no_contract_data, no_matching_links or lookup_failed.