@redocly/realm 0.129.0-next.5 → 0.129.0

package/dist/server/plugins/catalog-entities/utils/normalize-relation.d.ts

@@ -0,0 +1,77 @@
+import type { EntityRelationDtoSchema } from '../schemas/dto-schemas.js';
+/**
+ * Normalized relation data structure.
+ * Derived from EntityRelationDtoSchema with required (but nullable) version/revision fields.
+ */
+export type NormalizedRelation = Pick<EntityRelationDtoSchema, 'type' | 'sourceKey' | 'targetKey'> & {
+    /**
+     * Source entity version (may be swapped from original)
+     */
+    sourceVersion: string | null;
+    /**
+     * Target entity version (may be swapped from original)
+     */
+    targetVersion: string | null;
+    /**
+     * Source entity revision (may be swapped from original)
+     */
+    sourceRevision: string | null;
+    /**
+     * Target entity revision (may be swapped from original)
+     */
+    targetRevision: string | null;
+};
+/**
+ * Input relation data structure.
+ * Core relation fields from EntityRelationDtoSchema.
+ */
+export type RelationInput = Pick<EntityRelationDtoSchema, 'type' | 'sourceKey' | 'targetKey' | 'sourceVersion' | 'targetVersion' | 'sourceRevision' | 'targetRevision'>;
+/**
+ * Normalizes a relation to its canonical form.
+ *
+ * This function:
+ * 1. Looks up the canonical relation type in the normalization map
+ * 2. If the relation type differs from its canonical form, swaps source and target (including versions and revisions)
+ * 3. Uses the canonical relation type
+ * 4. For unknown relation types, passes through without modification
+ *
+ * @param relation - The relation to normalize
+ * @returns Normalized relation with canonical type and potentially swapped entities
+ *
+ * @example
+ * // Normalize ownedBy -> owns with swapped entities
+ * normalizeRelation({
+ *   type: 'ownedBy',
+ *   sourceKey: 'api-1',
+ *   targetKey: 'team-1',
+ *   sourceVersion: 'v1',
+ *   targetVersion: null,
+ *   sourceRevision: null,
+ *   targetRevision: null,
+ * })
+ * // Returns:
+ * // {
+ * //   type: 'owns',
+ * //   sourceKey: 'team-1',  // swapped
+ * //   targetKey: 'api-1',   // swapped
+ * //   sourceVersion: null,  // swapped
+ * //   targetVersion: 'v1',  // swapped
+ * //   sourceRevision: null,
+ * //   targetRevision: null,
+ * // }
+ *
+ * @example
+ * // Canonical type passes through unchanged
+ * normalizeRelation({
+ *   type: 'owns',
+ *   sourceKey: 'team-1',
+ *   targetKey: 'api-1',
+ *   sourceVersion: null,
+ *   targetVersion: 'v1',
+ *   sourceRevision: null,
+ *   targetRevision: null,
+ * })
+ * // Returns: same as input
+ */
+export declare function normalizeRelation(relation: RelationInput): NormalizedRelation;
+//# sourceMappingURL=normalize-relation.d.ts.map

package/dist/server/plugins/catalog-entities/utils/normalize-relation.js

@@ -0,0 +1 @@
+import{RELATION_NORMALIZATION_MAP as r}from"../database/constants/relation-normalization.js";function o(e){const s=r[e.type];return s?e.type===s?{type:s,sourceKey:e.sourceKey,targetKey:e.targetKey,sourceVersion:e.sourceVersion??null,targetVersion:e.targetVersion??null,sourceRevision:e.sourceRevision??null,targetRevision:e.targetRevision??null}:{type:s,sourceKey:e.targetKey,targetKey:e.sourceKey,sourceVersion:e.targetVersion??null,targetVersion:e.sourceVersion??null,sourceRevision:e.targetRevision??null,targetRevision:e.sourceRevision??null}:{type:e.type,sourceKey:e.sourceKey,targetKey:e.targetKey,sourceVersion:e.sourceVersion??null,targetVersion:e.targetVersion??null,sourceRevision:e.sourceRevision??null,targetRevision:e.targetRevision??null}}export{o as normalizeRelation};

package/dist/server/plugins/config-parser/format-error.js

@@ -1,9 +1,17 @@
-import{getLineColLocation as f,isAbsoluteUrl as s}from"@redocly/openapi-core";import{getCodeframe as l}from"@redocly/openapi-core";import m from"node:path";import{gray as u}from"../../tools/notifiers/helpers/colors.js";function h(r,n){return`Config validation error:
+import{getLineColLocation as u,isAbsoluteUrl as m}from"@redocly/openapi-core";import{getCodeframe as g}from"@redocly/openapi-core";import l from"node:path";import{gray as i}from"../../tools/notifiers/helpers/colors.js";function d(a,s){return`Config validation error:
 
-`+i(r);function i(e){const o=e.location[0],a=s(o.source.absoluteRef)?o.source.absoluteRef:m.relative(n,o.source.absoluteRef),t=f(o),c=o.pointer?u(`at ${o.pointer}`):"";return`${`${a}:${t.start.line}:${t.start.col}`} ${c}
+`+c(a);function c(o){const t=o.location[0];if(!t)return o.message;if(!t.source){const n=t.pointer??"";return`${o.message}${n?` at ${n}`:""}`}const e=t.source?.absoluteRef,r=e&&m(e)?e:e?l.relative(s,e):"config";try{if(typeof t.source.getAst!="function"){const $=t.pointer?i(`at ${t.pointer}`):"";return`${r} ${$}
 
-${e.message}
+${o.message}
 
-`+l(t,!0)+`
+`}const n=u(t),f=t.pointer?i(`at ${t.pointer}`):"";return`${`${r}:${n.start.line}:${n.start.col}`} ${f}
 
-`}}export{h as formatConfigProblem};
+${o.message}
+
+`+g(n,!0)+`
+
+`}catch{const n=t.pointer?i(`at ${t.pointer}`):"";return`${r} ${n}
+
+${o.message}
+
+`}}}export{d as formatConfigProblem};

package/dist/server/plugins/config-parser/loaders/utils/read-and-validate-config.js

@@ -1 +1 @@
-import h from"path";import{lintConfig as C,loadConfig as P,createConfigTypes as T}from"@redocly/openapi-core";import{deepMerge as b}from"../../../../../utils/object/deep-merge.js";import{readEnvVariable as R}from"../../../../utils/envs/read-env-variable.js";import{logger as a}from"../../../../tools/notifiers/logger.js";import{safeParsePartial as A}from"../../safe-parse.js";import{formatConfigProblem as x}from"../../format-error.js";import{ExternalResolver as E}from"../../../../fs/utils/external-ref-resolver.js";import{resolveMutuallyExclusiveProps as $}from"../../resolve-mutual-exclusion.js";async function W(o,r,t,c){const u=r.getFileInfo(o)?.realRelativePath||o;async function y(){const i=new E(r),l=h.join(r.cwd,u),n=await P({configPath:l,externalRefResolver:i}),f=await c(n.resolvedConfig);if(f===void 0)return n.resolvedConfig;const g=[...n.document?.source?await C({config:n,externalConfigTypes:T(f,n)}):[],...n.document?.source?$(n.resolvedConfig,n.document?.source):[]];if(g.length>0)for(const w of g)t(new Error(x(w,r.cwd)));return n.resolvedConfig}const s=await r.exists(o)?await y():{},v=j(s),p=await c(s);"residency"in s&&s.residency&&typeof s.residency=="string"&&(/^https?:\/\/.*/.test(s.residency)||t(new Error(`Invalid residency URL: "${s.residency}". Residency must start with "http://" or "https://".`)));let d=p?A(p,s):s;const{env:m}=d;if(m){const i=R("REDOCLY_ENV")||"development",l=m[i]||{};d=b(d,l)}const e=M(d,v);if(e.imports&&e.imports.length>0){a.warn("The 'imports' property is deprecated. Please use 'plugins' property instead.");const i=new Set([...e.plugins||[],...e.imports.map(l=>h.posix.join(l,"plugin.js"))]);e.plugins=Array.from(i),delete e.imports}if(e.catalog&&(a.warn("The 'catalog' property is deprecated. Please use 'catalogClassic' property instead."),e.catalogClassic={...e.catalog},delete e.catalog),e.scorecard&&(a.warn("The 'scorecard' property is deprecated. Please use 'scorecardClassic' property instead."),e.scorecardClassic=e.scorecard,delete e.scorecard),e.search?.ai){a.warn("The 'search.ai' property is deprecated. Please use 'aiAssistant' property instead.");const i={...e.search?.ai,...e.aiAssistant,suggestions:e.aiAssistant?.suggestions?.length?e.aiAssistant.suggestions:e.search?.ai.suggestions||[]};e.aiAssistant=i,delete e.search.ai}return e}function j(o){if(!o.theme)return[];a.warn("The 'theme' property in redocly.yaml is deprecated. Please move all of the properties from 'theme' to the root of the config.");const r=[];for(const t of Object.keys(o.theme))o[t]==null?r.push(t):a.warn(`Detected both '${t}' and 'theme.${t}' properties in redocly.yaml. The 'theme.${t}' property will be ignored and needs to be removed or merged into the '${t}'.`);return r}function M(o,r){if(!o.theme||r.length===0)return o;const t={...o};for(const c of r)t[c]=o.theme[c];return delete t.theme,t}export{W as readAndValidateConfig};
+import w from"path";import{lintConfig as R,loadConfig as C,createConfigTypes as T}from"@redocly/openapi-core";import{deepMerge as U}from"../../../../../utils/object/deep-merge.js";import{readEnvVariable as A}from"../../../../utils/envs/read-env-variable.js";import{logger as l}from"../../../../tools/notifiers/logger.js";import{safeParsePartial as L}from"../../safe-parse.js";import{formatConfigProblem as $}from"../../format-error.js";import{ExternalResolver as q}from"../../../../fs/utils/external-ref-resolver.js";import{resolveMutuallyExclusiveProps as x}from"../../resolve-mutual-exclusion.js";function f(o,e,t,r){e in o&&o[e]&&typeof o[e]=="string"&&(/^https?:\/\/.*/.test(o[e])||r(new Error(`Invalid ${t} URL: "${o[e]}". ${t} must start with "http://" or "https://".`)))}function j(o,e){if("access"in o&&o.access&&typeof o.access=="object"){const t=o.access;f(t,"logoutReturnUrl","access.logoutReturnUrl",e),f(t,"residency","access.residency",e);const r=["requiresLogin","logoutReturnUrl","residency","sso","rbac"];for(const n of r)n in t&&t[n]!==void 0&&n in o&&o[n]!==void 0&&e(new Error(`Property '${n}' is defined both at root level and in 'access' object. Please use 'access.${n}' to define this configuration.`))}}async function z(o,e,t,r){const m=e.getFileInfo(o)?.realRelativePath||o;async function d(){const c=new q(e),u=w.join(e.cwd,m),i=await C({configPath:u,externalRefResolver:c}),y=await r(i.resolvedConfig);if(y===void 0)return i.resolvedConfig;const v=[...i.document?.source?await R({config:i,externalConfigTypes:T(y,i)}):[],...i.document?.source?x(i.resolvedConfig,i.document?.source):[]];if(v.length>0)for(const b of v)t(new Error($(b,e.cwd)));return i.resolvedConfig}const a=await e.exists(o)?await d():{},P=E(a),g=await r(a);f(a,"residency","Residency",t),f(a,"logoutReturnUrl","Logout return URL",t),j(a,t);let p=g?L(g,a):a;const{env:h}=p;if(h){const c=A("REDOCLY_ENV")||"development",u=h[c]||{};p=U(p,u)}const s=M(p,P);if(s.imports&&s.imports.length>0){l.warn("The 'imports' property is deprecated. Please use 'plugins' property instead.");const c=new Set([...s.plugins||[],...s.imports.map(u=>w.posix.join(u,"plugin.js"))]);s.plugins=Array.from(c),delete s.imports}if(s.catalog&&(l.warn("The 'catalog' property is deprecated. Please use 'catalogClassic' property instead."),s.catalogClassic={...s.catalog},delete s.catalog),s.scorecard&&(l.warn("The 'scorecard' property is deprecated. Please use 'scorecardClassic' property instead."),s.scorecardClassic=s.scorecard,delete s.scorecard),s.search?.ai){l.warn("The 'search.ai' property is deprecated. Please use 'aiAssistant' property instead.");const c={...s.search?.ai,...s.aiAssistant,suggestions:s.aiAssistant?.suggestions?.length?s.aiAssistant.suggestions:s.search?.ai.suggestions||[]};s.aiAssistant=c,delete s.search.ai}return k(s)}function k(o){const e="access"in o?o.access:void 0;if(!e||typeof e!="object")return o;const t={...o},r=[{name:"requiresLogin",type:"boolean"},{name:"logoutReturnUrl",type:"string"},{name:"residency",type:"string"},{name:"sso",type:"string | string[]"},{name:"rbac",type:"object"}],n=[];for(const m of r){const d=m.name;d in t&&t[d]!==void 0&&!(d in e)&&n.push(d)}return n.length>0&&l.warn(`The following properties at root level are deprecated: ${n.join(", ")}. Please move them to the 'access' object.`),"requiresLogin"in e&&e.requiresLogin!==void 0&&(t.requiresLogin=e.requiresLogin),"logoutReturnUrl"in e&&e.logoutReturnUrl!==void 0&&(t.logoutReturnUrl=e.logoutReturnUrl),"residency"in e&&e.residency!==void 0&&(t.residency=e.residency),"sso"in e&&e.sso!==void 0&&(t.sso=e.sso),"rbac"in e&&e.rbac!==void 0&&(t.rbac=e.rbac),delete t.access,t}function E(o){if(!o.theme)return[];l.warn("The 'theme' property in redocly.yaml is deprecated. Please move all of the properties from 'theme' to the root of the config.");const e=[];for(const t of Object.keys(o.theme))o[t]==null?e.push(t):l.warn(`Detected both '${t}' and 'theme.${t}' properties in redocly.yaml. The 'theme.${t}' property will be ignored and needs to be removed or merged into the '${t}'.`);return e}function M(o,e){if(!o.theme||e.length===0)return o;const t={...o};for(const r of e)t[r]=o.theme[r];return delete t.theme,t}export{z as readAndValidateConfig};

package/dist/server/providers/database/databases/catalog-sqlite/migrations/0003_catalog_versions_and_revisions_relations.sql

@@ -9,9 +9,21 @@ DROP INDEX IF EXISTS `idx_entities_key_source_created_at`;--> statement-breakpoi
 DROP INDEX IF EXISTS `idx_entities_key_source_is_current`;--> statement-breakpoint
 DROP INDEX IF EXISTS `idx_entities_key_source_is_default`;--> statement-breakpoint
 DROP INDEX IF EXISTS `idx_entities_key_source`;--> statement-breakpoint
+-- Update all NULL values to '' first before creating unique index
 UPDATE `entities_relations` SET "source_version" = '' WHERE "source_version" IS NULL;--> statement-breakpoint
+UPDATE `entities_relations` SET "source_revision" = '' WHERE "source_revision" IS NULL;--> statement-breakpoint
+UPDATE `entities_relations` SET "target_version" = '' WHERE "target_version" IS NULL;--> statement-breakpoint
+UPDATE `entities_relations` SET "target_revision" = '' WHERE "target_revision" IS NULL;--> statement-breakpoint
+-- Delete duplicate relations keeping only the most recent one (by id)
+DELETE FROM `entities_relations` WHERE `id` NOT IN (
+  SELECT MAX(`id`) FROM `entities_relations`
+  GROUP BY `source_key`, `target_key`, `source_version`, `target_version`, `source_revision`, `target_revision`
+);--> statement-breakpoint
 -- We need to set default value to '', because NULL is not unique in sqlite
 ALTER TABLE `entities_relations` ALTER COLUMN "source_version" TO "source_version" text NOT NULL DEFAULT '';--> statement-breakpoint
+ALTER TABLE `entities_relations` ALTER COLUMN "source_revision" TO "source_revision" text NOT NULL DEFAULT '';--> statement-breakpoint
+ALTER TABLE `entities_relations` ALTER COLUMN "target_version" TO "target_version" text NOT NULL DEFAULT '';--> statement-breakpoint
+ALTER TABLE `entities_relations` ALTER COLUMN "target_revision" TO "target_revision" text NOT NULL DEFAULT '';--> statement-breakpoint
 ALTER TABLE `entities_relations` ADD `is_deleted` integer DEFAULT false;--> statement-breakpoint
 CREATE INDEX `idx_entities_relations_source_key` ON `entities_relations` (`source_key`,`is_deleted`);--> statement-breakpoint
 CREATE INDEX `idx_entities_relations_target_key` ON `entities_relations` (`target_key`,`is_deleted`);--> statement-breakpoint
@@ -25,12 +37,6 @@ ALTER TABLE `entities` ADD `is_deleted` integer DEFAULT false;--> statement-brea
 CREATE INDEX `idx_entities_key_source_is_current` ON `entities` (`key`,`is_current`,`is_deleted`);--> statement-breakpoint
 CREATE INDEX `idx_entities_key_source_is_default` ON `entities` (`key`,`is_default_version`);--> statement-breakpoint
 CREATE UNIQUE INDEX `idx_entities_key_source` ON `entities` (`key`,`source`,`revision`,`version`);--> statement-breakpoint
-UPDATE `entities_relations` SET "source_revision" = '' WHERE "source_revision" IS NULL;--> statement-breakpoint
-ALTER TABLE `entities_relations` ALTER COLUMN "source_revision" TO "source_revision" text NOT NULL DEFAULT '';--> statement-breakpoint
-UPDATE `entities_relations` SET "target_version" = '' WHERE "target_version" IS NULL;--> statement-breakpoint
-ALTER TABLE `entities_relations` ALTER COLUMN "target_version" TO "target_version" text NOT NULL DEFAULT '';--> statement-breakpoint
-UPDATE `entities_relations` SET "target_revision" = '' WHERE "target_revision" IS NULL;--> statement-breakpoint
-ALTER TABLE `entities_relations` ALTER COLUMN "target_revision" TO "target_revision" text NOT NULL DEFAULT '';--> statement-breakpoint
 ALTER TABLE `entities_relations` DROP COLUMN `source_id`;--> statement-breakpoint
 ALTER TABLE `entities_relations` DROP COLUMN `target_id`;--> statement-breakpoint
 DROP INDEX IF EXISTS `idx_entities_key_source_is_current`;--> statement-breakpoint

package/dist/server/providers/database/databases/catalog-sqlite/migrations/0004_normalize_relation_types.sql

@@ -0,0 +1,147 @@
+-- Migration: Normalize relation types to canonical forms
+-- This migration transforms bidirectional relation types to their canonical forms
+-- by swapping source and target entities where needed.
+
+-- Normalize ownedBy -> owns (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'owns',
+  target_to_source_relation = 'reverse:owns'
+WHERE source_to_target_relation = 'ownedBy';--> statement-breakpoint
+
+-- Normalize partOf -> hasParts (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'hasParts',
+  target_to_source_relation = 'reverse:hasParts'
+WHERE source_to_target_relation = 'partOf';--> statement-breakpoint
+
+-- Normalize createdBy -> creates (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'creates',
+  target_to_source_relation = 'reverse:creates'
+WHERE source_to_target_relation = 'createdBy';--> statement-breakpoint
+
+-- Normalize implementedBy -> implements (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'implements',
+  target_to_source_relation = 'reverse:implements'
+WHERE source_to_target_relation = 'implementedBy';--> statement-breakpoint
+
+-- Normalize dependencyOf -> dependsOn (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'dependsOn',
+  target_to_source_relation = 'reverse:dependsOn'
+WHERE source_to_target_relation = 'dependencyOf';--> statement-breakpoint
+
+-- Normalize usedBy -> uses (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'uses',
+  target_to_source_relation = 'reverse:uses'
+WHERE source_to_target_relation = 'usedBy';--> statement-breakpoint
+
+-- Normalize extendedBy -> extends (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'extends',
+  target_to_source_relation = 'reverse:extends'
+WHERE source_to_target_relation = 'extendedBy';--> statement-breakpoint
+
+-- Normalize supersededBy -> supersedes (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'supersedes',
+  target_to_source_relation = 'reverse:supersedes'
+WHERE source_to_target_relation = 'supersededBy';--> statement-breakpoint
+
+-- Normalize memberOf -> hasMember (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'hasMember',
+  target_to_source_relation = 'reverse:hasMember'
+WHERE source_to_target_relation = 'memberOf';--> statement-breakpoint
+
+-- Normalize triggeredBy -> triggers (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'triggers',
+  target_to_source_relation = 'reverse:triggers'
+WHERE source_to_target_relation = 'triggeredBy';--> statement-breakpoint
+
+-- Normalize returnedBy -> returns (swap source and target)
+UPDATE `entities_relations`
+SET 
+  source_key = target_key,
+  target_key = source_key,
+  source_version = target_version,
+  target_version = source_version,
+  source_revision = target_revision,
+  target_revision = source_revision,
+  source_to_target_relation = 'returns',
+  target_to_source_relation = 'reverse:returns'
+WHERE source_to_target_relation = 'returnedBy';
+