refactor: move AiResource types to @backstage/catalog-model alpha

Signed-off-by: benjdlambert <ben@blam.sh>
2026-05-18 17:38:27 +02:00
parent 46fbd60aef
commit 333b10c2ab
15 changed files with 144 additions and 127 deletions
@@ -1,5 +1,6 @@
 ---
 '@backstage/plugin-catalog-backend-module-ai-model': minor
+'@backstage/catalog-model': minor
 ---

-Introduced the `AiResource` catalog entity kind as an opt-in backend module. Install this module to register support for `AiResource` entities in your catalog, used to represent contextual information consumed by AI coding tools such as skills and rules.
+Introduced the `AiResource` catalog entity kind. Entity types, validators, type guards, and the model layer are exported from `@backstage/catalog-model/alpha`. Install `@backstage/plugin-catalog-backend-module-ai-model` in your backend to register the kind with the catalog.
@@ -3,13 +3,39 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).

 ```ts
-import type { Entity } from '@backstage/catalog-model';
+import type { Entity as Entity_2 } from '@backstage/catalog-model';
 import { JsonObject } from '@backstage/types';
 import { JsonValue } from '@backstage/types';
 import { SerializedError } from '@backstage/errors';

 // @alpha
-export interface AlphaEntity extends Entity {
+export const aiResourceEntityModel: CatalogModelLayer;
+
+// @alpha
+export type AiResourceEntityV1alpha1 =
+  | AiResourceEntityV1alpha1Default
+  | SkillAiResourceEntityV1alpha1;
+
+// @alpha
+export interface AiResourceEntityV1alpha1Default extends Entity {
+  // (undocumented)
+  apiVersion: 'backstage.io/v1alpha1';
+  // (undocumented)
+  kind: 'AiResource';
+  // (undocumented)
+  spec: {
+    type: string;
+    lifecycle: string;
+    owner: string;
+    system?: string;
+  };
+}
+
+// @alpha
+export const aiResourceEntityV1alpha1Validator: KindValidator;
+
+// @alpha
+export interface AlphaEntity extends Entity_2 {
  status?: EntityStatus;
 }

@@ -400,6 +426,43 @@ export function createCatalogModelLayerBuilder(options: {
 // @alpha
 export const defaultCatalogEntityModel: CatalogModelLayer;

+// @public
+export type Entity = {
+  apiVersion: string;
+  kind: string;
+  metadata: EntityMeta;
+  spec?: JsonObject;
+  relations?: EntityRelation[];
+};
+
+// @public
+export type EntityLink = {
+  url: string;
+  title?: string;
+  icon?: string;
+  type?: string;
+};
+
+// @public
+export type EntityMeta = JsonObject & {
+  uid?: string;
+  etag?: string;
+  name: string;
+  namespace?: string;
+  title?: string;
+  description?: string;
+  labels?: Record<string, string>;
+  annotations?: Record<string, string>;
+  tags?: string[];
+  links?: EntityLink[];
+};
+
+// @public
+export type EntityRelation = {
+  type: string;
+  targetRef: string;
+};
+
 // @alpha
 export type EntityStatus = {
  items?: EntityStatusItem[];
@@ -416,5 +479,42 @@ export type EntityStatusItem = {
 // @alpha
 export type EntityStatusLevel = 'info' | 'warning' | 'error';

+// @alpha
+export const isAiResourceEntity: (
+  entity: Entity,
+) => entity is AiResourceEntityV1alpha1;
+
+// @alpha
+export const isSkillAiResourceEntity: (
+  entity: Entity,
+) => entity is SkillAiResourceEntityV1alpha1;
+
+// @public
+export type KindValidator = {
+  check(entity: Entity): Promise<boolean>;
+};
+
+// @alpha
+export interface SkillAiResourceEntityV1alpha1 extends Entity {
+  // (undocumented)
+  apiVersion: 'backstage.io/v1alpha1';
+  // (undocumented)
+  kind: 'AiResource';
+  // (undocumented)
+  spec: {
+    type: 'skill';
+    lifecycle: string;
+    owner: string;
+    system?: string;
+    disciplines?: string[];
+    categories?: string[];
+    agents?: string[];
+    dependsOn?: string[];
+  };
+}
+
+// @alpha
+export const skillAiResourceEntityV1alpha1Validator: KindValidator;
+
 // (No @packageDocumentation comment for this package)
 ```
@@ -14,11 +14,30 @@
 * limitations under the License.
 */

+export type {
+  Entity,
+  EntityLink,
+  EntityMeta,
+  EntityRelation,
+} from './entity/Entity';
+export type { KindValidator } from './kinds/types';
 export type { AlphaEntity } from './entity/AlphaEntity';
 export type {
  EntityStatus,
  EntityStatusItem,
  EntityStatusLevel,
 } from './entity/EntityStatus';
+export type {
+  AiResourceEntityV1alpha1,
+  AiResourceEntityV1alpha1Default,
+  SkillAiResourceEntityV1alpha1,
+} from './kinds/AiResourceEntityV1alpha1';
+export {
+  aiResourceEntityV1alpha1Validator,
+  skillAiResourceEntityV1alpha1Validator,
+  isAiResourceEntity,
+  isSkillAiResourceEntity,
+  aiResourceEntityModel,
+} from './kinds/AiResourceEntityV1alpha1';
 export * from './model';
 export { defaultCatalogEntityModel } from './model/defaultCatalogEntityModel';
@@ -14,7 +14,7 @@
 * limitations under the License.
 */

-import type { Entity } from '@backstage/catalog-model';
+import type { Entity } from '../entity/Entity';
 import {
  type AiResourceEntityV1alpha1Default,
  type SkillAiResourceEntityV1alpha1,
@@ -14,20 +14,18 @@
 * limitations under the License.
 */

-import {
-  type Entity,
-  entityKindSchemaValidator,
-  type KindValidator,
-} from '@backstage/catalog-model';
-import { createCatalogModelLayer } from '@backstage/catalog-model/alpha';
+import { createCatalogModelLayer } from '../model/createCatalogModelLayer';
+import type { Entity } from '../entity/Entity';
+import { entityKindSchemaValidator } from '../validation';
+import type { KindValidator } from './types';
 import type { JsonObject } from '@backstage/types';
-import defaultJsonSchema from './schema/AiResource.v1alpha1.schema.json';
-import skillJsonSchema from './schema/AiResource.v1alpha1.skill.schema.json';
+import defaultJsonSchema from '../schema/kinds/AiResource.v1alpha1.schema.json';
+import skillJsonSchema from '../schema/kinds/AiResource.v1alpha1.skill.schema.json';

 /**
 * Default AiResource entity for types that don't have a structured spec.
 *
- * @public
+ * @alpha
 */
 export interface AiResourceEntityV1alpha1Default extends Entity {
  apiVersion: 'backstage.io/v1alpha1';
@@ -44,7 +42,7 @@ export interface AiResourceEntityV1alpha1Default extends Entity {
 * AiResource entity with spec.type 'skill'. Represents reusable contextual
 * knowledge consumed by AI coding tools.
 *
- * @public
+ * @alpha
 */
 export interface SkillAiResourceEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1';
@@ -65,7 +63,7 @@ export interface SkillAiResourceEntityV1alpha1 extends Entity {
 * Backstage catalog AiResource kind Entity. Represents contextual information
 * consumed by AI coding tools, such as skills and rules.
 *
- * @public
+ * @alpha
 */
 export type AiResourceEntityV1alpha1 =
  | AiResourceEntityV1alpha1Default
@@ -76,7 +74,7 @@ const defaultValidator = entityKindSchemaValidator(defaultJsonSchema);
 /**
 * Entity data validator for the default {@link AiResourceEntityV1alpha1}.
 *
- * @public
+ * @alpha
 */
 export const aiResourceEntityV1alpha1Validator: KindValidator = {
  async check(data: Entity) {
@@ -89,7 +87,7 @@ const skillValidator = entityKindSchemaValidator(skillJsonSchema);
 /**
 * Entity data validator for {@link SkillAiResourceEntityV1alpha1}.
 *
- * @public
+ * @alpha
 */
 export const skillAiResourceEntityV1alpha1Validator: KindValidator = {
  async check(data: Entity) {
@@ -100,7 +98,7 @@ export const skillAiResourceEntityV1alpha1Validator: KindValidator = {
 /**
 * Type guard for {@link AiResourceEntityV1alpha1}.
 *
- * @public
+ * @alpha
 */
 export const isAiResourceEntity = (
  entity: Entity,
@@ -110,7 +108,7 @@ export const isAiResourceEntity = (
 /**
 * Type guard for {@link SkillAiResourceEntityV1alpha1}.
 *
- * @public
+ * @alpha
 */
 export const isSkillAiResourceEntity = (
  entity: Entity,
@@ -2,7 +2,7 @@ apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:
  name: backstage-plugin-catalog-backend-module-ai-model
-  title: "@backstage/plugin-catalog-backend-module-ai-model"
+  title: '@backstage/plugin-catalog-backend-module-ai-model'
  description: Adds support for the AIResource entity kind to the catalog backend plugin.
 spec:
  lifecycle: experimental
@@ -1,7 +1,7 @@
 {
  "name": "@backstage/plugin-catalog-backend-module-ai-model",
  "version": "0.1.0",
-  "description": "Adds support for the AIResource entity kind to the catalog backend plugin.",
+  "description": "Adds support for the AiResource entity kind to the catalog backend plugin.",
  "backstage": {
    "role": "backend-plugin-module",
    "pluginId": "catalog",
@@ -18,16 +18,12 @@
  "license": "Apache-2.0",
  "exports": {
    ".": "./src/index.ts",
-    "./alpha": "./src/alpha.ts",
    "./package.json": "./package.json"
  },
  "main": "src/index.ts",
  "types": "src/index.ts",
  "typesVersions": {
    "*": {
-      "alpha": [
-        "src/alpha.ts"
-      ],
      "package.json": [
        "package.json"
      ]
@@ -48,8 +44,7 @@
  "dependencies": {
    "@backstage/backend-plugin-api": "workspace:^",
    "@backstage/catalog-model": "workspace:^",
-    "@backstage/plugin-catalog-node": "workspace:^",
-    "@backstage/types": "workspace:^"
+    "@backstage/plugin-catalog-node": "workspace:^"
  },
  "devDependencies": {
    "@backstage/backend-test-utils": "workspace:^",
@@ -1,12 +0,0 @@
-## API Report File for "@backstage/plugin-catalog-backend-module-ai-model"
-
-> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
-
-```ts
-import { CatalogModelLayer } from '@backstage/catalog-model/alpha';
-
-// @alpha
-export const aiResourceEntityModel: CatalogModelLayer;
-
-// (No @packageDocumentation comment for this package)
-```
@@ -4,65 +4,8 @@

 ```ts
 import { BackendFeature } from '@backstage/backend-plugin-api';
-import { Entity } from '@backstage/catalog-model';
-import { KindValidator } from '@backstage/catalog-model';
-
-// @public
-export type AiResourceEntityV1alpha1 =
-  | AiResourceEntityV1alpha1Default
-  | SkillAiResourceEntityV1alpha1;
-
-// @public
-export interface AiResourceEntityV1alpha1Default extends Entity {
-  // (undocumented)
-  apiVersion: 'backstage.io/v1alpha1';
-  // (undocumented)
-  kind: 'AiResource';
-  // (undocumented)
-  spec: {
-    type: string;
-    lifecycle: string;
-    owner: string;
-    system?: string;
-  };
-}
-
-// @public
-export const aiResourceEntityV1alpha1Validator: KindValidator;

 // @public
 const catalogModuleAiResourceEntityModel: BackendFeature;
 export default catalogModuleAiResourceEntityModel;
-
-// @public
-export const isAiResourceEntity: (
-  entity: Entity,
-) => entity is AiResourceEntityV1alpha1;
-
-// @public
-export const isSkillAiResourceEntity: (
-  entity: Entity,
-) => entity is SkillAiResourceEntityV1alpha1;
-
-// @public
-export interface SkillAiResourceEntityV1alpha1 extends Entity {
-  // (undocumented)
-  apiVersion: 'backstage.io/v1alpha1';
-  // (undocumented)
-  kind: 'AiResource';
-  // (undocumented)
-  spec: {
-    type: 'skill';
-    lifecycle: string;
-    owner: string;
-    system?: string;
-    disciplines?: string[];
-    categories?: string[];
-    agents?: string[];
-    dependsOn?: string[];
-  };
-}
-
-// @public
-export const skillAiResourceEntityV1alpha1Validator: KindValidator;
 ```
@@ -1,17 +0,0 @@
-/*
- * Copyright 2026 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-export { aiResourceEntityModel } from './AiResourceEntityV1alpha1';
@@ -20,15 +20,4 @@
 * @packageDocumentation
 */

-export type {
-  AiResourceEntityV1alpha1,
-  AiResourceEntityV1alpha1Default,
-  SkillAiResourceEntityV1alpha1,
-} from './AiResourceEntityV1alpha1';
-export {
-  aiResourceEntityV1alpha1Validator,
-  skillAiResourceEntityV1alpha1Validator,
-  isAiResourceEntity,
-  isSkillAiResourceEntity,
-} from './AiResourceEntityV1alpha1';
 export { catalogModuleAiResourceEntityModel as default } from './module';
@@ -15,9 +15,11 @@
 */

 import { createBackendModule } from '@backstage/backend-plugin-api';
-import { CatalogModelSources } from '@backstage/catalog-model/alpha';
+import {
+  CatalogModelSources,
+  aiResourceEntityModel,
+} from '@backstage/catalog-model/alpha';
 import { catalogModelExtensionPoint } from '@backstage/plugin-catalog-node/alpha';
-import { aiResourceEntityModel } from './AiResourceEntityV1alpha1';

 /**
 * Registers support for the AiResource entity kind in the catalog.
@@ -4768,7 +4768,6 @@ __metadata:
    "@backstage/catalog-model": "workspace:^"
    "@backstage/cli": "workspace:^"
    "@backstage/plugin-catalog-node": "workspace:^"
-    "@backstage/types": "workspace:^"
  languageName: unknown
  linkType: soft