@fern-api/fern-api-dev 5.23.3-1008-g29939b6a08a → 5.23.3-1013-g60e2acea243

package/cli.cjs

@@ -279185,16 +279185,16 @@ var init_ConjureImporter = __esm({
               });
             }
             for (const [endpointName, endpointDeclaration] of Object.entries(serviceDeclaration.endpoints ?? {})) {
-              const endpointLocator = parseEndpointLocator(endpointDeclaration.http);
-              if (endpointLocator.type === "failure") {
+              const endpointLocator2 = parseEndpointLocator(endpointDeclaration.http);
+              if (endpointLocator2.type === "failure") {
                 this.context?.logger.error(`Failed to parse ${endpointDeclaration.http}. Skipping.`);
                 continue;
               }
               const auth8 = endpointDeclaration.auth ?? serviceDeclaration.defaultAuth;
               const endpoint3 = {
                 auth: auth8 === ConjureAuthDefinitionType.None ? false : true,
-                path: endpointLocator.path,
-                method: endpointLocator.method,
+                path: endpointLocator2.path,
+                method: endpointLocator2.method,
                 response: endpointDeclaration.returns === "binary" ? "file" : endpointDeclaration.returns
               };
               if (endpointDeclaration.docs != null) {
@@ -279202,7 +279202,7 @@ var init_ConjureImporter = __esm({
               }
               const pathParameters = {};
               if (endpointDeclaration.args != null) {
-                for (const pathParameter of endpointLocator.pathParameters) {
+                for (const pathParameter of endpointLocator2.pathParameters) {
                   const pathParameterType = endpointDeclaration.args[pathParameter];
                   if (pathParameterType == null) {
                     throw new CliError({
@@ -449603,100 +449603,229 @@ var init_lib64 = __esm({
 });
 
 // ../docs-resolver/lib/applyTranslatedApiTitlesToNavTree.js
-function applyTranslatedApiTitlesToNavTree(root6, baseApis, translatedApis) {
-  const mapsByApiId = /* @__PURE__ */ new Map();
-  for (const [apiId, translatedApi] of Object.entries(translatedApis)) {
-    const holder = navigation_exports.ApiDefinitionHolder.create(translatedApi);
-    const endpoints = /* @__PURE__ */ new Map();
-    for (const [id, endpoint3] of holder.endpoints) {
-      if (endpoint3.name != null && endpoint3.name.length > 0) {
-        endpoints.set(id, endpoint3.name);
-      }
+function stringifyPathPartsForLocator(path119) {
+  return path119.map((part) => part.type === "literal" ? part.value : "{}").join("");
+}
+function endpointLocator(endpoint3) {
+  return `${endpoint3.method} ${stringifyPathPartsForLocator(endpoint3.path.parts)}`;
+}
+function webhookLocator(webhook) {
+  return `${webhook.method} ${webhook.path.join("/")}`;
+}
+function webSocketLocator(webSocket) {
+  return `WSS ${stringifyPathPartsForLocator(webSocket.path.parts)}`;
+}
+function nonEmptyTitle(name2) {
+  return name2 != null && name2.length > 0 ? name2 : void 0;
+}
+function subpackageTitle(pkg2) {
+  return pkg2.displayName ?? titleCase(pkg2.name);
+}
+function subpackageLocators(pkg2) {
+  return [
+    ...pkg2.endpoints.map(endpointLocator),
+    ...pkg2.webhooks.map(webhookLocator),
+    ...pkg2.websockets.map(webSocketLocator)
+  ];
+}
+function buildResolverForKind(baseEntries, translatedEntries, locatorOf, titleOf) {
+  const translatedIdByLocator = /* @__PURE__ */ new Map();
+  for (const [navId, def] of translatedEntries) {
+    if (!translatedIdByLocator.has(locatorOf(def))) {
+      translatedIdByLocator.set(locatorOf(def), navId);
     }
-    const webhooks2 = /* @__PURE__ */ new Map();
-    for (const [id, webhook] of holder.webhooks) {
-      if (webhook.name != null && webhook.name.length > 0) {
-        webhooks2.set(id, webhook.name);
-      }
+  }
+  return (baseNavId) => {
+    const exact = translatedEntries.get(baseNavId);
+    if (exact != null) {
+      return { translatedId: baseNavId, title: titleOf(exact) };
+    }
+    const baseDef = baseEntries.get(baseNavId);
+    if (baseDef == null) {
+      return void 0;
+    }
+    const translatedId = translatedIdByLocator.get(locatorOf(baseDef));
+    if (translatedId == null) {
+      return void 0;
+    }
+    const translatedDef = translatedEntries.get(translatedId);
+    return { translatedId, title: translatedDef != null ? titleOf(translatedDef) : void 0 };
+  };
+}
+function buildPackagesByBaseTitle(baseApi, translatedApi) {
+  const packagesByBaseTitle = /* @__PURE__ */ new Map();
+  for (const [subpackageId, translatedSubpackage] of Object.entries(translatedApi.subpackages)) {
+    const baseSubpackage = baseApi.subpackages[subpackageId];
+    if (baseSubpackage == null) {
+      continue;
     }
-    const webSockets = /* @__PURE__ */ new Map();
-    for (const [id, webSocket] of holder.webSockets) {
-      if (webSocket.name != null && webSocket.name.length > 0) {
-        webSockets.set(id, webSocket.name);
+    const baseTitle = subpackageTitle(baseSubpackage);
+    const translatedTitle = subpackageTitle(translatedSubpackage);
+    if (baseTitle !== translatedTitle) {
+      packagesByBaseTitle.set(baseTitle, translatedTitle);
+    }
+  }
+  const baseTitleByLocator = /* @__PURE__ */ new Map();
+  for (const baseSubpackage of Object.values(baseApi.subpackages)) {
+    const baseTitle = subpackageTitle(baseSubpackage);
+    for (const locator of subpackageLocators(baseSubpackage)) {
+      if (!baseTitleByLocator.has(locator)) {
+        baseTitleByLocator.set(locator, baseTitle);
       }
     }
-    const graphql4 = /* @__PURE__ */ new Map();
-    for (const [id, operation] of holder.graphqlOperations) {
-      const name2 = operation.displayName ?? operation.name;
-      if (name2 != null && name2.length > 0) {
-        graphql4.set(id, name2);
+  }
+  for (const translatedSubpackage of Object.values(translatedApi.subpackages)) {
+    const translatedTitle = subpackageTitle(translatedSubpackage);
+    for (const locator of subpackageLocators(translatedSubpackage)) {
+      const baseTitle = baseTitleByLocator.get(locator);
+      if (baseTitle != null && baseTitle !== translatedTitle && !packagesByBaseTitle.has(baseTitle)) {
+        packagesByBaseTitle.set(baseTitle, translatedTitle);
       }
     }
-    const packagesByBaseTitle = /* @__PURE__ */ new Map();
+  }
+  return packagesByBaseTitle;
+}
+function buildApiTranslationResolvers(baseApis, translatedApis) {
+  const resolvers = /* @__PURE__ */ new Map();
+  for (const [apiId, translatedApi] of Object.entries(translatedApis)) {
     const baseApi = baseApis[apiId];
-    if (baseApi != null) {
-      for (const [subpackageId, translatedSubpackage] of Object.entries(translatedApi.subpackages)) {
-        const baseSubpackage = baseApi.subpackages[subpackageId];
-        if (baseSubpackage == null) {
-          continue;
-        }
-        const baseTitle = baseSubpackage.displayName ?? titleCase(baseSubpackage.name);
-        const translatedTitle = translatedSubpackage.displayName ?? titleCase(translatedSubpackage.name);
-        if (baseTitle !== translatedTitle) {
-          packagesByBaseTitle.set(baseTitle, translatedTitle);
-        }
+    if (baseApi == null) {
+      continue;
+    }
+    const baseHolder = navigation_exports.ApiDefinitionHolder.create(baseApi);
+    const translatedHolder = navigation_exports.ApiDefinitionHolder.create(translatedApi);
+    const resolveEndpoint = buildResolverForKind(baseHolder.endpoints, translatedHolder.endpoints, endpointLocator, (endpoint3) => nonEmptyTitle(endpoint3.name));
+    const resolveWebhook = buildResolverForKind(baseHolder.webhooks, translatedHolder.webhooks, webhookLocator, (webhook) => nonEmptyTitle(webhook.name));
+    const resolveWebSocket = buildResolverForKind(baseHolder.webSockets, translatedHolder.webSockets, webSocketLocator, (webSocket) => nonEmptyTitle(webSocket.name));
+    const graphqlTitlesById = /* @__PURE__ */ new Map();
+    for (const [id, operation] of translatedHolder.graphqlOperations) {
+      const name2 = operation.displayName ?? operation.name;
+      const title2 = nonEmptyTitle(name2);
+      if (title2 != null) {
+        graphqlTitlesById.set(id, title2);
       }
     }
-    mapsByApiId.set(apiId, { endpoints, webhooks: webhooks2, webSockets, graphql: graphql4, packagesByBaseTitle });
+    resolvers.set(apiId, {
+      resolveEndpoint,
+      resolveWebhook,
+      resolveWebSocket,
+      graphqlTitlesById,
+      packagesByBaseTitle: buildPackagesByBaseTitle(baseApi, translatedApi)
+    });
   }
-  const clone5 = structuredClone(root6);
-  const visit5 = (node4) => {
-    if (node4 == null || typeof node4 !== "object") {
+  return resolvers;
+}
+function getApiDefinitionId(node4) {
+  return typeof node4.apiDefinitionId === "string" ? node4.apiDefinitionId : void 0;
+}
+function visitNavigationNodes(node4, callback) {
+  if (node4 == null || typeof node4 !== "object") {
+    return;
+  }
+  if (Array.isArray(node4)) {
+    for (const item of node4) {
+      visitNavigationNodes(item, callback);
+    }
+    return;
+  }
+  const obj = node4;
+  callback(obj);
+  for (const value2 of Object.values(obj)) {
+    visitNavigationNodes(value2, callback);
+  }
+}
+function findIncompatibleTranslatedApiIds(root6, baseApis, translatedApis) {
+  const incompatible = /* @__PURE__ */ new Set();
+  for (const apiId of Object.keys(translatedApis)) {
+    if (baseApis[apiId] == null) {
+      incompatible.add(apiId);
+    }
+  }
+  if (root6 == null) {
+    return incompatible;
+  }
+  const resolvers = buildApiTranslationResolvers(baseApis, translatedApis);
+  visitNavigationNodes(root6, (obj) => {
+    const apiDefinitionId = getApiDefinitionId(obj);
+    if (apiDefinitionId == null || incompatible.has(apiDefinitionId)) {
+      return;
+    }
+    const resolver2 = resolvers.get(apiDefinitionId);
+    if (resolver2 == null) {
       return;
     }
-    if (Array.isArray(node4)) {
-      for (const item of node4) {
-        visit5(item);
+    const type7 = obj.type;
+    if (type7 === "endpoint" && typeof obj.endpointId === "string") {
+      if (resolver2.resolveEndpoint(obj.endpointId) == null) {
+        incompatible.add(apiDefinitionId);
+      }
+    } else if (type7 === "webhook" && typeof obj.webhookId === "string") {
+      if (resolver2.resolveWebhook(obj.webhookId) == null) {
+        incompatible.add(apiDefinitionId);
+      }
+    } else if (type7 === "webSocket" && typeof obj.webSocketId === "string") {
+      if (resolver2.resolveWebSocket(obj.webSocketId) == null) {
+        incompatible.add(apiDefinitionId);
       }
+    }
+  });
+  return incompatible;
+}
+function applyTranslatedApiTitlesToNavTree(root6, baseApis, translatedApis, options2) {
+  const resolvers = buildApiTranslationResolvers(baseApis, translatedApis);
+  const rewritableApiIds = options2?.rewritableApiIds;
+  const canRewriteIds = (apiDefinitionId) => rewritableApiIds == null || rewritableApiIds.has(apiDefinitionId);
+  const clone5 = structuredClone(root6);
+  visitNavigationNodes(clone5, (obj) => {
+    const apiDefinitionId = getApiDefinitionId(obj);
+    const resolver2 = apiDefinitionId != null ? resolvers.get(apiDefinitionId) : void 0;
+    if (resolver2 == null || apiDefinitionId == null) {
       return;
     }
-    const obj = node4;
-    const apiDefinitionId = typeof obj.apiDefinitionId === "string" ? obj.apiDefinitionId : void 0;
-    const maps = apiDefinitionId != null ? mapsByApiId.get(apiDefinitionId) : void 0;
-    if (maps != null) {
-      const type7 = obj.type;
-      if (type7 === "endpoint" && typeof obj.endpointId === "string") {
-        const translated = maps.endpoints.get(obj.endpointId);
-        if (translated != null) {
-          obj.title = translated;
+    const rewriteIds = canRewriteIds(apiDefinitionId);
+    const type7 = obj.type;
+    if (type7 === "endpoint" && typeof obj.endpointId === "string") {
+      const match3 = resolver2.resolveEndpoint(obj.endpointId);
+      if (match3 != null) {
+        if (rewriteIds) {
+          obj.endpointId = match3.translatedId;
         }
-      } else if (type7 === "webhook" && typeof obj.webhookId === "string") {
-        const translated = maps.webhooks.get(obj.webhookId);
-        if (translated != null) {
-          obj.title = translated;
+        if (match3.title != null) {
+          obj.title = match3.title;
         }
-      } else if (type7 === "webSocket" && typeof obj.webSocketId === "string") {
-        const translated = maps.webSockets.get(obj.webSocketId);
-        if (translated != null) {
-          obj.title = translated;
+      }
+    } else if (type7 === "webhook" && typeof obj.webhookId === "string") {
+      const match3 = resolver2.resolveWebhook(obj.webhookId);
+      if (match3 != null) {
+        if (rewriteIds) {
+          obj.webhookId = match3.translatedId;
         }
-      } else if (type7 === "graphql" && typeof obj.graphqlOperationId === "string") {
-        const translated = maps.graphql.get(obj.graphqlOperationId);
-        if (translated != null) {
-          obj.title = translated;
+        if (match3.title != null) {
+          obj.title = match3.title;
         }
-      } else if (type7 === "apiPackage" && typeof obj.title === "string") {
-        const translated = maps.packagesByBaseTitle.get(obj.title);
-        if (translated != null) {
-          obj.title = translated;
+      }
+    } else if (type7 === "webSocket" && typeof obj.webSocketId === "string") {
+      const match3 = resolver2.resolveWebSocket(obj.webSocketId);
+      if (match3 != null) {
+        if (rewriteIds) {
+          obj.webSocketId = match3.translatedId;
+        }
+        if (match3.title != null) {
+          obj.title = match3.title;
         }
       }
+    } else if (type7 === "graphql" && typeof obj.graphqlOperationId === "string") {
+      const translated = resolver2.graphqlTitlesById.get(obj.graphqlOperationId);
+      if (translated != null) {
+        obj.title = translated;
+      }
+    } else if (type7 === "apiPackage" && typeof obj.title === "string") {
+      const translated = resolver2.packagesByBaseTitle.get(obj.title);
+      if (translated != null) {
+        obj.title = translated;
+      }
     }
-    for (const value2 of Object.values(obj)) {
-      visit5(value2);
-    }
-  };
-  visit5(clone5);
+  });
   return clone5;
 }
 var init_applyTranslatedApiTitlesToNavTree = __esm({
@@ -686827,7 +686956,7 @@ var AccessTokenPosthogManager = class {
         properties: {
           ...event,
           ...event.properties,
-          version: "5.23.3-1008-g29939b6a08a",
+          version: "5.23.3-1013-g60e2acea243",
           usingAccessToken: true,
           ...getRunIdProperties()
         }
@@ -686893,7 +687022,7 @@ var UserPosthogManager = class {
       distinctId: this.userId ?? await this.getPersistedDistinctId(),
       event: "CLI",
       properties: {
-        version: "5.23.3-1008-g29939b6a08a",
+        version: "5.23.3-1013-g60e2acea243",
         ...event,
         ...event.properties,
         usingAccessToken: false,
@@ -867987,7 +868116,7 @@ var LOCAL_STORAGE_FOLDER4 = ".fern-dev";
 var LOGS_FOLDER_NAME = "logs";
 var MAX_LOGS_DIR_SIZE_BYTES = 100 * 1024 * 1024;
 function getCliSource() {
-  const version7 = "5.23.3-1008-g29939b6a08a";
+  const version7 = "5.23.3-1013-g60e2acea243";
   return `cli@${version7}`;
 }
 var DebugLogger = class {
@@ -871636,10 +871765,24 @@ async function runAppPreviewServer({ initialProject, reloadProject, validateProj
             translatedNavbarLinks = localeNavOverlay.navbarLinks;
           }
         }
+        const baseApis = docsDefinition.apis;
         const localeApis = translatedApiDefinitions?.[locale];
-        const translatedApis = localeApis != null ? { ...docsDefinition.apis, ...localeApis } : docsDefinition.apis;
+        let servedLocaleApis = localeApis;
+        let rewritableApiIds;
         if (localeApis != null && updatedRoot != null) {
-          updatedRoot = applyTranslatedApiTitlesToNavTree(updatedRoot, docsDefinition.apis, localeApis);
+          const incompatibleApiIds = findIncompatibleTranslatedApiIds(updatedRoot, baseApis, localeApis);
+          if (incompatibleApiIds.size > 0) {
+            context3.logger.warn(`Translated API definition(s) [${Array.from(incompatibleApiIds).join(", ")}] for locale "${locale}" diverge from the default-locale spec (e.g. changed OpenAPI tag names, operationIds, or paths, or a missing/added endpoint), so they can't be fully matched to the navigation tree. Serving the default-locale API for those (localized sidebar titles are still applied where they can be matched). For fully localized API reference content, translate only human-readable text and keep tag names/operationIds/paths identical to the base spec.`);
+            servedLocaleApis = Object.fromEntries(Object.entries(localeApis).filter(([apiId]) => !incompatibleApiIds.has(apiId)));
+          }
+          rewritableApiIds = new Set(Object.keys(localeApis).filter((apiId) => !incompatibleApiIds.has(apiId)));
+        }
+        const hasServedLocaleApis = servedLocaleApis != null && Object.keys(servedLocaleApis).length > 0;
+        const translatedApis = hasServedLocaleApis ? { ...docsDefinition.apis, ...servedLocaleApis } : docsDefinition.apis;
+        if (localeApis != null && Object.keys(localeApis).length > 0 && updatedRoot != null) {
+          updatedRoot = applyTranslatedApiTitlesToNavTree(updatedRoot, baseApis, localeApis, {
+            rewritableApiIds
+          });
         }
         const translatedDefinition = {
           ...docsDefinition,
@@ -898817,8 +898960,19 @@ async function buildAllTranslationInputs({ docsDefinition, git, apiDefinitions,
             }
           }
         }
+        const incompatibleApiIds = findIncompatibleTranslatedApiIds(translatedDefinition.config.root, baseReadApis, translatedApisForTitles);
+        if (incompatibleApiIds.size > 0) {
+          context3.logger.warn(`Translated API definition(s) [${Array.from(incompatibleApiIds).join(", ")}] for locale "${locale}" diverge from the default-locale spec (e.g. changed OpenAPI tag names, operationIds, or paths, or a missing/added endpoint), so they can't be fully matched to the navigation tree. Serving the default-locale API for those (localized sidebar titles are still applied where they can be matched). For fully localized API reference content, translate only human-readable text and keep tag names/operationIds/paths identical to the base spec.`);
+          for (const apiId of incompatibleApiIds) {
+            const baseDef = apiDefinitions.get(apiId);
+            if (baseDef != null) {
+              localeApiDefinitions.set(apiId, baseDef);
+            }
+          }
+        }
+        const rewritableApiIds = new Set(Object.keys(translatedApisForTitles).filter((apiId) => !incompatibleApiIds.has(apiId)));
         if (Object.keys(translatedApisForTitles).length > 0) {
-          translatedDefinition.config.root = applyTranslatedApiTitlesToNavTree(translatedDefinition.config.root, baseReadApis, translatedApisForTitles);
+          translatedDefinition.config.root = applyTranslatedApiTitlesToNavTree(translatedDefinition.config.root, baseReadApis, translatedApisForTitles, { rewritableApiIds });
         }
       }
     }
@@ -899562,8 +899716,16 @@ ${JSON.stringify(errorDetails, void 0, 2)}`);
                 translatedApisForTitles[baseApiId] = translatedRead;
               }
             }
-            updatedRoot = Object.keys(translatedApisForTitles).length > 0 ? applyTranslatedApiTitlesToNavTree(updatedRoot, baseApisForTitles, translatedApisForTitles) : structuredClone(updatedRoot);
+            const incompatibleApiIds = findIncompatibleTranslatedApiIds(updatedRoot, baseApisForTitles, translatedApisForTitles);
+            if (incompatibleApiIds.size > 0) {
+              context3.logger.warn(`Translated API definition(s) [${Array.from(incompatibleApiIds).join(", ")}] for locale "${locale}" diverge from the default-locale spec (e.g. changed OpenAPI tag names, operationIds, or paths, or a missing/added endpoint), so they can't be fully matched to the navigation tree. Serving the default-locale API for those (localized sidebar titles are still applied where they can be matched). For fully localized API reference content, translate only human-readable text and keep tag names/operationIds/paths identical to the base spec.`);
+            }
+            const rewritableApiIds = new Set(Object.keys(translatedApisForTitles).filter((apiId) => !incompatibleApiIds.has(apiId)));
+            updatedRoot = Object.keys(translatedApisForTitles).length > 0 ? applyTranslatedApiTitlesToNavTree(updatedRoot, baseApisForTitles, translatedApisForTitles, { rewritableApiIds }) : structuredClone(updatedRoot);
             for (const [baseApiId, translatedApiId] of localeApiIdMap) {
+              if (incompatibleApiIds.has(baseApiId)) {
+                continue;
+              }
               updateApiDefinitionIdInTree(updatedRoot, baseApiId, translatedApiId);
             }
           }
@@ -900207,11 +900369,13 @@ async function runRemoteGenerationForDocsWorkspace({ organization, apiWorkspaces
     context3.failAndThrow(`More than one docs instances. Please specify one (e.g. --instance ${instances2[0]?.url})`, void 0, { code: CliError.Code.ConfigError });
     return;
   }
-  const maybeInstance = instances2.find((instance) => instance.url === instanceUrl) ?? instances2[0];
+  const maybeInstance = instanceUrl != null ? instances2.find((instance) => instance.url === instanceUrl) : instances2[0];
   if (maybeInstance == null) {
-    context3.failAndThrow(`No docs instance with url ${instanceUrl}. Failed to register.`, void 0, {
-      code: CliError.Code.ConfigError
-    });
+    const available = instances2.map((inst) => `  - ${inst.url}`).join("\n");
+    context3.failAndThrow(instanceUrl != null ? `No docs instance found matching '${instanceUrl}'.
+
+Available instances:
+${available}` : `No docs instance found. Failed to register.`, void 0, { code: CliError.Code.ConfigError });
     return;
   }
   const customDomains = (typeof maybeInstance.customDomain === "string" ? [maybeInstance.customDomain] : maybeInstance.customDomain ?? []).map(stripCustomDomainProtocol);
@@ -900306,7 +900470,7 @@ var LegacyDocsPublisher = class {
         previewId,
         disableTemplates: void 0,
         skipUpload,
-        cliVersion: "5.23.3-1008-g29939b6a08a",
+        cliVersion: "5.23.3-1013-g60e2acea243",
         loginCommand: "fern auth login"
       });
       if (taskContext.getResult() === TaskResult.Failure) {
@@ -966575,7 +966739,7 @@ function getAutomationContextFromEnv() {
     config_branch: process.env.FERN_CONFIG_BRANCH,
     config_pr_number: process.env.FERN_CONFIG_PR_NUMBER,
     trigger: process.env.GITHUB_EVENT_NAME,
-    cli_version: "5.23.3-1008-g29939b6a08a"
+    cli_version: "5.23.3-1013-g60e2acea243"
   };
 }
 function isAutomationMode() {
@@ -967407,7 +967571,7 @@ var CliContext = class _CliContext {
     if (false) {
       this.logger.error("CLI_VERSION is not defined");
     }
-    return "5.23.3-1008-g29939b6a08a";
+    return "5.23.3-1013-g60e2acea243";
   }
   getCliName() {
     if (false) {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "5.23.3-1008-g29939b6a08a",
+  "version": "5.23.3-1013-g60e2acea243",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fern-api/fern.git",