feat(#4040): add entity-provider SDK with types, interfaces, and annotation validation - #4212
feat(#4040): add entity-provider SDK with types, interfaces, and annotation validation#4212fullsend-ai-coder[bot] wants to merge 1 commit into
Conversation
…tation validation Create the @red-hat-developer-hub/backstage-plugin-boost-entity-provider-sdk package establishing type contracts for the AI catalog entity model. Annotation scheme: - Define annotation constants: AI_ASSET_CATEGORY_ANNOTATION, AI_ASSET_VERSION_ANNOTATION, AI_ASSET_SOURCE_ANNOTATION - Define AIAssetCategory Zod enum with 7 allowed values (agent, skill, rule, skill-bundle, mcp-server, ai-model, model-server) Utilities: - normalizeAIAssetVersion() with 4 normalization rules: semver pass-through, date-based, commit hash, and fallback - validateAIAssetEntity() throwing on missing/invalid annotations - AIAssetValidator CatalogProcessor rejecting entities with invalid annotations, gated to entities carrying rhdh.io/ai-asset-* Interfaces: - AIAssetEntityProvider with connect(), entities() generator, getProviderName(), getProviderId(), and optional delta() method - Neo4jSyncAdapter with createNode(), updateNode(), deleteNode(), createRelationship() and RelationshipType union - SkillBundleMetadata Zod schema for skillcard.yaml parsing Uses Zod schemas as single source of truth per workspace conventions. 28 unit tests cover all validation and normalization rules. Closes #4040
Missing ChangesetsThe following package(s) are changed by this PR but do not have a changeset:
See CONTRIBUTING.md for more information about how to add changesets. Changed Packages
|
|
|
|
/fs-review |
|
🤖 Finished Review · ✅ Success · Started 11:48 PM UTC · Completed 12:06 AM UTC Commit: |
ReviewFindingsMedium
Low
Labels: PR creates a new package under workspaces/boost/ implementing AI asset entity provider SDK |
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
There was a problem hiding this comment.
See the review comment for full details.
Note: The following inline comments could not be posted on the diff (GitHub returned 422) and are included here instead:
workspaces/boost/plugins/boost-entity-provider-sdk/package.json(file-level): Line 97 · [medium] architectural-conflict
The new package's pluginPackages array includes itself (7 entries) but the existing sibling packages (boost-common, boost-node) only list 6 entries and do NOT include the new SDK. The Backstage convention is for all packages sharing a pluginId to have an identical pluginPackages array.
Suggested fix: Update sibling packages' pluginPackages arrays to include the new SDK, or match the existing 6-entry list.
workspaces/boost/plugins/boost-entity-provider-sdk/src/normalizeAIAssetVersion.ts:21: [low] edge-case
SEMVER_RE accepts trailing hyphen without pre-release identifier (e.g. 1.0.0-). The inner ? makes the capture group optional after the literal -, so a bare hyphen matches and the string passes through unchanged.
Suggested fix: Change to (?:-(\w[\w.]*))?$ to require at least one character after the hyphen.
workspaces/boost/plugins/boost-entity-provider-sdk/src/AIAssetValidator.ts:64: [low] logic-error
AIAssetValidator.validateEntityKind produces the same error message for both missing and invalid category values, while validateAIAssetEntity() differentiates them with a more specific message including the rejected value.
Suggested fix: Align error messages between the two validation paths.
workspaces/boost/plugins/boost-entity-provider-sdk/package.json(file-level): Line 119 · [low] pattern-violation
Test script uses --passWithNoTests --coverage flags but sibling packages use bare backstage-cli package test.
Suggested fix: Match sibling packages or apply flags workspace-wide.
workspaces/boost/plugins/boost-entity-provider-sdk/src/index.ts:8: [low] pattern-inconsistency
Barrel file uses named re-exports while boost-common uses export *. Named re-exports prevent accidental exposure of internals.
workspaces/boost/plugins/boost-entity-provider-sdk/src/annotations.ts:54: [low] api-evolution
AIAssetCategorySchema uses z.enum with a fixed tuple. Adding categories will be a type-level breaking change. At version 0.1.0 this is acceptable but the evolution policy should be documented.
workspaces/boost/plugins/boost-entity-provider-sdk/src/Neo4jSyncAdapter.ts:57: [low] api-surface-coupling
Neo4j-specific types exported from a general-purpose entity-provider SDK. Per design.md Decision 7, this is intentional to avoid circular imports; types have no runtime cost.
fullsend-ai-review
Bot
added
requires-manual-review
1 participant
Create the @red-hat-developer-hub/backstage-plugin-boost-entity-provider-sdk package establishing type contracts for the AI catalog entity model.
Annotation scheme:
AI_ASSET_VERSION_ANNOTATION, AI_ASSET_SOURCE_ANNOTATION
(agent, skill, rule, skill-bundle, mcp-server, ai-model,
model-server)
Utilities:
pass-through, date-based, commit hash, and fallback
annotations, gated to entities carrying rhdh.io/ai-asset-*
Interfaces:
getProviderName(), getProviderId(), and optional delta() method
createRelationship() and RelationshipType union
Uses Zod schemas as single source of truth per workspace conventions. 28 unit tests cover all validation and normalization rules.
Closes #4040
Post-script verification
agent/4040-entity-provider-sdk)6c752b60d5bdc359d1eb6b5b81a34880a0c71c21..HEAD)