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

package/cli.cjs

@@ -691149,7 +691149,7 @@ var AccessTokenPosthogManager = class {
         properties: {
           ...event,
           ...event.properties,
-          version: "5.75.4",
+          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.4",
+        version: "5.75.5",
         ...event,
         ...event.properties,
         usingAccessToken: false,
@@ -872320,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.4";
+  const version7 = "5.75.5";
   return `cli@${version7}`;
 }
 var DebugLogger = class {
@@ -875598,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;
   }
@@ -875643,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
    */
@@ -876078,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;
@@ -904909,7 +904973,7 @@ var LegacyDocsPublisher = class {
         previewId,
         disableTemplates: void 0,
         skipUpload,
-        cliVersion: "5.75.4",
+        cliVersion: "5.75.5",
         loginCommand: "fern auth login"
       });
       if (taskContext.getResult() === TaskResult.Failure) {
@@ -935496,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({
@@ -935513,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(" *");
       }
@@ -935522,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) {
@@ -936694,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;
@@ -936706,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;
@@ -936739,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",
@@ -942729,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;
@@ -942743,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);
@@ -942788,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 [`);
@@ -946231,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,
@@ -946241,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("///");
@@ -946267,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("///");
@@ -946280,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();
       });
@@ -946303,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.
    */
@@ -952079,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)
@@ -952094,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) => {
@@ -952151,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();
     }
   }
@@ -971744,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.4"
+    cli_version: "5.75.5"
   };
 }
 function isAutomationMode() {
@@ -972576,7 +972718,7 @@ var CliContext = class _CliContext {
     if (false) {
       this.logger.error("CLI_VERSION is not defined");
     }
-    return "5.75.4";
+    return "5.75.5";
   }
   getCliName() {
     if (false) {

package/package.json

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