@stackql/provider-utils 0.5.6 → 0.5.7

package/package.json

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

package/src/docgen/generator.js

@@ -291,6 +291,7 @@ export async function generateDocsv2(options) {
         outputDir,          // e.g., 'website'
         providerDataDir,    // e.g., 'config/provider-data'
         dereferenced = false,
+        succinct = false,   // use summary instead of description for method/example descriptions
     } = options;
 
     console.log(`documenting ${providerName} (v2)...`);
@@ -338,7 +339,7 @@ export async function generateDocsv2(options) {
         const filePath = path.join(serviceDir, file);
         totalServicesCount++;
         const serviceFolder = `${servicesDir}/${serviceName}`;
-        await createDocsForServicev2(filePath, providerName, serviceName, serviceFolder, dereferenced);
+        await createDocsForServicev2(filePath, providerName, serviceName, serviceFolder, dereferenced, succinct);
     }
 
     console.log(`Processed ${totalServicesCount} services`);
@@ -394,7 +395,7 @@ ${servicesToMarkdown(providerName, secondColumnServices)}
 }
 
 // v2 service processing - uses SchemaTable for collapsible nested fields
-async function createDocsForServicev2(yamlFilePath, providerName, serviceName, serviceFolder, dereferenced = false) {
+async function createDocsForServicev2(yamlFilePath, providerName, serviceName, serviceFolder, dereferenced = false, succinct = false) {
 
     const data = yaml.load(fs.readFileSync(yamlFilePath, 'utf8'));
 
@@ -467,18 +468,18 @@ async function createDocsForServicev2(yamlFilePath, providerName, serviceName, s
 
     // Process each resource in first column
     for (const resource of firstColumn) {
-        await processResourcev2(providerName, serviceFolder, serviceName, resource);
+        await processResourcev2(providerName, serviceFolder, serviceName, resource, succinct);
     }
 
     // Process each resource in second column
     for (const resource of secondColumn) {
-        await processResourcev2(providerName, serviceFolder, serviceName, resource);
+        await processResourcev2(providerName, serviceFolder, serviceName, resource, succinct);
     }
 
     console.log(`Generated documentation (v2) for ${serviceName}`);
 }
 
-async function processResourcev2(providerName, serviceFolder, serviceName, resource) {
+async function processResourcev2(providerName, serviceFolder, serviceName, resource, succinct = false) {
     console.log(`Processing resource (v2): ${resource.name}`);
 
     const resourceFolder = path.join(serviceFolder, resource.name);
@@ -491,6 +492,7 @@ async function processResourcev2(providerName, serviceFolder, serviceName, resou
         providerName,
         serviceName,
         resource,
+        succinct,
     );
     fs.writeFileSync(resourceIndexPath, resourceIndexContent);
 

package/src/docgen/helpers.js

@@ -134,7 +134,7 @@ export function getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, sq
                 }
 
                 // Get response and params using the same function as for SQL verbs
-                const { respProps, respDescription, opDescription, requestBody } = getHttpOperationInfo(
+                const { respProps, respDescription, opDescription, opSummary, requestBody } = getHttpOperationInfo(
                     dereferencedAPI,
                     resolvedPath,
                     resolvedVerb,
@@ -152,6 +152,7 @@ export function getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, sq
                 // Initialize the method with the same structure as SQL methods
                 methods[methodName] = {
                     opDescription,
+                    opSummary,
                     respDescription,
                     properties: {},
                     requiredParams: requiredParams || {},
@@ -177,12 +178,13 @@ export function getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, sq
 
     for (const thisMethod of resourceData.sqlVerbs[sqlVerb]) {
         const {path, httpVerb, mediaType, openAPIDocKey, objectKey, methodName} = getHttpOperationForSqlVerb(thisMethod.$ref, resourceData);
-        const {respProps, respDescription, opDescription, requestBody} = getHttpOperationInfo(dereferencedAPI, path, httpVerb, mediaType, openAPIDocKey, objectKey);
+        const {respProps, respDescription, opDescription, opSummary, requestBody} = getHttpOperationInfo(dereferencedAPI, path, httpVerb, mediaType, openAPIDocKey, objectKey);
         const {requiredParams, optionalParams} = getHttpOperationParams(dereferencedAPI, path, httpVerb);
 
         // Initialize the method object with description and params
         methods[methodName] = {
             opDescription,
+            opSummary,
             respDescription,
             properties: {},
             requiredParams: requiredParams || {},
@@ -383,8 +385,9 @@ function getHttpOperationInfo(dereferencedAPI, path, httpVerb, mediaType, openAP
         throw new Error(`HTTP verb '${httpVerb}' not found for path '${path}'`);
     }
     
-    // Get operation description
+    // Get operation description and summary
     const opDescription = (dereferencedAPI.paths[path][httpVerb].description || '');
+    const opSummary = (dereferencedAPI.paths[path][httpVerb].summary || '');
 
     // Extract request body if it exists
     let requestBody = {};
@@ -474,19 +477,21 @@ function getHttpOperationInfo(dereferencedAPI, path, httpVerb, mediaType, openAP
             respProps: {},
             respDescription: '',
             opDescription,
+            opSummary,
             requestBody
         };
     }
-    
+
     // Check if there's a content section with the mediaType
     const responseObj = dereferencedAPI.paths[path][httpVerb].responses[openAPIDocKey];
-    
+
     // If no content or no mediaType in the response, return empty properties
     if (!responseObj.content || !mediaType || !responseObj.content[mediaType] || !responseObj.content[mediaType].schema) {
         return {
             respProps: {},
             respDescription: responseObj.description || '',
             opDescription,
+            opSummary,
             requestBody
         };
     }
@@ -499,6 +504,7 @@ function getHttpOperationInfo(dereferencedAPI, path, httpVerb, mediaType, openAP
         respProps,
         respDescription: responseObj.description ? responseObj.description : respDescription,
         opDescription,
+        opSummary,
         requestBody
     };
 }

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

@@ -4,7 +4,7 @@ import {
     sanitizeHtml,
 } from '../../helpers.js';
 
-export function createDeleteExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
+export function createDeleteExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, succinct = false) {
     const deleteMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'delete');
 
     // if there are no delete methods, return empty content
@@ -30,7 +30,7 @@ export function createDeleteExamples(providerName, serviceName, resourceName, re
         content += '<TabItem value="' + methodName + '">\n\n';
         
         // Add method description
-        const opDescription = methodDetails.opDescription || 'No description available.';
+        const opDescription = (succinct && methodDetails.opSummary) ? methodDetails.opSummary : (methodDetails.opDescription || 'No description available.');
         content += sanitizeHtml(opDescription);
 
         // Create SQL example

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

@@ -4,7 +4,7 @@ import {
     sanitizeHtml
 } from '../../helpers.js';
 
-export function createExecExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
+export function createExecExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, succinct = false) {
     const execMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'exec');
     
     // if there are no exec methods, return empty content
@@ -30,7 +30,7 @@ export function createExecExamples(providerName, serviceName, resourceName, reso
         content += '<TabItem value="' + methodName + '">\n\n';
         
         // Add method description
-        const opDescription = methodDetails.opDescription || methodDetails.respDescription || 'No description available.';
+        const opDescription = (succinct && methodDetails.opSummary) ? methodDetails.opSummary : (methodDetails.opDescription || methodDetails.respDescription || 'No description available.');
         content += sanitizeHtml(opDescription);
         
         // Create SQL example

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

@@ -4,7 +4,7 @@ import {
     sanitizeHtml
 } from '../../helpers.js';
 
-export function createInsertExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
+export function createInsertExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, succinct = false) {
     const insertMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'insert');
 
     // if there are no insert methods, return empty content
@@ -34,9 +34,8 @@ export function createInsertExamples(providerName, serviceName, resourceName, re
         content += '<TabItem value="' + methodName + '">\n\n';
 
         // Add method description
-        const opDescription = methodDetails.opDescription || 'No description available.';
+        const opDescription = (succinct && methodDetails.opSummary) ? methodDetails.opSummary : (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';

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

@@ -4,7 +4,7 @@ import {
     sanitizeHtml
 } from '../../helpers.js';
 
-export function createSelectExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
+export function createSelectExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, succinct = false) {
     const selectMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'select');
     
     // if there are no select methods, return empty content
@@ -30,7 +30,7 @@ export function createSelectExamples(providerName, serviceName, resourceName, re
         content += '<TabItem value="' + methodName + '">\n\n';
         // content += methodDetails.opDescription || 'No description available.';
         // Add method description
-        const opDescription = methodDetails.opDescription || methodDetails.respDescription || 'No description available.';
+        const opDescription = (succinct && methodDetails.opSummary) ? methodDetails.opSummary : (methodDetails.opDescription || methodDetails.respDescription || 'No description available.');
         content += sanitizeHtml(opDescription);
 
         // Create SQL example

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

@@ -4,7 +4,7 @@ import {
     sanitizeHtml
 } from '../../helpers.js';
 
-export function createUpdateExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, isReplace = false) {
+export function createUpdateExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, isReplace = false, succinct = false) {
     const updateMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, isReplace ? 'replace' : 'update');
     
     // if there are no update methods, return empty content
@@ -34,10 +34,8 @@ 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
-        const opDescription = methodDetails.opDescription || 'No description available.';
+        const opDescription = (succinct && methodDetails.opSummary) ? methodDetails.opSummary : (methodDetails.opDescription || 'No description available.');
         content += sanitizeHtml(opDescription);
         
         // Create SQL example

package/src/docgen/resource/examples.js

@@ -6,26 +6,26 @@ import { createUpdateExamples } from './examples/update-example.js';
 import { createDeleteExamples } from './examples/delete-example.js';
 import { createExecExamples } from './examples/exec-example.js';
 
-export function createExamplesSection(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
+export function createExamplesSection(providerName, serviceName, resourceName, resourceData, dereferencedAPI, succinct = false) {
     let content = '';
-    
+
     // Add SELECT examples
-    content += createSelectExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI);
+    content += createSelectExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, succinct);
 
     // Add INSERT examples
-    content += createInsertExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI);
-    
+    content += createInsertExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, succinct);
+
     // Add UPDATE examples
-    content += createUpdateExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, false);
-    
+    content += createUpdateExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, false, succinct);
+
     // Add REPLACE examples
-    content += createUpdateExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, true);
+    content += createUpdateExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, true, succinct);
 
     // Add DELETE examples
-    content += createDeleteExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI);
+    content += createDeleteExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, succinct);
 
     // Add EXEC examples
-    content += createExecExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI);    
+    content += createExecExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, succinct);
 
     return content;
 }

package/src/docgen/resource/methods.js

@@ -22,7 +22,7 @@ const getRequiredBodyParams = (methodDetails, accessType) => {
     }
 };
 
-export function createMethodsSection(resourceData, dereferencedAPI) {
+export function createMethodsSection(resourceData, dereferencedAPI, succinct = false) {
     
     let content = `\n## Methods\n\n`;
 
@@ -80,7 +80,7 @@ export function createMethodsSection(resourceData, dereferencedAPI) {
     <td><CopyableCode code="${accessType}" /></td>
     <td>${requiredParamsStr}</td>
     <td>${optionalParamsStr}</td>
-    <td>${sanitizeHtml(methodDetails.opDescription)}</td>
+    <td>${sanitizeHtml(succinct && methodDetails.opSummary ? methodDetails.opSummary : methodDetails.opDescription)}</td>
 </tr>`;
         }
     };

package/src/docgen/resource-content.js

@@ -26,13 +26,14 @@ export async function createResourceIndexContentv2(
     providerName,
     serviceName,
     resource,
+    succinct = false,
 ) {
     // Generate each section of the documentation (v2 uses SchemaTable for fields)
     const overviewContent = createOverviewSectionv2(resource.name, resource.type, resource.description, providerName, serviceName);
     const fieldsContent = createFieldsSectionv2(resource.type, resource.resourceData, resource.dereferencedAPI);
-    const methodsContent = resource.type === 'Resource' ? createMethodsSection(resource.resourceData, resource.dereferencedAPI) : '';
+    const methodsContent = resource.type === 'Resource' ? createMethodsSection(resource.resourceData, resource.dereferencedAPI, succinct) : '';
     const paramsContent = resource.type === 'Resource' ? createParamsSection(resource.resourceData, resource.dereferencedAPI) : '';
-    const examplesContent = resource.type === 'Resource' ? createExamplesSection(providerName, serviceName, resource.name, resource.resourceData, resource.dereferencedAPI) : '';
+    const examplesContent = resource.type === 'Resource' ? createExamplesSection(providerName, serviceName, resource.name, resource.resourceData, resource.dereferencedAPI, succinct) : '';
 
     // Combine all sections into the final content
     return `${overviewContent}${fieldsContent}${methodsContent}${paramsContent}${examplesContent}`;