docs(openapi): define delete_all completion for remote repositories

Why

api/openapi/v1.yaml defines delete_all completion as acceptance-time emptiness. That holds for hosted repositories but not remote ones: the caller's own read traffic re-fetches a remote collection's rows, so a poll-until-empty loop against a live remote cache never terminates. Container's text already carries the hosted/remote split. The shared Maven/npm response schema, PackagesBulkDeleteAccepted, still states the hosted-only promise unconditionally, and five smaller sites in the files this MR touches name only "npm" for behavior Maven's remote pass shares.

What

  • Splits PackagesBulkDeleteAccepted into hosted/remote clauses, reusing ContainerBulkDeleteAccepted's wording byte for byte so the sibling schemas read as one voice.
  • Widens the five npm-only sites in v1.yaml's bulk-delete descriptions by dropping the format name rather than enumerating formats, so a fourth format with a remote pass needs no edit here.
  • Pins the new promise with four Contains checks on the whitespace-normalized description. YAML re-wrapping cannot split a pin, and nothing structural reads this prose, so nothing else would catch a flattening rebase.
  • Aligns api/bruno/** as a ride-along: no operation changed, so the Bruno guardrail does not fire, but the files restate the same broken promise, including one container file the earlier container fix never resynced.

Test plan

  • go test ./internal/managementapi/... -run TestContract -v: the new TestContract_PackagesBulkDeleteAccepted_HostedRemoteSplit is red on main (each pinned substring has zero occurrences there) and green here, and the rest of the contract suite stays green.
  • npx --yes @redocly/cli@2.34.0 lint --config api/openapi/redocly.yaml, the version CI's lint:openapi job pins: passes.
  • Every commit ran the full pre-commit hook chain (no --no-verify: the guard test lands with the prose it pins, already green).

Spec coverage

Contract site Change Guard
PackagesBulkDeleteAccepted, completion sentence split: hosted acceptance-time boundary, remote bounded pass pins holds no entry older than the request, what is promised is the pass, re-cached behind it is still there
PackagesBulkDeleteAccepted, resubmission sentence split: hosted retry boundary, remote second pass pin remote repository is another pass
bulkDeletePackages (2 sentences), bulkDeleteVersions (1), bulkDeleteFiles (1), PackagesBulkDeleteAllSelector (1) "remote npm" widened to "remote" prose only
api/bruno/management-api/: container-bulk-deletes/folder.bru and 4 package-bulk-deletes/*.bru same split and widening as their openapi sites prose only

All four pins run against the description with whitespace runs collapsed (strings.Fields join), so a wrapping change cannot break them.

Closes #738 (closed)

Context for LLM agents

Rationale

  • Three commits with a red test(openapi) commit first. Rejected: this MR has no production layer to split from, and the repo's precedent for contract prose lands guard test and prose in one green commit, as in docs(openapi): Declare API lifecycle status (!2004 - merged) • Chance Feick.
  • Contains on the raw description. Rejected: a YAML re-wrap moves line breaks and silently splits a pin. Chosen: collapse whitespace first, then pin four clause fragments.
  • Widening "npm" to "Maven or npm". Rejected: neither container passage names a format, and a genericized sentence needs no edit when a fourth format gains a remote pass.

Consequences: the pins are reword-sensitive by design. A rewording that keeps the promise in different words fails the test and must update the pins.

Non-goals

  • The four remote npm sites left in v1.yaml (~1389, ~1557, ~1642, ~1722), the parallel packument sentence kept in bulk-delete-files.bru, and the three artifact-deletes/*.bru files. npm-specific mechanics (packument freshness, dist-tags) with no Maven analog.
  • Pinning ContainerBulkDeleteAccepted's prose. The same undefended-prose risk exists there, but it predates this issue. Follow-up candidate.
  • The stale "will declare its own equivalents" comment above PackagesBulkDeleteAccepted (~4837). Out-of-hunk churn, declined.
  • docs/specs/S17-rest-management-api.md. Already states the split.

Merge request reports

Loading
Loading