@fern-api/fern-api-dev 5.75.3 → 5.75.5

package/cli.cjs

@@ -691149,7 +691149,7 @@ var AccessTokenPosthogManager = class {
         properties: {
           ...event,
           ...event.properties,
-          version: "5.75.3",
+          version: "5.75.5",
           usingAccessToken: true,
           ...getRunIdProperties()
         }
@@ -691215,7 +691215,7 @@ var UserPosthogManager = class {
       distinctId: this.userId ?? await this.getPersistedDistinctId(),
       event: "CLI",
       properties: {
-        version: "5.75.3",
+        version: "5.75.5",
         ...event,
         ...event.properties,
         usingAccessToken: false,
@@ -866515,7 +866515,9 @@ var ValidMarkdownRule = {
           const message = markdownParseResult.message != null ? `Markdown failed to parse: ${markdownParseResult.message}` : "Markdown failed to parse";
           return [
             {
-              severity: "fatal",
+              // Surfaced as a warning (not an error) so re-enabling this rule does not
+              // suddenly break existing `fern check` runs on repos with latent MDX issues.
+              severity: "warning",
               message
             }
           ];
@@ -868492,6 +868494,8 @@ var allRules = [
   // Check non-component references (will skip v2 files)
   ValidLocalReferencesRule,
   // Validate that local references actually exist
+  ValidMarkdownRule,
+  // Compile each page's MDX and surface syntax errors (e.g. unclosed components)
   NavigationConflicts,
   ValidateVersionFileRule,
   ValidateProductFileRule,
@@ -872316,7 +872320,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.75.3";
+  const version7 = "5.75.5";
   return `cli@${version7}`;
 }
 var DebugLogger = class {
@@ -875594,6 +875598,8 @@ var SnippetDependencyTracker = class {
   snippetToPages = /* @__PURE__ */ new Map();
   // Map: page file path -> Set of snippet files it references
   pageToSnippets = /* @__PURE__ */ new Map();
+  // Whether a full scan has populated the maps at least once.
+  hasBuiltInitialMap = false;
   constructor(context3) {
     this.context = context3;
   }
@@ -875639,21 +875645,77 @@ var SnippetDependencyTracker = class {
           const content5 = await (0, import_promises101.readFile)(markdownFile, "utf-8");
           const referencedFiles = this.extractReferences(content5, markdownFile, docsWorkspace.absoluteFilePath);
           this.pageToSnippets.set(markdownFile, referencedFiles);
-          for (const referencedFile of referencedFiles) {
-            if (!this.snippetToPages.has(referencedFile)) {
-              this.snippetToPages.set(referencedFile, /* @__PURE__ */ new Set());
-            }
-            this.snippetToPages.get(referencedFile)?.add(markdownFile);
-          }
         } catch (error50) {
           this.context.logger.debug(`Failed to read markdown file ${markdownFile}: ${error50}`);
         }
       }
+      this.rebuildReverseMap();
+      this.hasBuiltInitialMap = true;
       this.context.logger.debug(`Built dependency map: ${this.snippetToPages.size} snippets, ${this.pageToSnippets.size} pages`);
     } catch (error50) {
       this.context.logger.debug(`Failed to build dependency map: ${error50}`);
     }
   }
+  /**
+   * Incrementally updates the dependency maps for a set of changed markdown files,
+   * avoiding a full re-scan of every page in the workspace.
+   *
+   * Only content-only (`.md`/`.mdx`) reloads take this path. For each changed file we
+   * re-read it and recompute its outgoing references (the page -> snippets forward
+   * edge); deleted files are dropped. We then rebuild the snippet -> pages reverse
+   * map from the forward map in memory (no disk I/O), so the reverse map is always
+   * fully consistent with the forward map and can never accumulate stale edges.
+   *
+   * Reloads never overlap (the watcher handler serializes them behind `isReloading`),
+   * so these mutations are not subject to concurrent access. Falls back to a full
+   * scan if an initial map has not been built yet.
+   */
+  async updateDependencyMapForFiles(changedFiles, project) {
+    const docsWorkspace = project.docsWorkspaces;
+    if (!docsWorkspace) {
+      return;
+    }
+    if (!this.hasBuiltInitialMap) {
+      await this.buildDependencyMap(project);
+      return;
+    }
+    for (const changedFile of changedFiles) {
+      const lower = changedFile.toLowerCase();
+      if (!lower.endsWith(".md") && !lower.endsWith(".mdx")) {
+        continue;
+      }
+      if (!await doesPathExist(changedFile)) {
+        this.pageToSnippets.delete(changedFile);
+        continue;
+      }
+      try {
+        const content5 = await (0, import_promises101.readFile)(changedFile, "utf-8");
+        const referencedFiles = this.extractReferences(content5, changedFile, docsWorkspace.absoluteFilePath);
+        this.pageToSnippets.set(changedFile, referencedFiles);
+      } catch (error50) {
+        this.context.logger.debug(`Failed to read markdown file ${changedFile}: ${error50}`);
+        this.pageToSnippets.delete(changedFile);
+      }
+    }
+    this.rebuildReverseMap();
+  }
+  /**
+   * Rebuilds the snippet -> pages (reverse) map from the page -> snippets (forward)
+   * map. A pure in-memory transformation, so it can never leave stale reverse edges.
+   */
+  rebuildReverseMap() {
+    this.snippetToPages.clear();
+    for (const [page, references] of this.pageToSnippets) {
+      for (const reference4 of references) {
+        let pages = this.snippetToPages.get(reference4);
+        if (pages == null) {
+          pages = /* @__PURE__ */ new Set();
+          this.snippetToPages.set(reference4, pages);
+        }
+        pages.add(page);
+      }
+    }
+  }
   /**
    * Find all markdown files in the docs workspace directory
    */
@@ -876074,10 +876136,16 @@ async function runAppPreviewServer({ initialProject, reloadProject, validateProj
     context3.logger.info("Reloading docs...");
     const startTime = Date.now();
     void debugLogger.logCliReloadStart();
+    const contentOnlyEdit = isContentOnlyEdit(editedAbsoluteFilepaths2);
     try {
-      project = await reloadProject();
-      await snippetTracker.buildDependencyMap(project);
-      if (!isContentOnlyEdit(editedAbsoluteFilepaths2)) {
+      if (contentOnlyEdit) {
+        context3.logger.debug("Content-only edit; reusing loaded project (skipping full reload).");
+        await snippetTracker.updateDependencyMapForFiles(editedAbsoluteFilepaths2 ?? [], project);
+      } else {
+        project = await reloadProject();
+        await snippetTracker.buildDependencyMap(project);
+      }
+      if (!contentOnlyEdit) {
         const validationStartTime = Date.now();
         void validateProject(project).then(() => {
           const validationTime = Date.now() - validationStartTime;
@@ -904905,7 +904973,7 @@ var LegacyDocsPublisher = class {
         previewId,
         disableTemplates: void 0,
         skipUpload,
-        cliVersion: "5.75.3",
+        cliVersion: "5.75.5",
         loginCommand: "fern auth login"
       });
       if (taskContext.getResult() === TaskResult.Failure) {
@@ -929238,6 +929306,9 @@ var DynamicTypeInstantiationMapper = class {
             return this.convertLiteralToOptionalPrimitive(named.typeReference.value);
           }
         }
+        if (inner2.type === "literal") {
+          return this.convertLiteralToOptionalPrimitive(inner2.value);
+        }
         return go_exports.TypeInstantiation.optional(this.convert({ typeReference: inner2, value: args.value, as: args.as }));
       }
       case "optional": {
@@ -929262,6 +929333,9 @@ var DynamicTypeInstantiationMapper = class {
             return this.convertLiteralToOptionalPrimitive(named.typeReference.value);
           }
         }
+        if (inner2.type === "literal") {
+          return this.convertLiteralToOptionalPrimitive(inner2.value);
+        }
         return go_exports.TypeInstantiation.optional(this.convert({ typeReference: inner2, value: args.value, as: args.as }));
       }
       case "primitive":
@@ -935486,10 +935560,12 @@ function convertToPhpVariableName(name2) {
 // ../../../generators/php/codegen/lib/ast/Comment.js
 var Comment4 = class extends AstNode4 {
   docs;
+  codeExample;
   tags = [];
-  constructor({ docs: docs2 } = {}) {
+  constructor({ docs: docs2, codeExample } = {}) {
     super();
     this.docs = docs2;
+    this.codeExample = codeExample;
   }
   addTag(tag2) {
     this.tags.push({
@@ -935503,6 +935579,17 @@ var Comment4 = class extends AstNode4 {
       this.docs.split("\n").forEach((line) => {
         writer2.writeLine(` * ${line}`);
       });
+      if (this.codeExample != null || this.tags.length > 0) {
+        writer2.writeLine(" *");
+      }
+    }
+    if (this.codeExample != null) {
+      writer2.writeLine(" * Example:");
+      writer2.writeLine(" * ```php");
+      this.codeExample.split("\n").forEach((line) => {
+        writer2.writeLine(` * ${this.escapeDocs(line)}`.trimEnd());
+      });
+      writer2.writeLine(" * ```");
       if (this.tags.length > 0) {
         writer2.writeLine(" *");
       }
@@ -935512,6 +935599,9 @@ var Comment4 = class extends AstNode4 {
     }
     writer2.writeLine(" */");
   }
+  escapeDocs(line) {
+    return line.replaceAll("*/", "*\\/");
+  }
   writeTag({ writer: writer2, tag: tag2 }) {
     const docsSplit = tag2.docs != null ? tag2.docs.split("\n") : void 0;
     if (docsSplit != null && docsSplit.length > 1) {
@@ -936684,10 +936774,11 @@ var Method4 = class extends AstNode4 {
   return_;
   body;
   docs;
+  codeExample;
   classReference;
   static_;
   noBody;
-  constructor({ name: name2, access: access7, parameters: parameters2, throws, return_, body, docs: docs2, classReference: classReference4, static_, noBody }) {
+  constructor({ name: name2, access: access7, parameters: parameters2, throws, return_, body, docs: docs2, codeExample, classReference: classReference4, static_, noBody }) {
     super();
     this.name = name2;
     this.access = access7;
@@ -936696,6 +936787,7 @@ var Method4 = class extends AstNode4 {
     this.return_ = return_;
     this.body = body;
     this.docs = docs2;
+    this.codeExample = codeExample;
     this.classReference = classReference4;
     this.static_ = static_ ?? false;
     this.noBody = noBody ?? false;
@@ -936729,7 +936821,7 @@ var Method4 = class extends AstNode4 {
     }
   }
   writeComment(writer2) {
-    const comment6 = new Comment4({ docs: this.docs });
+    const comment6 = new Comment4({ docs: this.docs, codeExample: this.codeExample });
     for (const parameter6 of this.parameters) {
       comment6.addTag({
         tagType: "param",
@@ -941726,6 +941818,10 @@ var EndpointSnippetGenerator5 = class {
         assertNever(named);
     }
   }
+  // Whether a type resolves to a literal, treating optional/nullable literals AS literals.
+  // Used for request-body properties and path parameters, which omit ALL literals (required
+  // and optional alike) from the generated method call because they are set internally.
+  // Contrast with resolvesToNonOptionalLiteralType below, which keeps optional literals.
   resolvesToLiteralType(typeReference2) {
     switch (typeReference2.type) {
       case "literal":
@@ -941753,6 +941849,44 @@ var EndpointSnippetGenerator5 = class {
         assertNever(typeReference2);
     }
   }
+  // Whether a type resolves to a REQUIRED literal, i.e. a literal NOT wrapped in optional/nullable.
+  // Used to filter query parameters and headers: a required literal (e.g. response_type="code") is
+  // hardcoded inside the generated method and omitted from its signature, so passing it as a keyword
+  // argument raises TypeError. An optional literal, by contrast, stays in the signature, so it must
+  // remain a valid keyword argument and is kept.
+  //
+  // This deliberately differs from resolvesToLiteralType above in the optional/nullable cases: here
+  // they return false (keep the parameter) instead of recursing. The asymmetry is intentional and is
+  // validated by the literal fixture's wire tests. Note the two cannot be collapsed into a single
+  // guard like `t.type !== "optional" && resolvesToLiteralType(t)`: a named alias whose target is
+  // optional<literal> has top-level type "named", so such a guard would misclassify it as a required
+  // literal and wrongly drop it, whereas recursing through the alias here correctly returns false.
+  resolvesToNonOptionalLiteralType(typeReference2) {
+    switch (typeReference2.type) {
+      case "literal":
+        return true;
+      case "named": {
+        const named = this.context.resolveNamedType({ typeId: typeReference2.value });
+        if (named == null) {
+          return false;
+        }
+        if (named.type === "alias") {
+          return this.resolvesToNonOptionalLiteralType(named.typeReference);
+        }
+        return false;
+      }
+      case "optional":
+      case "nullable":
+      case "list":
+      case "map":
+      case "set":
+      case "primitive":
+      case "unknown":
+        return false;
+      default:
+        assertNever(typeReference2);
+    }
+  }
   getBodyRequestArgsForBytes({ body, value: value2 }) {
     const typeInstantiation = this.getBytesBodyRequestTypeInstantiation({ value: value2 });
     if (python_exports.TypeInstantiation.isNop(typeInstantiation)) {
@@ -941866,7 +942000,7 @@ var EndpointSnippetGenerator5 = class {
       parameters: request7.queryParameters ?? [],
       values: snippet.queryParameters ?? {}
     });
-    const queryParameterFields = queryParameters.map((queryParameter) => ({
+    const queryParameterFields = queryParameters.filter((queryParameter) => !this.resolvesToNonOptionalLiteralType(queryParameter.typeReference)).map((queryParameter) => ({
       name: this.context.getPropertyName(queryParameter.name.name),
       value: this.context.dynamicTypeLiteralMapper.convert(queryParameter)
     }));
@@ -941876,7 +942010,7 @@ var EndpointSnippetGenerator5 = class {
       parameters: request7.headers ?? [],
       values: snippet.headers ?? {}
     });
-    const headerFields = headers2.map((header) => ({
+    const headerFields = headers2.filter((header) => !this.resolvesToNonOptionalLiteralType(header.typeReference)).map((header) => ({
       name: this.context.getPropertyName(header.name.name),
       value: this.context.dynamicTypeLiteralMapper.convert(header)
     }));
@@ -942677,7 +942811,8 @@ var Method6 = class extends AstNode6 {
   statements;
   returnType;
   splatOptionDocs;
-  constructor({ name: name2, docstring, kind, visibility, parameters: parameters2, returnType, statements, splatOptionDocs }) {
+  codeExample;
+  constructor({ name: name2, docstring, kind, visibility, parameters: parameters2, returnType, statements, splatOptionDocs, codeExample }) {
     super();
     this.name = name2;
     this.docstring = docstring;
@@ -942691,6 +942826,7 @@ var Method6 = class extends AstNode6 {
     this.returnType = returnType ?? Type35.untyped();
     this.statements = statements ?? [];
     this.splatOptionDocs = splatOptionDocs ?? [];
+    this.codeExample = codeExample;
   }
   addStatement(statement) {
     this.statements.push(statement);
@@ -942736,8 +942872,18 @@ var Method6 = class extends AstNode6 {
     for (const optionDoc of this.splatOptionDocs) {
       writer2.writeLine(`# ${optionDoc}`);
     }
+    const codeExample = this.codeExample?.trim();
+    if (codeExample) {
+      if (this.docstring || hasAnyParameters || this.splatOptionDocs.length > 0) {
+        writer2.writeLine("#");
+      }
+      writer2.writeLine("# @example");
+      for (const line of codeExample.split("\n")) {
+        writer2.writeLine(line.trim() === "" ? "#" : `#   ${line.trimEnd()}`);
+      }
+    }
     if (this.returnType != null) {
-      if (hasAnyParameters || this.docstring) {
+      if (hasAnyParameters || this.docstring || codeExample) {
         writer2.writeLine("#");
       }
       writer2.write(`# @return [`);
@@ -946179,7 +946325,7 @@ var DocComment = class extends AstNode7 {
   examples;
   constructor({ summary, description, parameters: parameters2, returns, errors: errors4, examples }) {
     super();
-    this.summary = this.sanitizeText(summary);
+    this.summary = summary ? this.sanitizeText(summary) : void 0;
     this.description = description ? this.sanitizeText(description) : void 0;
     this.parameters = (parameters2 ?? []).map((param) => ({
       name: param.name,
@@ -946189,15 +946335,25 @@ var DocComment = class extends AstNode7 {
     this.examples = (examples ?? []).map((e2) => this.sanitizeText(e2));
   }
   write(writer2) {
-    this.writeMultilineText(writer2, this.summary);
+    let hasContent = false;
+    if (this.summary) {
+      this.writeMultilineText(writer2, this.summary);
+      hasContent = true;
+    }
     if (this.description) {
-      writer2.write("///");
-      writer2.newLine();
+      if (hasContent) {
+        writer2.write("///");
+        writer2.newLine();
+      }
       this.writeMultilineText(writer2, this.description);
+      hasContent = true;
     }
     if (this.parameters.length > 0) {
-      writer2.write("///");
-      writer2.newLine();
+      if (hasContent) {
+        writer2.write("///");
+        writer2.newLine();
+      }
+      hasContent = true;
       writer2.write("/// # Arguments");
       writer2.newLine();
       writer2.write("///");
@@ -946215,8 +946371,11 @@ var DocComment = class extends AstNode7 {
       });
     }
     if (this.returns) {
-      writer2.write("///");
-      writer2.newLine();
+      if (hasContent) {
+        writer2.write("///");
+        writer2.newLine();
+      }
+      hasContent = true;
       writer2.write("/// # Returns");
       writer2.newLine();
       writer2.write("///");
@@ -946228,16 +946387,18 @@ var DocComment = class extends AstNode7 {
       });
     }
     if (this.examples.length > 0) {
-      writer2.write("///");
-      writer2.newLine();
+      if (hasContent) {
+        writer2.write("///");
+        writer2.newLine();
+      }
       writer2.write("/// # Examples");
       writer2.newLine();
       writer2.write("///");
       writer2.newLine();
       this.examples.forEach((example) => {
-        writer2.write("/// ```rust");
+        writer2.write("/// ```no_run");
         writer2.newLine();
-        this.writeMultilineText(writer2, example);
+        this.writeCodeBlock(writer2, example);
         writer2.write("/// ```");
         writer2.newLine();
       });
@@ -946251,6 +946412,14 @@ var DocComment = class extends AstNode7 {
       writer2.newLine();
     }
   }
+  writeCodeBlock(writer2, code5) {
+    const lines = code5.split("\n");
+    for (const line of lines) {
+      const trimmed2 = line.trimEnd();
+      writer2.write(trimmed2.length > 0 ? `/// ${trimmed2}` : "///");
+      writer2.newLine();
+    }
+  }
   /**
    * Sanitizes text content to ensure it doesn't break Rust doc comment syntax.
    */
@@ -952027,13 +952196,15 @@ var ComputedProperty = class extends AstNode8 {
 var DocComment2 = class _DocComment extends AstNode8 {
   summary;
   description;
+  codeExample;
   parameters;
   returns;
   throws;
-  constructor({ summary, description, parameters: parameters2, returns, throws }) {
+  constructor({ summary, description, codeExample, parameters: parameters2, returns, throws }) {
     super();
-    this.summary = _DocComment.sanitizeText(summary);
+    this.summary = summary != null ? _DocComment.sanitizeText(summary) : void 0;
     this.description = description != null ? _DocComment.sanitizeText(description) : void 0;
+    this.codeExample = codeExample != null ? _DocComment.sanitizeText(codeExample) : void 0;
     this.parameters = (parameters2 ?? []).map((param) => ({
       name: param.name,
       description: _DocComment.sanitizeText(param.description)
@@ -952042,15 +952213,34 @@ var DocComment2 = class _DocComment extends AstNode8 {
     this.throws = (throws ?? []).map((t3) => _DocComment.sanitizeText(t3));
   }
   write(writer2) {
-    this.writeMultilineText(writer2, this.summary);
+    let hasPrecedingSection = false;
+    if (this.summary != null) {
+      this.writeMultilineText(writer2, this.summary);
+      hasPrecedingSection = true;
+    }
     if (this.description != null) {
-      writer2.write("///");
-      writer2.newLine();
+      if (hasPrecedingSection) {
+        writer2.write("///");
+        writer2.newLine();
+      }
       this.writeMultilineText(writer2, this.description);
+      hasPrecedingSection = true;
+    }
+    if (this.codeExample != null) {
+      if (hasPrecedingSection) {
+        writer2.write("///");
+        writer2.newLine();
+      }
+      this.writeMultilineText(writer2, `\`\`\`swift
+${this.codeExample}
+\`\`\``);
+      hasPrecedingSection = true;
     }
     if (this.parameters.length > 0) {
-      writer2.write("///");
-      writer2.newLine();
+      if (hasPrecedingSection) {
+        writer2.write("///");
+        writer2.newLine();
+      }
       for (const param of this.parameters) {
         const paramLines = param.description.split("\n");
         paramLines.forEach((line, lineIdx) => {
@@ -952099,8 +952289,12 @@ var DocComment2 = class _DocComment extends AstNode8 {
   writeMultilineText(writer2, sanitizedText) {
     const lines = sanitizedText.split("\n");
     for (const line of lines) {
-      writer2.write("/// ");
-      writer2.write(line);
+      if (line === "") {
+        writer2.write("///");
+      } else {
+        writer2.write("/// ");
+        writer2.write(line);
+      }
       writer2.newLine();
     }
   }
@@ -971692,7 +971886,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.75.3"
+    cli_version: "5.75.5"
   };
 }
 function isAutomationMode() {
@@ -972524,7 +972718,7 @@ var CliContext = class _CliContext {
     if (false) {
       this.logger.error("CLI_VERSION is not defined");
     }
-    return "5.75.3";
+    return "5.75.5";
   }
   getCliName() {
     if (false) {

package/package.json

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