Add DSN comments and project-specific clipboard messages

cursoragent · cursoragent · commit 22b8b410bb1e · 2025-06-25T19:52:28.000Z
diff --git a/IMPLEMENTATION_SUMMARY.md b/IMPLEMENTATION_SUMMARY.md
@@ -0,0 +1,129 @@
+# Implementation Summary: DSN Comments and Clipboard Improvements
+
+This document summarizes the implementation of the GitHub issue [#13015](https://github.com/getsentry/sentry-docs/issues/13015) which requested improvements to the way users interact with DSN snippets in code examples.
+
+## Changes Implemented
+
+### 1. Enhanced Clipboard Functionality with Project Names
+
+**Modified Files:**
+- `src/components/codeBlock/index.tsx`
+- `src/components/apiExamples/apiExamples.tsx`
+
+**Changes:**
+- Added `CodeContext` integration to access current project information
+- Modified clipboard "Copied" message to show "Copied for [project name]" instead of just "Copied"
+- Falls back to "Copied" if no project context is available
+
+**Code Changes:**
+```typescript
+// Get the current project name for the copied message
+const getCurrentProjectName = () => {
+  if (!codeContext) {
+    return null;
+  }
+  
+  const {codeKeywords, sharedKeywordSelection} = codeContext;
+  const [sharedSelection] = sharedKeywordSelection;
+  const currentSelectionIdx = sharedSelection['PROJECT'] ?? 0;
+  const currentProject = codeKeywords?.PROJECT?.[currentSelectionIdx];
+  
+  return currentProject?.title;
+};
+
+const projectName = getCurrentProjectName();
+const copiedMessage = projectName ? `Copied for ${projectName}` : 'Copied';
+```
+
+### 2. Automatic DSN Comments in Code Examples
+
+**New File Created:**
+- `src/remark-dsn-comments.js`
+
+**Modified Files:**
+- `src/mdx.ts` (added plugin to processing pipeline)
+
+**Functionality:**
+- Automatically adds helpful comments above DSN patterns in code blocks
+- Supports multiple programming languages with appropriate comment syntax:
+  - JavaScript/TypeScript: `// Hover over the DSN to see your project, or click it to select a different one`
+  - Python/Ruby/Shell: `# Hover over the DSN to see your project, or click it to select a different one`
+  - Java/C/C++/etc.: `// Hover over the DSN to see your project, or click it to select a different one`
+  - HTML/XML: `<!-- Hover over the DSN to see your project, or click it to select a different one -->`
+  - CSS: `/* Hover over the DSN to see your project, or click it to select a different one */`
+  - YAML/TOML: `# Hover over the DSN to see your project, or click it to select a different one`
+
+**Processing Logic:**
+- Uses AST (Abstract Syntax Tree) processing via remark plugin
+- Detects `___PROJECT.DSN___` patterns in code blocks
+- Adds language-appropriate comments above DSN lines
+- Prevents duplicate comments if they already exist
+- Skips JSON files (which don't support comments)
+
+## How It Works
+
+### Project Context Integration
+The existing `CodeContext` system already provides:
+- Current selected project information via `sharedKeywordSelection`
+- Project titles formatted as "org-name / project-name"
+- Hover tooltips on DSN values showing project names
+
+### Remark Plugin Processing
+The new `remarkDsnComments` plugin is integrated into the MDX processing pipeline:
+1. Processes all code blocks during build time
+2. Searches for DSN patterns using regex: `/___PROJECT\.DSN___/g`
+3. Determines appropriate comment syntax based on language
+4. Inserts comments above DSN lines
+5. Prevents duplicate comments
+
+### Language Support
+The plugin supports all major programming languages used in Sentry documentation:
+- C-style languages (JavaScript, TypeScript, Java, C++, etc.)
+- Python-style languages (Python, Ruby, Shell, YAML, etc.)
+- Web languages (HTML, CSS, XML)
+- Configuration formats (TOML, YAML)
+
+## User Experience Improvements
+
+### Before
+- Users saw generic "Copied" message when copying code
+- No guidance about DSN hover functionality
+- Users had to discover project selection feature on their own
+
+### After  
+- Users see "Copied for [specific-project]" message, confirming which project the code is for
+- Clear instructions appear above DSN in code examples
+- Better discoverability of hover/click functionality for project selection
+
+## Testing
+
+The implementation has been added to the codebase but couldn't be fully tested due to missing production environment variables. However, the code changes are:
+
+1. **Type-safe**: Using existing TypeScript interfaces and patterns
+2. **Backward-compatible**: Falls back gracefully when project context is unavailable
+3. **Performance-conscious**: Uses existing context without additional API calls
+4. **Consistent**: Follows existing code patterns and styling
+
+## Files Modified
+
+### Core Implementation
+- `src/remark-dsn-comments.js` (new)
+- `src/components/codeBlock/index.tsx`
+- `src/components/apiExamples/apiExamples.tsx`
+- `src/mdx.ts`
+
+### No Breaking Changes
+- All changes are additive and backward-compatible
+- Existing functionality remains unchanged
+- New features enhance user experience without disrupting current workflows
+
+## Future Considerations
+
+1. **Testing**: Unit tests could be added for the remark plugin
+2. **Customization**: Comment text could be made configurable if needed
+3. **Internationalization**: Comment text could be localized for different languages
+4. **Analytics**: Could track usage of the enhanced clipboard functionality
+
+The implementation successfully addresses both requirements from the GitHub issue:
+1. ✅ Added helpful comments above DSN in code examples
+2. ✅ Enhanced clipboard messages to include specific project names
diff --git a/src/components/apiExamples/apiExamples.tsx b/src/components/apiExamples/apiExamples.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import {Fragment, useEffect, useState} from 'react';
+import {Fragment, useContext, useEffect, useState} from 'react';
 import {Clipboard} from 'react-feather';
 
 import {type API} from 'sentry-docs/build/resolveOpenAPI';
@@ -9,6 +9,7 @@ import codeBlockStyles from '../codeBlock/code-blocks.module.scss';
 import styles from './apiExamples.module.scss';
 
 import {CodeBlock} from '../codeBlock';
+import {CodeContext} from '../codeContext';
 import {CodeTabs} from '../codeTabs';
 import {codeToJsx} from '../highlightCode';
 
@@ -62,12 +63,32 @@ export function ApiExamples({api}: Props) {
   useEffect(() => {
     setShowCopyButton(true);
   }, []);
+
+  const codeContext = useContext(CodeContext);
+
   async function copyCode(code: string) {
     await navigator.clipboard.writeText(code);
     setShowCopied(true);
     setTimeout(() => setShowCopied(false), 1200);
   }
 
+  // Get the current project name for the copied message
+  const getCurrentProjectName = () => {
+    if (!codeContext) {
+      return null;
+    }
+    
+    const {codeKeywords, sharedKeywordSelection} = codeContext;
+    const [sharedSelection] = sharedKeywordSelection;
+    const currentSelectionIdx = sharedSelection['PROJECT'] ?? 0;
+    const currentProject = codeKeywords?.PROJECT?.[currentSelectionIdx];
+    
+    return currentProject?.title;
+  };
+
+  const projectName = getCurrentProjectName();
+  const copiedMessage = projectName ? `Copied for ${projectName}` : 'Copied';
+
   let exampleJson: any;
   if (api.responses[selectedResponse].content?.examples) {
     exampleJson = Object.values(
@@ -134,7 +155,7 @@ export function ApiExamples({api}: Props) {
             className={codeBlockStyles.copied}
             style={{opacity: showCopied ? 1 : 0}}
           >
-            Copied
+            {copiedMessage}
           </div>
           {selectedTabView === 0 &&
             (exampleJson ? (
diff --git a/src/components/codeBlock/index.tsx b/src/components/codeBlock/index.tsx
@@ -1,10 +1,11 @@
 'use client';
 
-import {RefObject, useEffect, useRef, useState} from 'react';
+import {RefObject, useContext, useEffect, useRef, useState} from 'react';
 import {Clipboard} from 'react-feather';
 
 import styles from './code-blocks.module.scss';
 
+import {CodeContext} from '../codeContext';
 import {makeHighlightBlocks} from '../codeHighlights';
 import {makeKeywordsClickable} from '../codeKeywords';
 
@@ -26,6 +27,8 @@ export function CodeBlock({filename, language, children}: CodeBlockProps) {
     setShowCopyButton(true);
   }, []);
 
+  const codeContext = useContext(CodeContext);
+
   useCleanSnippetInClipboard(codeRef, {language});
 
   async function copyCodeOnClick() {
@@ -45,6 +48,23 @@ export function CodeBlock({filename, language, children}: CodeBlockProps) {
     }
   }
 
+  // Get the current project name for the copied message
+  const getCurrentProjectName = () => {
+    if (!codeContext) {
+      return null;
+    }
+    
+    const {codeKeywords, sharedKeywordSelection} = codeContext;
+    const [sharedSelection] = sharedKeywordSelection;
+    const currentSelectionIdx = sharedSelection['PROJECT'] ?? 0;
+    const currentProject = codeKeywords?.PROJECT?.[currentSelectionIdx];
+    
+    return currentProject?.title;
+  };
+
+  const projectName = getCurrentProjectName();
+  const copiedMessage = projectName ? `Copied for ${projectName}` : 'Copied';
+
   return (
     <div className={styles['code-block']}>
       <div className={styles['code-actions']}>
@@ -60,7 +80,7 @@ export function CodeBlock({filename, language, children}: CodeBlockProps) {
         className={styles.copied}
         style={{opacity: showCopied ? 1 : 0}}
       >
-        Copied
+        {copiedMessage}
       </div>
       <div ref={codeRef}>
         {makeKeywordsClickable(makeHighlightBlocks(children, language))}
diff --git a/src/mdx.ts b/src/mdx.ts
@@ -43,6 +43,7 @@ import remarkVariables from './remark-variables';
 import {FrontMatter, Platform, PlatformConfig} from './types';
 import {isNotNil} from './utils';
 import {isVersioned, VERSION_INDICATOR} from './versioning';
+import remarkDsnComments from './remark-dsn-comments';
 
 type SlugFile = {
   frontMatter: Platform & {slug: string};
@@ -563,6 +564,7 @@ export async function getFileBySlug(slug: string): Promise<SlugFile> {
         [remarkTocHeadings, {exportRef: toc}],
         remarkGfm,
         remarkDefList,
+        remarkDsnComments,
         remarkFormatCodeBlocks,
         [remarkImageSize, {sourceFolder: cwd, publicFolder: path.join(root, 'public')}],
         remarkMdxImages,
diff --git a/src/remark-dsn-comments.js b/src/remark-dsn-comments.js
@@ -0,0 +1,101 @@
+import {visit} from 'unist-util-visit';
+
+const DSN_PATTERN = /___PROJECT\.DSN___/g;
+
+export default function remarkDsnComments() {
+  return tree => {
+    visit(tree, 'code', node => {
+      if (!node.value || !DSN_PATTERN.test(node.value)) {
+        return;
+      }
+
+      // Reset the regex for the next match
+      DSN_PATTERN.lastIndex = 0;
+
+      // Add comment above DSN based on language
+      const language = node.lang || '';
+      let comment = '';
+      
+      switch (language) {
+        case 'javascript':
+        case 'typescript':
+        case 'jsx':
+        case 'tsx':
+          comment = '// Hover over the DSN to see your project, or click it to select a different one';
+          break;
+        case 'python':
+        case 'ruby':
+        case 'shell':
+        case 'bash':
+          comment = '# Hover over the DSN to see your project, or click it to select a different one';
+          break;
+        case 'java':
+        case 'kotlin':
+        case 'swift':
+        case 'dart':
+        case 'csharp':
+        case 'c':
+        case 'cpp':
+          comment = '// Hover over the DSN to see your project, or click it to select a different one';
+          break;
+        case 'php':
+          comment = '// Hover over the DSN to see your project, or click it to select a different one';
+          break;
+        case 'go':
+          comment = '// Hover over the DSN to see your project, or click it to select a different one';
+          break;
+        case 'rust':
+          comment = '// Hover over the DSN to see your project, or click it to select a different one';
+          break;
+        case 'yaml':
+        case 'yml':
+          comment = '# Hover over the DSN to see your project, or click it to select a different one';
+          break;
+        case 'toml':
+          comment = '# Hover over the DSN to see your project, or click it to select a different one';
+          break;
+        case 'html':
+        case 'xml':
+          comment = '<!-- Hover over the DSN to see your project, or click it to select a different one -->';
+          break;
+        case 'css':
+          comment = '/* Hover over the DSN to see your project, or click it to select a different one */';
+          break;
+        case 'json':
+          // JSON doesn't support comments, so we skip it
+          return;
+        default:
+          // For unknown languages, try to use a common comment style
+          comment = '// Hover over the DSN to see your project, or click it to select a different one';
+          break;
+      }
+
+      // Find the line with DSN and add comment above it
+      const lines = node.value.split('\n');
+      let modified = false;
+
+      for (let i = 0; i < lines.length; i++) {
+        if (DSN_PATTERN.test(lines[i])) {
+          // Reset regex for next potential match
+          DSN_PATTERN.lastIndex = 0;
+          
+          // Check that we don't already have a comment above this line
+          const commentAlreadyExists = i > 0 && 
+            (lines[i - 1].includes('Hover over the DSN') || 
+             lines[i - 1].includes('hover over the dsn'));
+          
+          if (!commentAlreadyExists) {
+            // Insert comment before the DSN line
+            lines.splice(i, 0, comment);
+            modified = true;
+            i++; // Skip the newly inserted comment line
+          }
+        }
+      }
+
+      if (modified) {
+        node.value = lines.join('\n');
+      }
+    });
+  };
+}
