Repository navigation
pass: report names that collide once canonicalized #647
Description
Problem
Names are neutral words in the IR (invariant 4), so two source names that canonicalize to the same words collide in every target:
paths:
/users:
get: {operationId: getUser, tags: [users], responses: {"200": {description: ok}}}
post: {operationId: get_user, tags: [users], responses: {"200": {description: ok}}}
put: {operationId: GetUser, tags: [users], responses: {"200": {description: ok}}}
components:
schemas:
Sep: {type: string, enum: [a-b, a_b, "A B", aB]}
Sign: {type: integer, enum: [-1, 1, 0]}
Ops: {type: string, enum: ["<", "<=", "+", "-"]}- All three operations get canonical name
get_userin one group. - All four members of
Sepcanonicalize toa_b. -1and1both canonicalize to1.- The members of
Opsget no canonical words and no hint at all.
Nothing is reported. Emitters resolve collisions by ID (docs/emitters/refine/naming.md), and that stays the mechanism; but the document author would want to know, and one check on neutral words gives the answer for every target at once.
Proposal
A pass that warns, per scope, on equal canonical names: operations within a group, parameters within an operation, properties within a model, groups within a service, members within an enum, and component types. The message names every party. Enum members that canonicalize to no words at all get their own diagnostic. Related: #255 (enum members have no key for resolution).
Activity
fuad-daoud commentedon Oct 10, 2026
Another case for this check: a synthesized operation group can share its name with a declared tag. A document with
tags: [{name: default}], one tagged and one untagged operation, givesg/tags/defaultnamed{source: default}andg/defaultnamed{hint: default}. The webhook group'swebhookshint collides with a declaredwebhookstag in the same way. #801 keeps these names deliberately, since emitters resolve collisions by ID, so the compiler should report the collision, not rename it (#810, closed).OmarAlJarrah commentedon Oct 19, 2026
Two counts for the scopes this issue names, on the golden spec (the Cloudflare API schema,
cloudflare/api-schemasopenapi.jsonat911ad78) compiled atc387e25c:>=,<,==, …), and 1,171 more across 154 compiled corpus specs. A diagnostic tells the author, but an emitter still has nothing to name them from. docs/emitter-design: give an enum member whose value has no letters or digits a naming rule #956 asks the emitter design for that rule.