From 191078916b1d8e9f2911badfb757661e68f3302f Mon Sep 17 00:00:00 2001
From: Santiago Palladino <santiago@aztecprotocol.com>
Date: Tue, 26 Sep 2023 16:40:33 -0300
Subject: [PATCH] feat(docs): Warn if snippet is grabbed from master

---
 docs/src/preprocess/include_code.js | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/docs/src/preprocess/include_code.js b/docs/src/preprocess/include_code.js
index 9991780e2cc..60bc40defc8 100644
--- a/docs/src/preprocess/include_code.js
+++ b/docs/src/preprocess/include_code.js
@@ -87,13 +87,12 @@ function useLastRelease() {
 function readFile(filePath, tag) {
   if (tag && tag !== "master") {
     try {
-      const tag = getLatestTag();
       const root = path.resolve(__dirname, "../../../");
       const relPath = path.relative(root, filePath);
       return childProcess.execSync(`git show ${tag}:${relPath}`).toString();
     } catch (err) {
       console.error(
-        `Error reading file ${filePath} from latest version. Falling back to current content.`
+        `Error reading file ${filePath} from version ${tag}. Falling back to current content.`
       );
     }
   }
@@ -101,13 +100,15 @@ function readFile(filePath, tag) {
 }
 
 /** Extracts a code snippet, trying with the last release if applicable, and falling back to current content. */
-function extractCodeSnippet(filePath, identifier) {
+function extractCodeSnippet(filePath, identifier, requesterFile) {
   if (useLastRelease()) {
     try {
       return doExtractCodeSnippet(filePath, identifier, false);
     } catch (err) {
       console.error(
-        `Error extracting code snippet ${identifier} for ${filePath}: ${err}. Falling back to current content.`
+        `Error extracting code snippet ${identifier} from ${path.basename(
+          filePath
+        )} requested by ${requesterFile}: ${err}. Falling back to current content.`
       );
     }
   }
@@ -286,7 +287,11 @@ async function preprocessIncludeCode(markdownContent, filePath, rootDir) {
       const absCodeFilePath = path.join(rootDir, codeFilePath);
 
       // Extract the code snippet between the specified comments
-      const extracted = extractCodeSnippet(absCodeFilePath, identifier);
+      const extracted = extractCodeSnippet(
+        absCodeFilePath,
+        identifier,
+        filePath
+      );
       const [codeSnippet, startLine, endLine, tag] = extracted;
 
       const relativeCodeFilePath = path.resolve(rootDir, codeFilePath);
@@ -297,9 +302,13 @@ async function preprocessIncludeCode(markdownContent, filePath, rootDir) {
 
       const title = noTitle ? "" : `title="${identifier}"`;
       const lineNumbers = noLineNumbers ? "" : "showLineNumbers";
+      const warn =
+        useLastRelease() && (!tag || tag === "master")
+          ? `<br/>This example references unreleased code. Code from released packages may be different. Use with care.`
+          : "";
       const source = noSourceLink
         ? ""
-        : `\n> [<sup><sub>Source code: ${urlText}</sub></sup>](${url})`;
+        : `\n> <sup><sub><a href="${url}" target="_blank" rel="noopener noreferrer">Source code: ${urlText}</a>${warn}</sub></sup>`;
       const replacement =
         language === "raw"
           ? codeSnippet