quickbase-js 0.1.0-beta.7 → 0.1.0-beta.9

package/open-api/generate-unified-interface.ts

@@ -1,4 +1,5 @@
-// open-api/generate-unified-interface.ts
+#!/usr/bin/env node
+console.log("Script started");
 
 import {
   readFileSync,
@@ -7,12 +8,27 @@ import {
   existsSync,
   readdirSync,
 } from "fs";
+console.log("FS modules imported");
+
 import { join, dirname } from "path";
+console.log("Path modules imported");
+
 import { fileURLToPath } from "url";
+console.log("URL module imported");
+
 import { OpenAPIV2 } from "openapi-types";
-import { simplifyName } from "../src/utils.ts";
+console.log("openapi-types imported");
+
+import { Project } from "ts-morph";
+console.log("ts-morph imported");
+
+import { generateJsDoc } from "./utils/generateJsDoc.js";
+
+const simplifyName = (str: string): string => str;
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+console.log("__dirname set:", __dirname);
+
 const SPEC_FILE = join(__dirname, "output", "quickbase-fixed.json");
 const OUTPUT_DIR = join(__dirname, "..", "src", "generated-unified");
 const OUTPUT_FILE = join(OUTPUT_DIR, "QuickbaseClient.ts");
@@ -52,30 +68,18 @@ function mapRefToType(
     const refParts = schema.$ref.split("/");
     const model = refParts[refParts.length - 1];
     const pascalModel = model.charAt(0).toUpperCase() + model.slice(1);
-    const camelModel = model.charAt(0).toLowerCase() + model.slice(1);
     if (availableModels.includes(pascalModel)) {
       modelImports.add(pascalModel);
       return pascalModel;
-    } else if (availableModels.includes(camelModel)) {
-      modelImports.add(camelModel);
-      return camelModel;
     }
     missingTypes.add(pascalModel);
-    console.warn(
-      `Type ${pascalModel} not found in /generated/models, defaulting to 'any'`
-    );
+    console.warn(`Type ${pascalModel} not found, defaulting to 'any'`);
     return "any";
   }
 
   if ("type" in schema) {
     if (schema.type === "object" && schema.properties) {
       const props = schema.properties;
-      if (props.data && props.data.format === "binary") {
-        return "ArrayBuffer"; // Map binary object to ArrayBuffer
-      }
-      if (props.content && props.content.format === "yaml") {
-        return "string"; // Map YAML object to string
-      }
       const propTypes = Object.entries(props).map(([key, prop]) => {
         const propSchema = prop as OpenAPIV2.SchemaObject;
         const propType = mapRefToType(
@@ -104,31 +108,64 @@ function mapRefToType(
       );
       return `${itemType}[]`;
     }
-    if (schema.type === "object" && schema.additionalProperties) {
-      const additionalProps = schema.additionalProperties as
-        | OpenAPIV2.SchemaObject
-        | OpenAPIV2.ReferenceObject
-        | boolean;
-      if (typeof additionalProps === "boolean") {
-        return "{ [key: string]: any }";
-      }
-      const valueType = mapRefToType(
-        additionalProps,
-        modelImports,
-        spec,
-        depth + 1,
-        availableModels,
-        missingTypes
-      );
-      return `{ [key: string]: ${valueType} }`;
-    }
     return mapOpenApiTypeToTs(schema.type);
   }
 
   return "any";
 }
 
-function generateInterface() {
+interface PropertyDetail {
+  name: string;
+  type: string;
+  required: boolean;
+  jsdoc?: string;
+}
+
+function parseInterfaceProperties(
+  modelName: string,
+  modelsDir: string
+): PropertyDetail[] {
+  const project = new Project();
+  const filePath = join(modelsDir, `${modelName}.ts`);
+  if (!existsSync(filePath)) {
+    console.warn(`Model file ${filePath} not found for ${modelName}`);
+    return [];
+  }
+
+  const sourceFile = project.addSourceFileAtPath(filePath);
+  const interfaceDec = sourceFile.getInterface(modelName);
+  if (!interfaceDec) {
+    console.warn(`Interface ${modelName} not found in ${filePath}`);
+    return [];
+  }
+
+  return interfaceDec.getProperties().map((prop) => {
+    const jsDocs = prop.getJsDocs();
+    const jsdocText =
+      jsDocs.length > 0 ? jsDocs[0].getDescription().trim() : undefined;
+    return {
+      name: prop.getName(),
+      type: prop.getType().getText(prop),
+      required: !prop.hasQuestionToken(),
+      jsdoc: jsdocText,
+    };
+  });
+}
+
+interface ParamDetail {
+  name: string;
+  type: string;
+  required: boolean;
+  properties: PropertyDetail[];
+}
+
+function generateInterface(includeResponseProperties: boolean = false): void {
+  console.log(
+    "Generating interface with includeResponseProperties:",
+    includeResponseProperties
+  );
+
+  console.log("Checking spec file:", SPEC_FILE);
   if (!existsSync(SPEC_FILE)) {
     console.error(
       `Spec file ${SPEC_FILE} not found. Run 'npm run fix-spec' first.`
@@ -136,12 +173,24 @@ function generateInterface() {
     process.exit(1);
   }
 
-  console.log("Generating unified QuickbaseClient interface...");
-  const spec = JSON.parse(
-    readFileSync(SPEC_FILE, "utf8")
-  ) as OpenAPIV2.Document;
+  console.log("Reading spec file...");
+  const specContent = readFileSync(SPEC_FILE, "utf8");
+  const spec: OpenAPIV2.Document = JSON.parse(specContent);
+  console.log("Spec parsed, keys:", Object.keys(spec));
+
   const { paths } = spec;
+  if (!paths) {
+    console.error("No 'paths' in spec");
+    process.exit(1);
+  }
 
+  console.log("Checking models directory:", MODELS_DIR);
+  if (!existsSync(MODELS_DIR)) {
+    console.error(
+      `Models directory ${MODELS_DIR} not found. Run 'npm run gen:openapi' first.`
+    );
+    process.exit(1);
+  }
   const availableModels = readdirSync(MODELS_DIR)
     .filter((file) => file.endsWith(".ts") && !file.startsWith("index"))
     .map((file) => file.replace(".ts", ""));
@@ -155,7 +204,6 @@ function generateInterface() {
     paths as OpenAPIV2.PathsObject
   )) {
     if (!methodsObj) continue;
-
     for (const [method, operation] of Object.entries(
       methodsObj as OpenAPIV2.PathItemObject
     )) {
@@ -163,71 +211,89 @@ function generateInterface() {
       if (!op || !op.operationId) continue;
 
       const opId = simplifyName(op.operationId);
-      const summary = op.summary || "No description available.";
-      const params = (op.parameters || [])
-        .filter((p) => {
-          const param = p as OpenAPIV2.Parameter;
+      const summary = op.summary || "No description.";
+      const docLink = `https://developer.quickbase.com/operation/${op.operationId}`;
+
+      const paramDetails: ParamDetail[] = (op.parameters || [])
+        .filter((p: OpenAPIV2.ParameterObject | OpenAPIV2.ReferenceObject) => {
+          const param = p as OpenAPIV2.ParameterObject;
           return !["QB-Realm-Hostname", "Authorization", "User-Agent"].includes(
-            "name" in param ? param.name : ""
+            param.name || ""
           );
         })
-        .map((param: OpenAPIV2.Parameter) => {
-          if (!("name" in param)) return "";
-          let type: string;
-          if ("schema" in param && param.schema) {
+        .map((param: OpenAPIV2.ParameterObject | OpenAPIV2.ReferenceObject) => {
+          const p = param as OpenAPIV2.ParameterObject;
+          if (!p.name) return null;
+          let type = "any";
+          let properties: PropertyDetail[] = [];
+          if ("schema" in p && p.schema) {
             type = mapRefToType(
-              param.schema,
+              p.schema,
               modelImports,
               spec,
               1,
               availableModels,
               missingTypes
             );
-          } else if ("type" in param && param.type) {
-            type = mapOpenApiTypeToTs(param.type);
-          } else {
-            console.warn(
-              `Parameter ${param.name} in ${opId} has no type or schema, defaulting to 'any'`
-            );
-            type = "any";
+            if ("$ref" in p.schema && p.schema.$ref) {
+              const refParts = p.schema.$ref.split("/");
+              const model = refParts[refParts.length - 1];
+              const pascalModel =
+                model.charAt(0).toUpperCase() + model.slice(1);
+              properties = parseInterfaceProperties(pascalModel, MODELS_DIR);
+            }
+          } else if ("type" in p && p.type) {
+            type = mapOpenApiTypeToTs(p.type);
           }
-          const paramName = param.in === "body" ? "body" : param.name;
-          return `${paramName}${param.required ? "" : "?"}: ${type}`;
+          const paramName = p.in === "body" ? "body" : p.name;
+          return {
+            name: paramName,
+            type,
+            required: p.required || false,
+            properties,
+          };
         })
-        .filter((param) => param !== "")
+        .filter((p): p is ParamDetail => p !== null);
+
+      const params = paramDetails
+        .map((p) => `${p.name}${p.required ? "" : "?"}: ${p.type}`)
         .join("; ");
 
-      const successResponses = ["200", "207"]
-        .map((code) => ({
-          code,
-          response: op.responses?.[code] as
-            | OpenAPIV2.ResponseObject
-            | undefined,
-        }))
-        .filter(({ response }) => response?.schema);
-      const returnTypes = successResponses.map(({ response }) =>
-        mapRefToType(
-          response!.schema,
-          modelImports,
-          spec,
-          1,
-          availableModels,
-          missingTypes
+      const returnTypes = ["200", "207"]
+        .map(
+          (code) => op.responses?.[code] as OpenAPIV2.ResponseObject | undefined
         )
-      );
-      const uniqueReturnTypes = [...new Set(returnTypes)];
+        .filter((response) => response?.schema)
+        .map((response) =>
+          mapRefToType(
+            response!.schema,
+            modelImports,
+            spec,
+            1,
+            availableModels,
+            missingTypes
+          )
+        );
       const returnType =
-        uniqueReturnTypes.length > 1
-          ? uniqueReturnTypes.join(" | ")
-          : uniqueReturnTypes[0] || "void";
-
-      const jsDoc = [
-        `  /**`,
-        `   * ${summary}`,
-        `   * @param params - Parameters for the ${opId} operation`,
-        `   * @returns A promise resolving to the ${opId} response`,
-        `   */`,
-      ].join("\n");
+        returnTypes.length > 1
+          ? returnTypes.join(" | ")
+          : returnTypes[0] || "void";
+
+      const returnTypeDetails: PropertyDetail[] =
+        includeResponseProperties &&
+        returnTypes.length === 1 &&
+        returnTypes[0] !== "void"
+          ? parseInterfaceProperties(returnTypes[0], MODELS_DIR)
+          : [];
+
+      const jsDoc = generateJsDoc({
+        summary,
+        opId,
+        paramDetails,
+        returnType,
+        returnTypeDetails,
+        docLink,
+      });
 
       methods.push(
         `${jsDoc}\n  ${opId}: (params: { ${params} }) => Promise<${returnType}>;`
@@ -235,20 +301,11 @@ function generateInterface() {
     }
   }
 
-  // Always write the missing-types-report.json to reflect the current state
-  if (missingTypes.size > 0) {
-    console.log(
-      "Missing types detected (defaulted to 'any'):",
-      Array.from(missingTypes)
-    );
-  } else {
-    console.log("No missing types detected.");
-  }
+  console.log("Writing missing types report...");
   writeFileSync(
     join(OUTPUT_DIR, "missing-types-report.json"),
     JSON.stringify({ missingTypes: Array.from(missingTypes) }, null, 2)
   );
-  console.log("Missing types report saved to missing-types-report.json");
 
   const importStatement =
     modelImports.size > 0
@@ -256,22 +313,24 @@ function generateInterface() {
           .sort()
           .join(", ")} } from "../generated/models";`
       : "";
-  console.log(`Imports: ${Array.from(modelImports).join(", ")}`);
-
   const interfaceContent = `// Generated on ${new Date().toISOString()}\n${importStatement}\n\nexport interface QuickbaseClient {\n${methods.join(
     "\n"
   )}\n}\n`;
 
+  console.log("Ensuring output directory exists...");
   if (!existsSync(OUTPUT_DIR)) {
     mkdirSync(OUTPUT_DIR, { recursive: true });
   }
   writeFileSync(OUTPUT_FILE, interfaceContent, "utf8");
-  console.log(`Generated ${OUTPUT_FILE}`);
+  console.log("Generated:", OUTPUT_FILE);
 }
 
+console.log("Entering try block");
 try {
-  generateInterface();
+  generateInterface(true); // Toggle response properties here
 } catch (error) {
-  console.error("Generation failed:", error);
+  console.error("Error in generateInterface:", error);
   process.exit(1);
 }
+
+console.log("Script completed");