@stackql/provider-utils 0.1.0

package/src/docgen/resource/methods.js

@@ -0,0 +1,90 @@
+// src/docgen/resource/methods.js
+import { 
+    cleanDescription, 
+    getSqlMethodsWithOrderedFields,
+    sanitizeHtml
+} from '../helpers.js';
+
+export function createMethodsSection(resourceData, dereferencedAPI) {
+    
+    let content = `\n## Methods\n\n`;
+
+    content += 'The following methods are available for this resource:\n\n';
+
+    // Add the table header
+    content += `<table>
+<thead>
+    <tr>
+    <th>Name</th>
+    <th>Accessible by</th>
+    <th>Required Params</th>
+    <th>Optional Params</th>
+    <th>Description</th>
+    </tr>
+</thead>
+<tbody>`;
+
+    const selectMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'select');
+    const insertMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'insert');
+    const updateMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'update');
+    const replaceMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'replace');
+    const deleteMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'delete');
+    const execMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'exec');
+
+    // console.dir(selectMethods, { depth: null, colors: true });
+
+    // Helper function to add methods to the table
+    const addMethodsToTable = (methods, accessType) => {
+        for (const [methodName, methodDetails] of Object.entries(methods)) {
+            console.info(`Adding ${accessType} method to table: ${methodName}`);
+            
+            // Format required params as comma-delimited list with hyperlinks
+            const requiredParamsArr = Object.keys(methodDetails.requiredParams || {});
+            const requiredParamsStr = requiredParamsArr.length > 0 
+                ? requiredParamsArr.map(param => `<a href="#parameter-${param}"><code>${param}</code></a>`).join(', ') 
+                : '';
+            
+            // Format optional params as comma-delimited list with hyperlinks
+            const optionalParamsArr = Object.keys(methodDetails.optionalParams || {});
+            const optionalParamsStr = optionalParamsArr.length > 0 
+                ? optionalParamsArr.map(param => `<a href="#parameter-${param}"><code>${param}</code></a>`).join(', ') 
+                : '';
+            
+            // Add the method row to the table
+            content += `
+<tr>
+    <td><a href="#${methodName}"><CopyableCode code="${methodName}" /></a></td>
+    <td><CopyableCode code="${accessType}" /></td>
+    <td>${requiredParamsStr}</td>
+    <td>${optionalParamsStr}</td>
+    <td>${sanitizeHtml(methodDetails.opDescription)}</td>
+</tr>`;
+        }
+    };
+
+    // Add all methods to the table by type
+    console.info(`Processing select methods...`);
+    addMethodsToTable(selectMethods, 'select');
+    
+    console.info(`Processing insert methods...`);
+    addMethodsToTable(insertMethods, 'insert');
+    
+    console.info(`Processing update methods...`);
+    addMethodsToTable(updateMethods, 'update');
+    
+    console.info(`Processing replace methods...`);
+    addMethodsToTable(replaceMethods, 'replace');
+    
+    console.info(`Processing delete methods...`);
+    addMethodsToTable(deleteMethods, 'delete');
+    
+    console.info(`Processing exec methods...`);
+    addMethodsToTable(execMethods, 'exec');
+
+    // Close the table
+    content += `
+</tbody>
+</table>`;
+
+    return content;
+}

package/src/docgen/resource/overview.js

@@ -0,0 +1,39 @@
+// src/docgen/resource/overview.js
+import { 
+    getIndefiniteArticle, 
+} from '../helpers.js';
+
+export function createOverviewSection(resourceName, providerName, serviceName) {
+
+  let content = `--- 
+title: ${resourceName}
+hide_title: false
+hide_table_of_contents: false
+keywords:
+  - ${resourceName}
+  - ${serviceName}
+  - ${providerName}
+  - infrastructure-as-code
+  - configuration-as-data
+  - cloud inventory
+description: Query, deploy and manage ${providerName} resources using SQL
+custom_edit_url: null
+image: /img/providers/${providerName}/stackql-${providerName}-provider-featured-image.png
+---
+
+import CopyableCode from '@site/src/components/CopyableCode/CopyableCode';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Creates, updates, deletes, gets or lists ${getIndefiniteArticle(resourceName)} <code>${resourceName}</code> resource.
+
+## Overview
+<table><tbody>
+<tr><td><b>Name</b></td><td><code>${resourceName}</code></td></tr>
+<tr><td><b>Type</b></td><td>Resource</td></tr>
+<tr><td><b>Id</b></td><td><CopyableCode code="${providerName}.${serviceName}.${resourceName}" /></td></tr>
+</tbody></table>
+
+`;
+    return content;
+}

package/src/docgen/resource/parameters.js

@@ -0,0 +1,76 @@
+// src/docgen/resource/parameters.js
+import { 
+    getSqlMethodsWithOrderedFields,
+    sanitizeHtml 
+} from '../helpers.js';
+
+const mdCodeAnchor = "`";
+
+export function createParamsSection(resourceData, dereferencedAPI) {
+    let content = '\n\n## Parameters\n\n';
+
+    content += 'Parameters can be passed in the `WHERE` clause of a query. ' +
+               'Check the [Methods](#methods) section to see which parameters are required or optional for each operation.\n\n';
+ 
+    // Get all methods at once
+    const allMethodTypes = ['select', 'insert', 'update', 'replace', 'delete', 'exec'];
+    const allMethods = allMethodTypes.flatMap(type => 
+        Object.values(getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, type))
+    );
+    
+    // Collect all unique parameters in one pass
+    const requiredParams = {};
+    const optionalParams = {};
+    
+    allMethods.forEach(method => {
+        // Add required params
+        Object.entries(method.requiredParams || {}).forEach(([name, details]) => {
+            requiredParams[name] = details;
+        });
+        
+        // Add optional params
+        Object.entries(method.optionalParams || {}).forEach(([name, details]) => {
+            optionalParams[name] = details;
+        });
+    });
+
+    // Add the table header
+    content += `<table>
+<thead>
+    <tr>
+    <th>Name</th>
+    <th>Datatype</th>
+    <th>Description</th>
+    </tr>
+</thead>
+<tbody>`;            
+
+    // Helper function to add parameter rows
+    const addParamRows = (params) => {
+        // Sort parameters alphabetically for better readability
+        const sortedParamNames = Object.keys(params).sort();
+        
+        for (const paramName of sortedParamNames) {
+            const paramDetails = params[paramName];
+            content += `
+<tr id="parameter-${paramName}">
+    <td><CopyableCode code="${paramName}" /></td>
+    <td><code>${paramDetails.type || ''}</code></td>
+    <td>${sanitizeHtml(paramDetails.description) || ''}</td>
+</tr>`;
+        }
+    };
+
+    // Add required parameter rows
+    addParamRows(requiredParams);
+    
+    // Add optional parameter rows
+    addParamRows(optionalParams);
+    
+    // Close the table
+    content += `
+</tbody>
+</table>`;
+
+    return content;
+}

package/src/docgen/resource-content.js

@@ -0,0 +1,25 @@
+// src/docgen/resource-content.js
+
+import { createOverviewSection } from './resource/overview.js';
+import { createFieldsSection } from './resource/fields.js';
+import { createMethodsSection } from './resource/methods.js';
+import { createParamsSection } from './resource/parameters.js';
+import { createExamplesSection } from './resource/examples.js';
+ 
+export async function createResourceIndexContent(
+    providerName, 
+    serviceName, 
+    resourceName, 
+    resourceData, 
+    dereferencedAPI,
+) {
+    // Generate each section of the documentation
+    const overviewContent = createOverviewSection(resourceName, providerName, serviceName);
+    const fieldsContent = createFieldsSection(resourceData, dereferencedAPI);
+    const methodsContent = createMethodsSection(resourceData, dereferencedAPI);
+    const paramsContent = createParamsSection(resourceData, dereferencedAPI);
+    const examplesContent = createExamplesSection(providerName, serviceName, resourceName, resourceData, dereferencedAPI);
+
+    // Combine all sections into the final content
+    return `${overviewContent}${fieldsContent}${methodsContent}${paramsContent}${examplesContent}`;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// src/index.js
+
+// Main entry point for Node.js
+export * as docgen from './docgen/index.js';