Merge owner-declared surfaces by base URL when the spec locator misses - #77
Open
TaltonFiggins wants to merge 1 commit into
Open
Conversation
mergeDeclared matched a declared surface to a discovered one only by surfaceLocator, which prefers `spec` over `url`. An owner declaration that names both url and spec therefore never matched the LLM-discovered surface for the same API when discovery had recorded only the base URL (and vice versa), and the domain page rendered the API twice: one row "discovered", one "declared". Add a secondary index keyed by `type|url` and fall back to it when the primary locator lookup misses. mergeDeclaredSurface then fills the missing spec/docs on the surviving row as before. Seen on modem.dev: declared "Modem API" (url + spec) and discovered "Modem API" (url only) both rendered until the declaration dropped its spec URL to force a match. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BR5Ajen32HMbwJXaHDrhX1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
mergeDeclared(src/lib/discover.ts) folds an owner's/.well-known/integrations.jsonsurface into the discovered result only whensurfaceLocatormatches. That locator prefersspecoverurl:Same API, two keys, so the declared surface is appended instead of merged and the domain page shows it twice: one row tagged
discovered, onedeclared. The reverse also happens when discovery recorded a spec and the owner declared only the base URL.Seen live on
modem.devtoday: "Modem API" rendered twice until we removed the spec URL from our declaration purely to force the match. That is the wrong incentive for owners, since the declaration is the place we want the spec.Fix
Add a secondary index keyed by
type|urlinmergeDeclaredand fall back to it when the primary locator lookup misses.mergeDeclaredSurfacealready copiesspec/docs/urlonto the surviving row when missing, so the merged row ends up with the spec either way. Surfaces without aurl(spec-only, CLI, package-only) behave exactly as before.preserveSlugsin the worker keys on the same locator, so slug continuity across re-runs is unchanged by this.Tests
Three cases in
src/lib/discover.test.ts:url + specfolds into a discoveredurl-only row, keeps the spec, basis becomesdeclaredurl-only folds into a discovered row that knows the spec (GraphQLintrospection, which skips the network spec validation)bun test src/lib/discover.test.ts: 10 pass. Fullbun testat the repo root: everything green except the 8cli/tests, which needcd cli && bun run buildplus network and run in their own CI job.tsc --noEmit: no errors in the touched files.🤖 Generated with Claude Code
https://claude.ai/code/session_01BR5Ajen32HMbwJXaHDrhX1