@stackql/provider-utils 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackql/provider-utils",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Utilities for building StackQL providers from OpenAPI specifications.",
   "type": "module",
   "main": "./src/index.js",

package/src/docgen/generator.js

@@ -126,7 +126,8 @@ async function createDocsForService(yamlFilePath, providerName, serviceName, ser
     let dereferencedAPI;
 
     try {
-        dereferencedAPI = await deno_openapi_dereferencer.dereferenceApi(api, "$", ignorePaths);
+        // dereferencedAPI = await deno_openapi_dereferencer.dereferenceApi(api, "$", ignorePaths);
+        const dereferencedAPI = await SwaggerParser.dereference(api);
         dereferencedAPI = await deno_openapi_dereferencer.flattenAllOf(dereferencedAPI);
     } catch (error) {
         console.error("error in dereferencing or flattening:", error);

package/src/docgen/helpers.js

@@ -23,41 +23,29 @@ export function getIndefiniteArticle(resourceName) {
   return article;
 }
 
-export function cleanDescription(description) {
-    if (!description) return '';
-    
-    // Replace <a> tags with markdown equivalent
-    description = description.replace(/<a\s+(?:[^>]*?\s+)?href="([^"]*)"(?:[^>]*?)>(.*?)<\/a>/gi, '[$2]($1)');
-
-    // Remove <p> tags and replace them with a single space
-    description = description.replace(/<\/?p>/gi, ' ');
-
-    // Replace <br> tags with a single space
-    description = description.replace(/<br\s*\/?>/gi, ' ');
-
-    // Replace <code> and <pre> tags with markdown code blocks
-    description = description.replace(/<(code|pre)>(.*?)<\/\1>/gi, '`$2`');
-
-    // Convert <ul> and <li> tags into a comma-separated list
-    description = description.replace(/<\/?ul>/gi, '');
-    description = description.replace(/<li>(.*?)<\/li>/gi, '$1, ');
-
-    // Remove <name>, <td>, <tr>, and <table> tags
-    description = description.replace(/<\/?(name|td|tr|table)>/gi, '');
-
-    // Replace multiple spaces with a single space
-    description = description.replace(/\s+/g, ' ');
-
-    // Escape pipe characters to prevent breaking markdown tables
-    description = description.replace(/\|/g, '\\|');
-
-    // Remove any trailing commas, spaces, and line breaks
-    description = description.replace(/,s*$/, '').trim();
-
-    description = description.replace(/</g, '{');
-    description = description.replace(/>/g, '}');
-
-    return description;
+export function sanitizeHtml(text) {
+  return text
+    // Replace "<" unless it's followed by "a", "/a", "b", "/b", "strong", or "/strong"
+    .replace(/<(?!\/?(?:a|b|strong)\b)/gi, '&lt;')
+    // Replace ">" unless it's preceded by "</a", "<a ...>", "</b", "<b ...>", "</strong", or "<strong ...>"
+    .replace(/(?<!<\/?(?:a|b|strong)[^>]*)>/gi, '&gt;')
+    // Add quotes around unquoted href values (within <a ...>)
+    .replace(/(<a\b[^>]*?)href=([^"' \t\r\n>]+)/gi, '$1href="$2"')
+    // Wrap backticked text with <code>
+    .replace(/`([^`]+)`/g, '<code>$1</code>')
+    // Replace { and }
+    .replace(/{/g, '&#123;')
+    .replace(/}/g, '&#125;')
+    // Escape backslash
+    .replace(/\\/g, '\\\\')
+    // Replace " with &quot; UNLESS inside <code>...</code> OR inside an href="...".
+    // The alternation matches either a whole <code>...</code> block, an href="...",
+    // or a bare " to replace.
+    .replace(/(<code>[\s\S]*?<\/code>)|(\bhref="[^"]*")|"/gi, (m, code, href) => {
+      if (code) return code;          // keep code blocks untouched
+      if (href) return href;          // keep href="..." quotes untouched
+      return '&quot;';                // everything else: replace "
+    });
 }
 
 export function getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, sqlVerb) {
@@ -249,47 +237,13 @@ function formatProperties(respProps) {
         // Store formatted property details
         allProperties[propName] = {
             type: typeString,
-            description: escapeHtml(fullDescription),
+            // description: escapeHtml(fullDescription),
+            description: fullDescription
         };
     }
     return allProperties;
 }
 
-function escapeHtml(text) {
-    if (!text) return '';
-    return text
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#039;');
-}
-
-export function sanitizeHtml(text) {
-  return text
-    // Replace "<" unless it's followed by "a", "/a", "b", "/b", "strong", or "/strong"
-    .replace(/<(?!\/?(?:a|b|strong)\b)/gi, '&lt;')
-    // Replace ">" unless it's preceded by "</a", "<a ...>", "</b", "<b ...>", "</strong", or "<strong ...>"
-    .replace(/(?<!<\/?(?:a|b|strong)[^>]*)>/gi, '&gt;')
-    // Add quotes around unquoted href values (within <a ...>)
-    .replace(/(<a\b[^>]*?)href=([^"' \t\r\n>]+)/gi, '$1href="$2"')
-    // Wrap backticked text with <code>
-    .replace(/`([^`]+)`/g, '<code>$1</code>')
-    // Replace { and }
-    .replace(/{/g, '&#123;')
-    .replace(/}/g, '&#125;')
-    // Escape backslash
-    .replace(/\\/g, '\\\\')
-    // Replace " with &quot; UNLESS inside <code>...</code> OR inside an href="...".
-    // The alternation matches either a whole <code>...</code> block, an href="...",
-    // or a bare " to replace.
-    .replace(/(<code>[\s\S]*?<\/code>)|(\bhref="[^"]*")|"/gi, (m, code, href) => {
-      if (code) return code;          // keep code blocks untouched
-      if (href) return href;          // keep href="..." quotes untouched
-      return '&quot;';                // everything else: replace "
-    });
-}
-
 function getRequiredServerVars(dereferencedAPI) {
     const serverVars = {};
     
@@ -389,7 +343,7 @@ function getHttpOperationInfo(dereferencedAPI, path, httpVerb, mediaType, openAP
     }
     
     // Get operation description and replace curly braces with HTML entities
-    const opDescription = (dereferencedAPI.paths[path][httpVerb].description || '').replace(/\{/g, '&#123;').replace(/\}/g, '&#125;');
+    const opDescription = (dereferencedAPI.paths[path][httpVerb].description || '');   // .replace(/\{/g, '&#123;').replace(/\}/g, '&#125;');
 
     // Extract request body if it exists
     let requestBody = {};
@@ -498,26 +452,26 @@ function getHttpOperationParams(dereferencedAPI, path, httpVerb) {
         
         let additionalDescriptionParts = [];
         
-        for (const [fieldName, fieldValue] of Object.entries(param.schema)) {
-            if (fieldName === 'type' || fieldName === 'format' || fieldName === 'description' || fieldName === 'pattern') {
-                continue;
-            }
-
-            let formattedValue;
-            if (Array.isArray(fieldValue)) {
-                formattedValue = `[${fieldValue.join(', ')}]`;
-            } else if (typeof fieldValue === 'object' && fieldValue !== null) {
-                formattedValue = JSON.stringify(fieldValue);
-            } else {
-                formattedValue = String(fieldValue);
-            }
-
-            // if (fieldName === 'pattern') {
-            //     additionalDescriptionParts.push(`pattern: <code>${formattedValue}</code>`);
-            // } else {
-            //     additionalDescriptionParts.push(`${fieldName}: ${formattedValue}`);
-            // }
-        }
+        // for (const [fieldName, fieldValue] of Object.entries(param.schema)) {
+        //     if (fieldName === 'type' || fieldName === 'format' || fieldName === 'description' || fieldName === 'pattern') {
+        //         continue;
+        //     }
+
+        //     let formattedValue;
+        //     if (Array.isArray(fieldValue)) {
+        //         formattedValue = `[${fieldValue.join(', ')}]`;
+        //     } else if (typeof fieldValue === 'object' && fieldValue !== null) {
+        //         formattedValue = JSON.stringify(fieldValue);
+        //     } else {
+        //         formattedValue = String(fieldValue);
+        //     }
+
+        //     if (fieldName === 'pattern') {
+        //         additionalDescriptionParts.push(`pattern: <code>${formattedValue}</code>`);
+        //     } else {
+        //         additionalDescriptionParts.push(`${fieldName}: ${formattedValue}`);
+        //     }
+        // }
 
         // Add any fields from the parameter itself that might contain metadata
         for (const [fieldName, fieldValue] of Object.entries(param)) {
@@ -551,7 +505,7 @@ function getHttpOperationParams(dereferencedAPI, path, httpVerb) {
         // Create the parameter details object
         const paramDetails = {
             type: typeString,
-            description: description // Apply escapeHtml here if needed
+            description: description
         };
         
         // Add to the appropriate category based on required flag

package/src/docgen/resource/examples/delete-example.js

@@ -1,6 +1,7 @@
 // src/docgen/resource/examples/delete-example.js
 import { 
     getSqlMethodsWithOrderedFields, 
+    sanitizeHtml,
 } from '../../helpers.js';
 
 export function createDeleteExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
@@ -29,8 +30,9 @@ export function createDeleteExamples(providerName, serviceName, resourceName, re
         content += '<TabItem value="' + methodName + '">\n\n';
         
         // Add method description
-        content += methodDetails.opDescription || methodDetails.respDescription || 'No description available.';
-        
+        const opDescription = methodDetails.opDescription || 'No description available.';
+        content += sanitizeHtml(opDescription);
+
         // Create SQL example
         content += '\n\n```sql\nDELETE FROM ' + providerName + '.' + serviceName + '.' + resourceName;
         

package/src/docgen/resource/examples/exec-example.js

@@ -1,6 +1,7 @@
 // src/docgen/resource/examples/exec-example.js
 import { 
     getSqlMethodsWithOrderedFields, 
+    sanitizeHtml
 } from '../../helpers.js';
 
 export function createExecExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
@@ -29,7 +30,8 @@ export function createExecExamples(providerName, serviceName, resourceName, reso
         content += '<TabItem value="' + methodName + '">\n\n';
         
         // Add method description
-        content += methodDetails.opDescription || methodDetails.respDescription || 'No description available.';
+        const opDescription = methodDetails.opDescription || methodDetails.respDescription || 'No description available.';
+        content += sanitizeHtml(opDescription);
         
         // Create SQL example
         content += '\n\n```sql\nEXEC ' + providerName + '.' + serviceName + '.' + resourceName + '.' + methodName + ' \n';

package/src/docgen/resource/examples/insert-example.js

@@ -1,6 +1,7 @@
 // src/docgen/resource/examples/insert-example.js
 import { 
     getSqlMethodsWithOrderedFields, 
+    sanitizeHtml
 } from '../../helpers.js';
 
 export function createInsertExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
@@ -31,7 +32,11 @@ export function createInsertExamples(providerName, serviceName, resourceName, re
     // Create each method tab content
     Object.entries(insertMethods).forEach(([methodName, methodDetails]) => {
         content += '<TabItem value="' + methodName + '">\n\n';
-        content += methodDetails.opDescription || 'No description available.';
+
+        // Add method description
+        const opDescription = methodDetails.opDescription || 'No description available.';
+        content += sanitizeHtml(opDescription);
+        // content += methodDetails.opDescription || 'No description available.';
         
         // Create SQL example
         content += '\n\n```sql\nINSERT INTO ' + providerName + '.' + serviceName + '.' + resourceName + ' (\n';
@@ -107,22 +112,6 @@ export function createInsertExamples(providerName, serviceName, resourceName, re
         content += '\n;\n```\n</TabItem>\n';
     });
 
-    
-// {
-//     "code": {
-//         "type": "string",
-//         "description": " (example: 000123)"
-//     },
-//     "createdOn": {
-//         "type": "integer (int64)",
-//         "description": "Timestamp that specifies when the statement execution started.‌ The timestamp is expressed in milliseconds since the epoch.‌"
-//     },
-//     "data": {
-//         "type": "array",
-//         "description": "Result set data."
-//     },
-// }
-
     // Create manifest tab
     content += '<TabItem value="manifest">\n\n';
     content += '```yaml\n# Description fields are for documentation purposes\n- name: ' + resourceName + '\n  props:\n';

package/src/docgen/resource/examples/select-example.js

@@ -1,6 +1,7 @@
 // src/docgen/resource/examples/select-example.js
 import { 
     getSqlMethodsWithOrderedFields, 
+    sanitizeHtml
 } from '../../helpers.js';
 
 export function createSelectExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
@@ -27,8 +28,11 @@ export function createSelectExamples(providerName, serviceName, resourceName, re
     // Create each tab content
     Object.entries(selectMethods).forEach(([methodName, methodDetails]) => {
         content += '<TabItem value="' + methodName + '">\n\n';
-        content += methodDetails.opDescription || 'No description available.';
-        
+        // content += methodDetails.opDescription || 'No description available.';
+        // Add method description
+        const opDescription = methodDetails.opDescription || methodDetails.respDescription || 'No description available.';
+        content += sanitizeHtml(opDescription);
+
         // Create SQL example
         content += '\n\n```sql\nSELECT\n';
         

package/src/docgen/resource/examples/update-example.js

@@ -1,6 +1,7 @@
 // src/docgen/resource/examples/update-example.js
 import { 
     getSqlMethodsWithOrderedFields, 
+    sanitizeHtml
 } from '../../helpers.js';
 
 export function createUpdateExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, isReplace = false) {
@@ -33,8 +34,11 @@ export function createUpdateExamples(providerName, serviceName, resourceName, re
     Object.entries(updateMethods).forEach(([methodName, methodDetails]) => {
         content += '<TabItem value="' + methodName + '">\n\n';
         
+        // // Add method description
+        // content += methodDetails.opDescription || methodDetails.respDescription || 'No description available.';
         // Add method description
-        content += methodDetails.opDescription || methodDetails.respDescription || 'No description available.';
+        const opDescription = methodDetails.opDescription || 'No description available.';
+        content += sanitizeHtml(opDescription);
         
         // Create SQL example
         content += '\n\n```sql\n';

package/src/docgen/resource/fields.js

@@ -1,6 +1,7 @@
 // src/docgen/resource/fields.js
 import { 
     getSqlMethodsWithOrderedFields, 
+    sanitizeHtml,
 } from '../helpers.js';
 
 const mdCodeAnchor = "`";
@@ -58,7 +59,7 @@ export function createFieldsSection(resourceData, dereferencedAPI) {
                 content += `\n<tr>
     <td><CopyableCode code="${propName}" /></td>
     <td><code>${propData.type}</code></td>
-    <td>${propData.description}</td>
+    <td>${sanitizeHtml(propData.description)}</td>
 </tr>`;
             }
             

package/src/docgen/resource/methods.js

@@ -1,6 +1,5 @@
 // src/docgen/resource/methods.js
 import { 
-    cleanDescription, 
     getSqlMethodsWithOrderedFields,
     sanitizeHtml
 } from '../helpers.js';