@fern-api/fern-api-dev 5.89.5 → 5.90.0

package/cli.cjs

@@ -32839,19 +32839,57 @@ var init_mediaType = __esm({
 
 // ../../commons/core-utils/lib/mergeWithOverrides.js
 function mergeWithOverrides({ data: data2, overrides, allowNullKeys }) {
-  const merged = mergeWith_default(data2, mergeWith_default, overrides, (obj, src) => Array.isArray(obj) && Array.isArray(src) ? src.every((element4) => typeof element4 === "object") && obj.every((element4) => typeof element4 === "object") ? (
-    // nested arrays of objects are merged
-    void 0
-  ) : (
-    // nested arrays of primitives are replaced
-    [...src]
-  ) : void 0);
+  const merged = mergeWith_default(data2, mergeWith_default, overrides, overridesCustomizer);
   const filtered = omitDeepBy(merged, isNull_default, {
     ancestorKeys: allowNullKeys ?? [],
     allowOmissionCursor: false
   });
   return filtered;
 }
+function overridesCustomizer(obj, src) {
+  if (!Array.isArray(obj) || !Array.isArray(src)) {
+    return void 0;
+  }
+  if (!src.every((element4) => typeof element4 === "object") || !obj.every((element4) => typeof element4 === "object")) {
+    return [...src];
+  }
+  return mergeParametersByIdentity(obj, src) ?? void 0;
+}
+function isParameterEntry(value2) {
+  if (!isPlainObject_default(value2)) {
+    return false;
+  }
+  const { name: name2, in: location2 } = value2;
+  return typeof name2 === "string" && typeof location2 === "string";
+}
+function identityOf(entry) {
+  return `${entry.in}:${entry.name}`;
+}
+function mergeParametersByIdentity(obj, src) {
+  if (!obj.every(isParameterEntry) || !src.every(isParameterEntry)) {
+    return void 0;
+  }
+  const unmatchedIndices = /* @__PURE__ */ new Map();
+  obj.forEach((entry, index3) => {
+    const indices = unmatchedIndices.get(identityOf(entry));
+    if (indices != null) {
+      indices.push(index3);
+    } else {
+      unmatchedIndices.set(identityOf(entry), [index3]);
+    }
+  });
+  const merged = [...obj];
+  for (const override of src) {
+    const identity5 = identityOf(override);
+    const matchIndex = unmatchedIndices.get(identity5)?.shift();
+    if (matchIndex == null) {
+      merged.push(override);
+      continue;
+    }
+    merged[matchIndex] = mergeWith_default(obj[matchIndex], override, overridesCustomizer);
+  }
+  return merged;
+}
 var omitDeepBy;
 var init_mergeWithOverrides = __esm({
   "../../commons/core-utils/lib/mergeWithOverrides.js"() {
@@ -118352,7 +118390,8 @@ var init_DocsYmlSchemas = __esm({
     });
     GitLibraryInputSchema = external_exports.object({
       git: external_exports.string(),
-      subpath: external_exports.string().optional()
+      subpath: external_exports.string().optional(),
+      ref: external_exports.string().optional()
     });
     PathLibraryInputSchema = external_exports.object({
       path: external_exports.string()
@@ -123729,7 +123768,8 @@ var init_GitLibraryInputSchema2 = __esm({
     init_core5();
     GitLibraryInputSchema2 = schemas_exports6.object({
       git: schemas_exports6.string(),
-      subpath: schemas_exports6.string().optional()
+      subpath: schemas_exports6.string().optional(),
+      ref: schemas_exports6.string().optional()
     });
   }
 });
@@ -165758,7 +165798,7 @@ function convertParameters({ path: path120, httpMethod, parameters: parameters2,
     const convertedParameter = {
       name: resolvedParameter.name,
       schema,
-      description: resolvedParameter.description,
+      description: getParameterDescription(resolvedParameter),
       parameterNameOverride: getParameterName(resolvedParameter),
       availability,
       source: source2,
@@ -165787,6 +165827,15 @@ function convertParameters({ path: path120, httpMethod, parameters: parameters2,
   }
   return convertedParameters;
 }
+function getParameterDescription(parameter6) {
+  if (parameter6.description != null) {
+    return parameter6.description;
+  }
+  if (parameter6.schema == null || isReferenceObject(parameter6.schema)) {
+    return void 0;
+  }
+  return parameter6.schema.description;
+}
 function getExplodeForQueryParameter(parameter6) {
   const style2 = parameter6.style ?? "form";
   const explode = parameter6.explode;
@@ -235585,7 +235634,7 @@ function parseLibrariesConfiguration(libraries) {
   }
   const result = {};
   for (const [name2, config5] of Object.entries(libraries)) {
-    const input3 = isGitLibraryInput(config5.input) ? { type: "git", git: config5.input.git, subpath: config5.input.subpath } : { type: "path", path: config5.input.path };
+    const input3 = isGitLibraryInput(config5.input) ? { type: "git", git: config5.input.git, subpath: config5.input.subpath, ref: config5.input.ref } : { type: "path", path: config5.input.path };
     result[name2] = {
       input: input3,
       output: {
@@ -568242,6 +568291,7 @@ var require_VersionUtils = __commonJS({
     exports2.maxVersionBump = maxVersionBump3;
     exports2.isAutoVersion = isAutoVersion5;
     exports2.isValidSemver = isValidSemver;
+    exports2.isPlaceholderVersion = isPlaceholderVersion2;
     exports2.incrementVersion = incrementVersion;
     exports2.extractPreviousVersionFromDiffLine = extractPreviousVersionFromDiffLine;
     var semver_1 = __importDefault2(require_semver2());
@@ -568321,11 +568371,18 @@ var require_VersionUtils = __commonJS({
     function isValidSemver(version7) {
       return SEMVER_PATTERN.test(version7);
     }
+    function isPlaceholderVersion2(version7) {
+      const withoutPrefix = version7.startsWith("v") ? version7.slice(1) : version7;
+      return withoutPrefix === exports2.MAGIC_VERSION || withoutPrefix.startsWith(`${exports2.MAGIC_VERSION}.`) || withoutPrefix === exports2.MAGIC_VERSION_PYTHON || withoutPrefix.startsWith(`${exports2.MAGIC_VERSION_PYTHON}.`);
+    }
     function incrementVersion(currentVersion, versionBump) {
       const matcher = currentVersion.match(SEMVER_PATTERN);
       if (!matcher) {
         throw new AutoVersioningService_js_1.AutoVersioningException("Invalid semantic version format: " + currentVersion);
       }
+      if (isPlaceholderVersion2(currentVersion)) {
+        throw new AutoVersioningService_js_1.AutoVersioningException("Refusing to increment the magic placeholder version: " + currentVersion + ". A real previous version must be resolved first.");
+      }
       const prefix2 = matcher[1] ?? "";
       const versionWithoutPrefix = currentVersion.slice(prefix2.length);
       const preRelease = matcher[5];
@@ -568366,7 +568423,7 @@ var require_autoversion = __commonJS({
   "../../generator-cli/lib/autoversion/index.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.VersionBump = exports2.maxVersionBump = exports2.mapMagicVersionForLanguage = exports2.MAX_RAW_DIFF_BYTES = exports2.MAX_CHUNKS = exports2.MAX_AI_DIFF_BYTES = exports2.MAGIC_VERSION_PYTHON = exports2.MAGIC_VERSION = exports2.isValidSemver = exports2.isAutoVersion = exports2.incrementVersion = exports2.extractPreviousVersionFromDiffLine = exports2.extractLanguageFromGeneratorName = exports2.AUTO_VERSION = exports2.prependChangelogBlock = exports2.changelogContainsVersion = exports2.formatSizeKB = exports2.countFilesInDiff = exports2.AutoVersioningService = exports2.AutoVersioningException = exports2.AutoVersioningCache = void 0;
+    exports2.VersionBump = exports2.maxVersionBump = exports2.mapMagicVersionForLanguage = exports2.MAX_RAW_DIFF_BYTES = exports2.MAX_CHUNKS = exports2.MAX_AI_DIFF_BYTES = exports2.MAGIC_VERSION_PYTHON = exports2.MAGIC_VERSION = exports2.isValidSemver = exports2.isPlaceholderVersion = exports2.isAutoVersion = exports2.incrementVersion = exports2.extractPreviousVersionFromDiffLine = exports2.extractLanguageFromGeneratorName = exports2.AUTO_VERSION = exports2.prependChangelogBlock = exports2.changelogContainsVersion = exports2.formatSizeKB = exports2.countFilesInDiff = exports2.AutoVersioningService = exports2.AutoVersioningException = exports2.AutoVersioningCache = void 0;
     var AutoVersioningCache_js_1 = require_AutoVersioningCache();
     Object.defineProperty(exports2, "AutoVersioningCache", { enumerable: true, get: function() {
       return AutoVersioningCache_js_1.AutoVersioningCache;
@@ -568407,6 +568464,9 @@ var require_autoversion = __commonJS({
     Object.defineProperty(exports2, "isAutoVersion", { enumerable: true, get: function() {
       return VersionUtils_js_1.isAutoVersion;
     } });
+    Object.defineProperty(exports2, "isPlaceholderVersion", { enumerable: true, get: function() {
+      return VersionUtils_js_1.isPlaceholderVersion;
+    } });
     Object.defineProperty(exports2, "isValidSemver", { enumerable: true, get: function() {
       return VersionUtils_js_1.isValidSemver;
     } });
@@ -569237,7 +569297,8 @@ var require_AutoVersionStep = __commonJS({
       }
       async handleFirstGeneration(params2) {
         const { service, language, mappedMagicVersion, commit } = params2;
-        const initialVersion = this.config.baseVersion ?? (mappedMagicVersion.startsWith("v") ? "v0.0.1" : "0.0.1");
+        const configuredBaseVersion = this.usableVersion(this.config.baseVersion, "baseVersion");
+        const initialVersion = configuredBaseVersion ?? (mappedMagicVersion.startsWith("v") ? "v0.0.1" : "0.0.1");
         if (!(0, index_1.isValidSemver)(initialVersion)) {
           const errorMessage = `AutoVersionStep: baseVersion ${JSON.stringify(initialVersion)} is not a valid semver string (expected e.g. "1.2.3" or "v1.2.3"). Refusing to run.`;
           this.logger.error(errorMessage);
@@ -569547,12 +569608,13 @@ var require_AutoVersionStep = __commonJS({
        */
       async resolvePreviousVersionNonReplay(params2) {
         const { service, rawDiff, mappedMagicVersion, baseVersion } = params2;
-        if (baseVersion != null && (0, index_1.isValidSemver)(baseVersion)) {
-          this.logger.debug(`AutoVersionStep (non-replay): previous version from pipeline baseVersion: ${baseVersion}`);
-          return this.normalizeVersionPrefix(baseVersion, mappedMagicVersion);
+        const usableBaseVersion = this.usableVersion(baseVersion, "baseVersion");
+        if (usableBaseVersion != null && (0, index_1.isValidSemver)(usableBaseVersion)) {
+          this.logger.debug(`AutoVersionStep (non-replay): previous version from pipeline baseVersion: ${usableBaseVersion}`);
+          return this.normalizeVersionPrefix(usableBaseVersion, mappedMagicVersion);
         }
         try {
-          const extracted = service.extractPreviousVersion(rawDiff, mappedMagicVersion);
+          const extracted = this.usableVersion(service.extractPreviousVersion(rawDiff, mappedMagicVersion) ?? void 0, "diff");
           if (extracted != null) {
             this.logger.debug(`AutoVersionStep (non-replay): previous version from diff: ${extracted}`);
             return extracted;
@@ -569563,12 +569625,12 @@ var require_AutoVersionStep = __commonJS({
           }
           this.logger.info("AutoVersionStep (non-replay): magic version not in diff; trying metadata + git tags.");
         }
-        const metadataVersion = this.readVersionFromMetadataAtHead();
+        const metadataVersion = this.usableVersion(this.readVersionFromMetadataAtHead(), "metadata.json");
         if (metadataVersion != null) {
           return this.normalizeVersionPrefix(metadataVersion, mappedMagicVersion);
         }
         try {
-          const tagVersion = await service.getLatestVersionFromGitTags(this.outputDir);
+          const tagVersion = this.usableVersion(await service.getLatestVersionFromGitTags(this.outputDir) ?? void 0, "git tags");
           if (tagVersion != null) {
             return this.normalizeVersionPrefix(tagVersion, mappedMagicVersion);
           }
@@ -569579,12 +569641,13 @@ var require_AutoVersionStep = __commonJS({
       }
       async resolvePreviousVersion(params2) {
         const { service, rawDiff, mappedMagicVersion, baseVersion } = params2;
-        if (baseVersion != null && (0, index_1.isValidSemver)(baseVersion)) {
-          this.logger.debug(`AutoVersionStep: previous version from pipeline baseVersion: ${baseVersion}`);
-          return this.normalizeVersionPrefix(baseVersion, mappedMagicVersion);
+        const usableBaseVersion = this.usableVersion(baseVersion, "baseVersion");
+        if (usableBaseVersion != null && (0, index_1.isValidSemver)(usableBaseVersion)) {
+          this.logger.debug(`AutoVersionStep: previous version from pipeline baseVersion: ${usableBaseVersion}`);
+          return this.normalizeVersionPrefix(usableBaseVersion, mappedMagicVersion);
         }
         try {
-          const extracted = service.extractPreviousVersion(rawDiff, mappedMagicVersion);
+          const extracted = this.usableVersion(service.extractPreviousVersion(rawDiff, mappedMagicVersion) ?? void 0, "diff");
           if (extracted != null) {
             this.logger.debug(`AutoVersionStep: previous version from diff: ${extracted}`);
             return extracted;
@@ -569595,12 +569658,12 @@ var require_AutoVersionStep = __commonJS({
           }
           this.logger.info("AutoVersionStep: magic version not found in diff; falling back to metadata + git tags.");
         }
-        const metadataVersion = await this.readVersionFromMetadata();
+        const metadataVersion = this.usableVersion(await this.readVersionFromMetadata(), "metadata.json");
         if (metadataVersion != null) {
           return this.normalizeVersionPrefix(metadataVersion, mappedMagicVersion);
         }
         try {
-          const tagVersion = await service.getLatestVersionFromGitTags(this.outputDir);
+          const tagVersion = this.usableVersion(await service.getLatestVersionFromGitTags(this.outputDir) ?? void 0, "git tags");
           if (tagVersion != null) {
             return this.normalizeVersionPrefix(tagVersion, mappedMagicVersion);
           }
@@ -569622,6 +569685,25 @@ var require_AutoVersionStep = __commonJS({
           return void 0;
         }
       }
+      /**
+       * Drops candidate previous versions that are the magic placeholder. SDK repos
+       * that derive their published version at release time keep the placeholder
+       * committed, so every resolution source (baseVersion, diff extraction,
+       * metadata.json, git tags) can hand back the sentinel; incrementing it would
+       * emit a mutated placeholder such as `0.0.0-fern-placeholder.0` instead of a
+       * real version. Returning undefined lets the caller fall through to the next
+       * source, and ultimately to the first-generation path.
+       */
+      usableVersion(version7, source2) {
+        if (version7 == null) {
+          return void 0;
+        }
+        if ((0, index_1.isPlaceholderVersion)(version7)) {
+          this.logger.info(`AutoVersionStep: ignoring placeholder version ${version7} from ${source2}; trying the next previous-version source.`);
+          return void 0;
+        }
+        return version7;
+      }
       normalizeVersionPrefix(version7, mappedMagicVersion) {
         const stripped = version7.startsWith("v") ? version7.slice(1) : version7;
         return mappedMagicVersion.startsWith("v") ? `v${stripped}` : stripped;
@@ -694418,7 +694500,7 @@ var AccessTokenPosthogManager = class {
         properties: {
           ...event,
           ...event.properties,
-          version: "5.89.5",
+          version: "5.90.0",
           usingAccessToken: true,
           ...getRunIdProperties()
         }
@@ -694484,7 +694566,7 @@ var UserPosthogManager = class {
       distinctId: this.userId ?? await this.getPersistedDistinctId(),
       event: "CLI",
       properties: {
-        version: "5.89.5",
+        version: "5.90.0",
         ...event,
         ...event.properties,
         usingAccessToken: false,
@@ -875614,7 +875696,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.89.5";
+  const version7 = "5.90.0";
   return `cli@${version7}`;
 }
 var DebugLogger = class {
@@ -896131,13 +896213,14 @@ async function generateIrRemotely({ client: client3, name: name2, config: config
   }
   const gitInput = config5.input;
   const jobId = await wrapStep({
-    message: `Library '${name2}': starting generation from ${gitInput.git}`,
+    message: `Library '${name2}': starting generation from ${gitInput.git}${gitInput.ref != null ? ` (ref: ${gitInput.ref})` : ""}`,
     operation: () => startGeneration(client3, {
       name: name2,
       orgId,
       githubUrl: gitInput.git,
       language,
       packagePath: gitInput.subpath,
+      ref: gitInput.ref,
       doxyfileContent
     })
   });
@@ -896172,7 +896255,8 @@ async function startGeneration(client3, opts) {
       githubUrl: opts.githubUrl,
       language: opts.language,
       config: {
-        branch: void 0,
+        // FDR's library-docs API accepts any git ref (branch, tag, or SHA) via `branch`.
+        branch: opts.ref,
         packagePath: opts.packagePath,
         title: opts.name,
         slug: opts.name,
@@ -898336,6 +898420,17 @@ var definitions6 = {
           }
         ],
         description: "Optional path within the repository to the library source.\nExample: django/core"
+      },
+      ref: {
+        oneOf: [
+          {
+            type: "string"
+          },
+          {
+            type: "null"
+          }
+        ],
+        description: "Git ref (branch, tag, or commit SHA) to check out.\nDefaults to the repository's default branch when omitted.\nExample: feature/my-fix"
       }
     },
     required: [
@@ -908324,7 +908419,7 @@ var LegacyDocsPublisher = class {
         previewId,
         disableTemplates: void 0,
         skipUpload,
-        cliVersion: "5.89.5",
+        cliVersion: "5.90.0",
         loginCommand: "fern auth login"
       });
       if (taskContext.getResult() === TaskResult.Failure) {
@@ -961942,16 +962037,16 @@ var LocalTaskHandler = class {
       }
       let previousVersion;
       try {
-        previousVersion = autoVersioningService.extractPreviousVersion(diffContent, mappedMagicVersion);
+        previousVersion = this.usableVersion(autoVersioningService.extractPreviousVersion(diffContent, mappedMagicVersion) ?? void 0, "diff");
       } catch (e2) {
         if (!(e2 instanceof import_autoversion2.AutoVersioningException) || !e2.magicVersionAbsent) {
           throw e2;
         }
         this.context.logger.info(`Magic version not found in diff, trying fallbacks: ${e2}`);
-        previousVersion = await this.getVersionFromLocalMetadata();
+        previousVersion = this.usableVersion(await this.getVersionFromLocalMetadata(), "metadata.json");
         if (previousVersion == null) {
           const tagVersion = await autoVersioningService.getLatestVersionFromGitTags(this.absolutePathToLocalOutput);
-          previousVersion = this.normalizeVersionPrefix(tagVersion);
+          previousVersion = this.usableVersion(this.normalizeVersionPrefix(tagVersion), "git tags");
         }
         if (previousVersion == null) {
           this.context.logger.info("No git tags found \u2014 treating as new SDK repository");
@@ -961971,10 +962066,10 @@ var LocalTaskHandler = class {
       const cleanedFileCount = (0, import_autoversion2.countFilesInDiff)(cleanedDiff);
       this.context.logger.debug(`Generated diff size: ${rawDiffSizeKB}KB (${diffContent.length} chars), ${rawFileCount} files changed. Cleaned diff size: ${cleanedDiffSizeKB}KB (${cleanedDiff.length} chars), ${cleanedFileCount} files remaining`);
       if (previousVersion == null) {
-        previousVersion = await this.getVersionFromLocalMetadata();
+        previousVersion = this.usableVersion(await this.getVersionFromLocalMetadata(), "metadata.json");
         if (previousVersion == null) {
           const rawTagVersion = await autoVersioningService.getLatestVersionFromGitTags(this.absolutePathToLocalOutput);
-          const normalizedTag = this.normalizeVersionPrefix(rawTagVersion);
+          const normalizedTag = this.usableVersion(this.normalizeVersionPrefix(rawTagVersion), "git tags");
           if (normalizedTag != null) {
             this.context.logger.info(`No previous version from diff; using git tag: ${normalizedTag}`);
             previousVersion = normalizedTag;
@@ -962244,6 +962339,24 @@ var LocalTaskHandler = class {
       return void 0;
     }
   }
+  /**
+   * Drops candidate previous versions that are the magic placeholder. SDK repos
+   * that derive their published version at release time keep the placeholder
+   * committed, so any resolution source can hand back the sentinel; bumping it
+   * would publish a mutated placeholder rather than a real version. Returning
+   * undefined lets the caller fall through to the next source, and ultimately to
+   * the initial-version path.
+   */
+  usableVersion(version7, source2) {
+    if (version7 == null) {
+      return void 0;
+    }
+    if ((0, import_autoversion2.isPlaceholderVersion)(version7)) {
+      this.context.logger.info(`Ignoring placeholder version ${version7} from ${source2}; trying the next previous-version source.`);
+      return void 0;
+    }
+    return version7;
+  }
   /**
    * Normalizes a version string's `v` prefix to match the convention used by
    * the magic version for this generator's language. Git tags may use `v1.2.3`
@@ -975214,7 +975327,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.89.5"
+    cli_version: "5.90.0"
   };
 }
 function isAutomationMode() {
@@ -976046,7 +976159,7 @@ var CliContext = class _CliContext {
     if (false) {
       this.logger.error("CLI_VERSION is not defined");
     }
-    return "5.89.5";
+    return "5.90.0";
   }
   getCliName() {
     if (false) {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "5.89.5",
+  "version": "5.90.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fern-api/fern.git",