@stackql/provider-utils 0.4.2 → 0.4.4

package/package.json

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

package/src/docgen/helpers.js

@@ -23,18 +23,44 @@ export function getIndefiniteArticle(resourceName) {
   return article;
 }
 
+/**
+ * Sanitizes HTML with special handling for allowed tags and backticked content
+ * @param {string} text - The text to sanitize
+ * @return {string} - The sanitized text
+ */
 export function sanitizeHtml(text) {
-  return text
+  if (!text) return '';
+  
+  // First apply the general sanitization
+  let result = text
     .replace(/{/g, '{')
     .replace(/}/g, '}')
     .replace(/>/g, '>')
     .replace(/</g, '&lt;')
     // edge case
     .replace(/&#125;_&#123;/g, '&#125;&#95;&#123;')
-    .replace(/\n/g, '<br />')
+    .replace(/\n/g, '<br />');
+  
+  // Fix 1: Replace &lt;br&gt;, &lt;br/&gt;, &lt;p&gt;, &lt;/p&gt; back to their literal HTML tags
+  // Make sure <br> is always self-closing for MDX compatibility
+  result = result
+    .replace(/&lt;br\s*\/?&gt;/gi, '<br />')
+    .replace(/&lt;p&gt;/gi, '<p>')
+    .replace(/&lt;\/p&gt;/gi, '</p>');
+  
+  // Fix 2: Find any &lt; or &gt; inside backticks and convert them back to < and >
+  // We need to handle the backtick content by finding pairs of backticks
+  result = result.replace(/`([^`]*)`/g, (match, content) => {
+    // Convert &lt; and &gt; back to < and > only within backticked content
+    const fixedContent = content
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>');
+    return '`' + fixedContent + '`';
+  });
+  
+  return result;
 }
 
-
 export function getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, sqlVerb) {
     const methods = {};
 

package/src/providerdev/analyze.js

@@ -51,6 +51,108 @@ function extractMain2xxResponse(responseObj) {
   return '';
 }
 
+/**
+ * Detect if an object should have an objectKey and determine what it should be
+ * @param {Object} spec - Full OpenAPI spec
+ * @param {Object} operation - Operation object
+ * @returns {string} - Suggested objectKey or empty string if none
+ */
+function detectObjectKey(spec, operation) {
+  // Only applicable for GET operations
+  if (!operation || !operation.responses) {
+    return '';
+  }
+  
+  let responseObject = null;
+  let responseCode = null;
+  
+  // Find the first 2xx response
+  for (const [code, response] of Object.entries(operation.responses)) {
+    if (code.startsWith('2')) {
+      responseCode = code;
+      // Handle direct response or reference
+      if (response.$ref) {
+        // Resolve reference
+        const refParts = response.$ref.split('/');
+        const componentType = refParts[2];
+        const responseName = refParts[3];
+        responseObject = spec.components?.[componentType]?.[responseName];
+      } else {
+        responseObject = response;
+      }
+      break;
+    }
+  }
+  
+  if (!responseObject) {
+    return '';
+  }
+  
+  // Get the schema from the response
+  let schema = null;
+  
+  // If it's a direct response object
+  if (responseObject.content?.['application/json']?.schema) {
+    schema = responseObject.content['application/json'].schema;
+  } 
+  
+  // If the schema is a reference, resolve it
+  if (schema && schema.$ref) {
+    const refParts = schema.$ref.split('/');
+    const componentType = refParts[2];
+    const schemaName = refParts[3];
+    schema = spec.components?.[componentType]?.[schemaName];
+  }
+  
+  // Handle allOf case (like in the droplets_list example)
+  if (schema && schema.allOf) {
+    // Look at the first object in allOf that has properties
+    for (const subSchema of schema.allOf) {
+      if (subSchema.properties && Object.keys(subSchema.properties).length === 1) {
+        const key = Object.keys(subSchema.properties)[0];
+        return `$.${key}`;
+      }
+    }
+  }
+  
+  // Handle direct properties case (like in the droplets_get example)
+  if (schema && schema.properties) {
+    // If there's only one property at the top level, and it's not a primitive
+    const propKeys = Object.keys(schema.properties);
+    if (propKeys.length === 1) {
+      const key = propKeys[0];
+      const prop = schema.properties[key];
+      
+      // Check if the property is an object or array, not a primitive
+      if (prop.$ref || 
+          prop.type === 'object' || 
+          prop.type === 'array' ||
+          (prop.properties && Object.keys(prop.properties).length > 0)) {
+        return `$.${key}`;
+      }
+    }
+  }
+  
+  return '';
+}
+
+/**
+ * Map HTTP verb to SQL verb
+ * @param {string} httpVerb - HTTP verb (get, post, put, etc)
+ * @returns {string} - Corresponding SQL verb
+ */
+function mapToSqlVerb(httpVerb) {
+  const verbMap = {
+    'get': 'select',
+    'post': 'insert',
+    'delete': 'delete',
+    'put': 'replace',
+    'patch': 'update'
+  };
+  
+  return verbMap[httpVerb] || 'exec';
+}
+
 /**
  * Find existing mapping in x-stackQL-resources
  * @param {Object} spec - OpenAPI spec
@@ -77,10 +179,14 @@ function findExistingMapping(spec, pathRef) {
           }
         }
         
+        // Get objectKey if present
+        const objectKey = method.response?.objectKey || '';
+        
         return {
           resourceName,
           methodName,
-          sqlVerb
+          sqlVerb,
+          objectKey
         };
       }
     }
@@ -91,7 +197,8 @@ function findExistingMapping(spec, pathRef) {
   return {
     resourceName: '',
     methodName: '',
-    sqlVerb: ''
+    sqlVerb: '',
+    objectKey: ''
   };
 }
 
@@ -150,7 +257,8 @@ export async function analyze(options) {
                 existingMappings[key] = {
                   resourceName: row.stackql_resource_name || '',
                   methodName: row.stackql_method_name || '',
-                  sqlVerb: row.stackql_verb || ''
+                  sqlVerb: row.stackql_verb || '',
+                  objectKey: row.stackql_object_key || ''
                 };
               }
             })
@@ -176,7 +284,7 @@ export async function analyze(options) {
 
     // Only write header if creating a new file
     if (!fileExists) {
-      writer.write('filename,path,operationId,formatted_op_id,verb,response_object,tags,formatted_tags,stackql_resource_name,stackql_method_name,stackql_verb,op_description\n');
+      writer.write('filename,path,operationId,formatted_op_id,verb,response_object,tags,formatted_tags,stackql_resource_name,stackql_method_name,stackql_verb,stackql_object_key,op_description\n');
     }
     
     const files = fs.readdirSync(inputDir);
@@ -231,7 +339,22 @@ export async function analyze(options) {
           const pathRef = `#/paths/${encodedPath}/${verb}`;
           
           // Find existing mapping if available
-          const { resourceName, methodName, sqlVerb } = findExistingMapping(spec, pathRef);
+          let { resourceName, methodName, sqlVerb, objectKey } = findExistingMapping(spec, pathRef);
+          
+          // CHANGE 1: Default methodName to formattedOpId if not found
+          if (!methodName) {
+            methodName = formattedOpId;
+          }
+          
+          // CHANGE 2: Default sqlVerb based on HTTP verb if not found
+          if (!sqlVerb) {
+            sqlVerb = mapToSqlVerb(verb);
+          }
+
+          // CHANGE 3: Detect and set objectKey for GET operations if not already set
+          if (!objectKey && verb === 'get') {
+            objectKey = detectObjectKey(spec, operation);
+          }
           
           // Get operation description
           const opDescription = operation.summary || operation.description || '';
@@ -249,11 +372,12 @@ export async function analyze(options) {
             resourceName: escapeCsvField(resourceName),
             methodName: escapeCsvField(methodName),
             sqlVerb: escapeCsvField(sqlVerb),
+            objectKey: escapeCsvField(objectKey),
             opDescription: escapeCsvField(opDescription)
           };
           
           // Write row
-          writer.write(`${escapedFields.filename},${escapedFields.path},${escapedFields.operationId},${escapedFields.formattedOpId},${escapedFields.verb},${escapedFields.responseRef},${escapedFields.tagsStr},${escapedFields.formattedTags},${escapedFields.resourceName},${escapedFields.methodName},${escapedFields.sqlVerb},${escapedFields.opDescription}\n`);
+          writer.write(`${escapedFields.filename},${escapedFields.path},${escapedFields.operationId},${escapedFields.formattedOpId},${escapedFields.verb},${escapedFields.responseRef},${escapedFields.tagsStr},${escapedFields.formattedTags},${escapedFields.resourceName},${escapedFields.methodName},${escapedFields.sqlVerb},${escapedFields.objectKey},${escapedFields.opDescription}\n`);
         }
       }
     }

package/src/providerdev/generate.js

@@ -1,4 +1,3 @@
-// src/providerdev/generate.js
 import fs from 'fs';
 import path from 'path';
 import yaml from 'js-yaml';
@@ -75,14 +74,15 @@ function getSuccessResponseInfo(operation) {
     .sort();
 
   if (twoXxCodes.length === 0) {
-    return { mediaType: '', openAPIDocKey: '' };
+    throw new Error('No 2xx response found, openAPIDocKey is required');
   }
 
   const lowest2xx = twoXxCodes[0];
   const content = responses[lowest2xx]?.content || {};
   const mediaTypes = Object.keys(content);
 
-  const mediaType = mediaTypes.length > 0 ? mediaTypes[0] : '';
+  // Default to 'application/json' if mediaType is not found
+  const mediaType = mediaTypes.length > 0 ? mediaTypes[0] : 'application/json';
 
   return {
     mediaType,
@@ -99,6 +99,71 @@ function snakeCase(name) {
   return name.replace(/-/g, '_');
 }
 
+/**
+ * Count the number of path parameters in a path
+ * @param {string} path - HTTP path
+ * @returns {number} - Number of path parameters
+ */
+function countPathParams(path) {
+  // Match all path parameters like {param_name}
+  const matches = path.match(/\{[^}]+\}/g);
+  return matches ? matches.length : 0;
+}
+
+/**
+ * Sort operations from most specific to least specific based on path parameters
+ * @param {Object} resources - Resources object containing methods and sqlVerbs
+ * @param {Object} spec - Full OpenAPI specification
+ * @returns {Object} - Resources with sorted sqlVerbs
+ */
+function sortOperationsBySpecificity(resources, spec) {
+  // For each resource
+  for (const resourceName in resources) {
+    const resource = resources[resourceName];
+    const methods = resource.methods;
+    
+    // Create a map of method references to their specificity (path param count)
+    const methodSpecificityMap = {};
+    
+    // For each method, find its operation ref and count path params
+    for (const methodName in methods) {
+      const method = methods[methodName];
+      const operationRef = method.operation.$ref;
+      
+      // Extract path and verb from the reference
+      // Reference format: '#/paths/{encodedPath}/{verb}'
+      const refParts = operationRef.split('/');
+      const verb = refParts.pop();
+      // Remove '#/paths/' and the verb, then decode the path
+      const encodedPath = refParts.slice(2).join('/');
+      const path = encodedPath.replace(/~1/g, '/');
+      
+      // Count path parameters
+      const paramCount = countPathParams(path);
+      
+      // Store the method reference and its path parameter count
+      const methodRef = `#/components/x-stackQL-resources/${resourceName}/methods/${methodName}`;
+      methodSpecificityMap[methodRef] = paramCount;
+    }
+    
+    // For each SQL verb, sort the operations by specificity
+    for (const verbName in resource.sqlVerbs) {
+      const operations = resource.sqlVerbs[verbName];
+      
+      if (operations && operations.length > 0) {
+        // Sort operations from most specific (more path params) to least specific
+        operations.sort((a, b) => {
+          const aRef = a.$ref;
+          const bRef = b.$ref;
+          return methodSpecificityMap[bRef] - methodSpecificityMap[aRef];
+        });
+      }
+    }
+  }
+  
+  return resources;
+}
+
 /**
  * Generate StackQL provider extensions
  * @param {Object} options - Options for generation
@@ -234,6 +299,11 @@ export async function generate(options) {
             response: responseInfo
           };
 
+          // Add objectKey to the response info if it exists in the manifest and is for a GET operation
+          if (entry.stackql_object_key && verb === 'get') {
+            methodEntry.response.objectKey = entry.stackql_object_key;
+          }
+
           resources[resource].methods[method] = methodEntry;
           if (sqlverb && sqlverb === 'exec') {
             logger.info(`exec method skipped:  ${resource}.${method}`);
@@ -247,11 +317,14 @@ export async function generate(options) {
         }
       }
       
+      // Sort operations by specificity before injecting into spec
+      const sortedResources = sortOperationsBySpecificity(resources, spec);
+      
       // Inject into spec
       if (!spec.components) {
         spec.components = {};
       }
-      spec.components['x-stackQL-resources'] = resources;
+      spec.components['x-stackQL-resources'] = sortedResources;
       
       // Inject servers if provided
       if (servers) {