[delphyne]

Summary

Every string the plugin emits is now classified as CommonMark (description) or plain text (summary, title, OAuth scope descriptions) and handled consistently, whether it comes from a proto comment or an engine.protoc.openapi annotation.

Before:

• Reference links ([Widget], [Service.Method]) were only resolved when referenceLinkTarget was set, which is off by default. Unresolved ones only logged a warning, and the default logLevel=ERROR hid it.
• Annotation text bypassed both resolution and scrubbing.
• Comments kept the leading space of every // line.

Changes

• Comments: read through protoc-utils' cleaned Comment (dedented, Markdown preserved) instead of raw leadingComments.
• Resolution: new compile/Descriptions.kt (on JsonContext) uses protoc-utils-markdown (Keep Markdown in cleaned comments; add protoc-utils-markdown for shared reference links protoc-utils#14) to resolve references in every description, summary, and title against every file in the request.
  • A resolved reference links to its operation, tag, or schema, per referenceLinkTarget.
  • Elements with no anchor in the document render as inline code, without a failure: RPCs without an HTTP binding, services that aren't tagged, types not in components/schemas, and any schema under Swagger UI.
  • Anchor availability is decided per document. The collector is now seeded before annotation layers are merged, so annotation text sees the final schema set.
• New options, matching protoc-gen-markdown:
  • resolveReferenceLinksMode: NONE / WARN / FAIL_ON_INVALID (default). FAIL_ON_INVALID sets CodeGeneratorResponse.error listing every bad reference.
  • referenceLink=<label>=<URL> (repeatable). A URL without a scheme gets https://, because protoc reserves : in --openapi_out.
• Plain text: annotation summaries, titles, and OAuth scope descriptions are scrubbed. Comment-derived summaries keep their first-sentence logic. Code spans in summaries now flatten to bare text instead of "quoted".
• Fix: SecurityScheme.description was dropped and is now emitted.
• ReferenceLinkResolver.kt is removed; operationIdFor and primaryTagFor moved to Descriptions.kt.

⚠️ Breaking change

Unresolved or ambiguous reference links now fail the run by default. Set resolveReferenceLinksMode=WARN to keep the previous behavior. This needs a major version bump.

Output changes

Golden diffs fall into three groups:

• Multi-line descriptions lose the leading space on continuation lines.
• Summaries drop quote marks around former code spans.
• complete now has the security scheme description. CompleteTest now honors UPDATE_GOLDENS like the other suites.

Dependencies

Requires protoc-utils 1.1.0 (engine-public/protoc-utils#14) to be released first.

Test plan

• ./gradlew check against a locally published protoc-utils: all suites pass, with regenerated goldens reviewed
• New referenceLinkResolution suite covers:
  • FAIL_ON_INVALID aggregate error, with one unresolved and one ambiguous reference
  • WARN with REDOC and SWAGGER_UI
  • NONE
  • [text][label] with referenceLink
  • an imported type
  • an unmapped RPC
  • annotation descriptions, summaries, and titles
  • dedented lists
• Native image built with publishToMavenLocal
• The Partner API docs build runs strict mode in both dialects. Across about 2,000 emitted strings per document, an audit found no bare [Name] references, no leading-space continuations, no Markdown in plain-text fields, and no dangling anchors.

🤖 Generated with Claude Code

[ezweave]

praise: I read through it and it looks good, I'd like to see the output against our protos before we go live.