chore: moving isOwnerOf to alpha and documentation the limitations

Signed-off-by: blam <ben@blam.sh>

plugins/catalog-react/api-report.md

@@ -452,8 +452,8 @@ export function InspectEntityDialog(props: {
   onClose: () => void;
 }): JSX.Element | null;
 
-// @public
-export function isOwnerOf(owner: Entity, owned: Entity): boolean;
+// @alpha
+export function isOwnerOf(owner: Entity, entity: Entity): boolean;
 
 // @public @deprecated
 export function loadCatalogOwnerRefs(

plugins/catalog-react/src/utils/isOwnerOf.ts

@@ -24,10 +24,15 @@ import {
 import { getEntityRelations } from './getEntityRelations';
 
 /**
- * Get the related entity references.
- * @public
+ * Returns true if the `owner` argument is a direct owner on the `entity` argument.
+ *
+ * @alpha
+ * @remarks
+ *
+ * Note that this ownership is not the same as using the claims in the auth-resolver, it only will take into account ownership as expressed by direct entity relations.
+ * It doesn't know anything about the additional groups that a user might belong to which the claims contain.
  */
-export function isOwnerOf(owner: Entity, owned: Entity) {
+export function isOwnerOf(owner: Entity, entity: Entity) {
   const possibleOwners = new Set(
     [
       ...getEntityRelations(owner, RELATION_MEMBER_OF, { kind: 'group' }),
@@ -35,7 +40,7 @@ export function isOwnerOf(owner: Entity, owned: Entity) {
     ].map(stringifyEntityRef),
   );
 
-  const owners = getEntityRelations(owned, RELATION_OWNED_BY).map(
+  const owners = getEntityRelations(entity, RELATION_OWNED_BY).map(
     stringifyEntityRef,
   );