Bug Report: Syntax Errors in Generated Code Samples

October 4, 2025 · View on GitHub

Summary

The add_code_samples.py script generates syntactically invalid code samples for POST/PUT/PATCH operations in both cURL and JavaScript examples. These invalid samples would fail if users try to execute them directly.

Bug Details

File: add_code_samples.py
Lines: 144-153 (cURL), 170-181 (JavaScript)
Severity: High (generates broken code that users cannot execute)
Status: 🔴 IDENTIFIED, NEEDS FIX

Description

When generating code samples for operations that include request bodies (POST, PUT, PATCH), the script produces syntactically invalid code due to incorrect line continuation and missing punctuation.

Bug 1: cURL - Missing Line Continuation Backslash

Location: Lines 144-153

Problem: The cURL sample has inconsistent line continuation. Line 146 includes the Authorization header but is missing a trailing backslash, yet line 150 (Content-Type header) has one. This causes the cURL command to be malformed.

Generated Output:

curl -X POST 'https://api.venice.ai/api/v1/test' \
  -H 'Authorization: Bearer YOUR_API_KEY'
  -H 'Content-Type: application/json' \
  -d '{}'

Issue: Line 2 ends without \, so line 3 is interpreted as a separate command rather than a continuation of the curl command.

Expected Output:

curl -X POST 'https://api.venice.ai/api/v1/test' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Bug 2: JavaScript - Missing Comma in Object Literal

Location: Lines 170-181

Problem: The JavaScript fetch example has a missing comma between the Authorization and Content-Type headers in the headers object, resulting in invalid JavaScript syntax.

Generated Output:

const response = await fetch('https://api.venice.ai/api/v1/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
});

Issue: Line 4 is missing a comma at the end, making the JavaScript object literal syntactically invalid.

Expected Output:

const response = await fetch('https://api.venice.ai/api/v1/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
});

Impact

Before Fix:

  • ❌ Users copying cURL examples get shell syntax errors
  • ❌ Users copying JavaScript examples get syntax errors when running code
  • ❌ Code samples fail basic validation in IDEs and linters
  • ❌ Reduces trust in the API documentation
  • ❌ Creates support burden from confused users

After Fix:

  • ✅ All generated code samples are syntactically valid
  • ✅ Users can copy-paste examples directly without modifications
  • ✅ Examples pass linting and validation tools
  • ✅ Professional, production-ready documentation

Root Cause

The bug was introduced in the string concatenation logic for generating multi-line code samples. When adding conditional content (Content-Type header and body), the developer forgot to include:

  1. The trailing backslash on line 146 for cURL continuation
  2. The trailing comma on line 174 for JavaScript object syntax

This likely happened because:

  • The conditional logic for POST/PUT/PATCH was added after the initial implementation
  • The developer tested only GET requests, which don't exhibit these bugs
  • No automated tests verified the syntax validity of generated code

Fix Strategy

Fix for Bug 1 (cURL):

Line 146: Add trailing backslash to the Authorization header line

# Before
curl_lines = [
    f"curl -X {method.upper()} 'https://api.venice.ai/api/v1{path}' \\",
    "  -H 'Authorization: Bearer YOUR_API_KEY'"
]

# After
curl_lines = [
    f"curl -X {method.upper()} 'https://api.venice.ai/api/v1{path}' \\",
    "  -H 'Authorization: Bearer YOUR_API_KEY' \\"
]

Fix for Bug 2 (JavaScript):

Line 174: Add trailing comma to the Authorization header line

# Before
js_lines = [
    f"const response = await fetch('https://api.venice.ai/api/v1{path}', {{",
    f"  method: '{method.upper()}',",
    "  headers: {",
    "    'Authorization': 'Bearer YOUR_API_KEY'"
]

# After
js_lines = [
    f"const response = await fetch('https://api.venice.ai/api/v1{path}', {{",
    f"  method: '{method.upper()}',",
    "  headers: {",
    "    'Authorization': 'Bearer YOUR_API_KEY',"
]

Verification

Test Case: test_code_sample_syntax.py

A dedicated test will be created to verify this bug fix by:

  1. Generating code samples for POST/PUT/PATCH operations
  2. Validating the syntax of generated cURL commands
  3. Validating the syntax of generated JavaScript code
  4. Ensuring all line continuations are correct
  5. Ensuring all object literals have proper punctuation

Before Fix: Test will FAIL - Generated code has syntax errors
After Fix: Test will PASS - Generated code is syntactically valid

Manual Verification

After the fix, running:

python3 add_code_samples.py

Should generate valid code samples that:

  • Can be executed directly in a shell (cURL)
  • Can be parsed and executed in Node.js (JavaScript)
  • Pass syntax validation in linters (shellcheck, eslint)

Lessons Learned

  1. Test Edge Cases: Always test conditional code paths (GET vs POST)
  2. Automated Validation: Add tests that validate generated code syntax
  3. Multi-line Strings: Be extra careful with string concatenation and continuation characters
  4. User Experience: Invalid code samples significantly harm user experience

Prevention

To prevent similar issues:

  1. ✅ Automated Tests: New test validates syntax of all generated code samples
  2. ✅ Code Review: PRs should include examples of generated output
  3. ✅ Linting: Consider running shellcheck/eslint on generated samples in tests
  4. ✅ Documentation: Document the expected format for each language
  • add_code_samples.py - Main script with bugs (lines 144-153, 170-181)
  • test_code_sample_syntax.py - New test to verify fix
  • test_add_code_samples.py - Existing test (doesn't catch syntax errors)

References

Identified By: Automated code review
Identified Date: 2025-01-XX
Status: Ready for fix implementation