feat(release-metadata): publish release-metadata.json + CI sync check [PLT-107543]#611
Open
ninja-shreyash wants to merge 3 commits into
Open
feat(release-metadata): publish release-metadata.json + CI sync check [PLT-107543]#611ninja-shreyash wants to merge 3 commits into
ninja-shreyash wants to merge 3 commits into
Conversation
Adds release-metadata.json — a machine-readable map of public capabilities (services, notable methods, enum members) and the SDK version each was introduced in. Shipped in the package `files` and served via unpkg @latest. Consumers (e.g. the uipath-coded-apps agent skill) use it to answer 'this capability is absent from the installed SDK — which version adds it?' Reading installed types shows what exists now; this file names the upgrade target. - release-metadata.json: seeded from the historical version gates, verified against src @ 1.5.5 (includes the new Notifications service + Subscriptions, ConversationalAgent.downloadCitationSource, MULTILINE_MAX). - scripts/check-release-metadata.mjs + release-metadata:check: CI gate that fails if a public service has no entry or snapshotVersion is stale. Runs in ci.yml after a fresh build (never a stale dist). - release-metadata.md: contract + how to add a capability each release. Scope = presence + since only (no signatures/renames/removals). @internal is excluded. v1 enforcement is service-level; per-method verification is a follow-up. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ninja-shreyash
requested review from
Raina451,
swati354 and
vnaren23
as code owners
July 17, 2026 12:25
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| 1. New **service** → add `services.<PublicName> = { subpath, since: "<this version>" }`. | ||
| 2. New **method** on an existing service → add it under that service's `methods` with `"<this version>"` **only if** its version differs from the service `since` (else it inherits). | ||
| 3. New **enum member** → add under `enums.<Enum>.values`. | ||
| 4. Bump `snapshotVersion` to the release version. |
Contributor
There was a problem hiding this comment.
The agent_docs/rules.md post-implementation checklist (line 102) ends with package.json exports + rollup.config.js — subpath export added (if new service). It has no entry for release-metadata.json, so AI-guided onboarding won't remind developers to update the metadata file — they'll only find out when CI fails.
Please add a checklist item there, e.g.:
- [ ] `release-metadata.json` — new service entry added with `since: "<version>"` (if new service); `snapshotVersion` bumped on version-bump PRs
This mirrors how docs/oauth-scopes.md and mkdocs.yml are already called out in the same checklist.
…ghts methods - Notifications: since 1.4.5 -> 1.5.1 (the ./notifications public subpath and Notifications export shipped in 1.5.1, not 1.5.5; only Subscriptions is new in 1.5.5). - MaestroProcesses + Cases: pin the Maestro analytics methods to their real introduction versions instead of leaving them baseline (getInstanceStatusTimeline/ getTop* 1.3.9, getTopElementFailedCount 1.3.11, getElementStats 1.3.12, getInstanceStats 1.5.0, getIncidentsTimeline 1.5.1). Services stay baseline (null); only the later methods are listed (inheritance). - Subscriptions kept: it is publicly exported from ./notifications with no @internal tag, so metadata reflects the mechanical public surface. All versions resolved from the actual release tags. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| // ── 2. orphan entries (in metadata, not in the public surface) ────────────────── | ||
| // Removals "never happen" — flag for human review, never auto-drop a `since` fact. | ||
| for (const name of listed) { | ||
| if (!surface.has(name)) { |
Contributor
There was a problem hiding this comment.
The orphan check confirms each meta.services key maps to a real public service (surface.has(name)), but never validates that meta.services[name].subpath matches surface.get(name) — the subpath the build actually detected. Consumers use subpath to construct the import path, so a stale or typo'd value silently passes CI.
Suggested addition in the else branch:
} else if (meta.services[name].subpath !== surface.get(name)) {
fail.push(
`SUBPATH_MISMATCH: "${name}" subpath in metadata is "${meta.services[name].subpath}" ` +
`but package.json exports map it to "${surface.get(name)}". ` +
`Update subpath in release-metadata.json.`
);
}Making it a fail (not warn) is consistent with the MISSING check — an incorrect import path is as harmful as a missing entry for a consumer trying to import the service.
Contributor
|
Review summary — new finding posted this run: subpath mismatch not validated in check-release-metadata.mjs (line 81). Existing open thread on release-metadata.md:41 was not re-raised. |
ninja-shreyash
changed the title
…ersion to sdkVersion
Review feedback: services/methods/enums are now arrays of { name, ... } objects
(standard, schema-validatable, codegen-friendly) instead of name-keyed maps; and
snapshotVersion -> sdkVersion (schema and per-entry since are also version markers,
so the top-level field reads clearer as sdkVersion).
Updated release-metadata.json, the completeness check (scripts/check-release-metadata.mjs),
and release-metadata.md. Check passes on the current surface (27/27).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
|
✅ No issues found. Checked for bugs and CLAUDE.md compliance. |
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.
What
Adds
release-metadata.json— a map of public capabilities (services, notable methods, enum members) to the SDK version each was introduced in — plus a CI check that keeps it in sync with the API. Shipped in the package (files) and served on unpkg@latest. Contract inrelease-metadata.md.Why
Lets consumers (e.g. the
uipath-coded-appsskill) answer "a capability is missing from the installed SDK — which version adds it?" Installed types show what exists now; this names the version to upgrade to.Contents (verified against release tags)
Insights RTM subpaths 1.4.1, Agents aggregates 1.5.0, AgentTraces governance 1.5.1,
MULTILINE_MAX1.5.2, Maestro analytics 1.3.9–1.5.1,Notifications1.5.1,Subscriptions1.5.5,downloadCitationSource1.5.5.CI
npm run release-metadata:check(inci.yml, after a fresh build) fails if a public service has no entry (prints the JSON to add) orsnapshotVersionis stale.Reviewer note
Subscriptionsis included because it's publicly exported from./notificationswith no@internaltag. If it should be internal, add an@internaltag and I'll drop the entry.🤖 Generated with Claude Code