Merge branch 'main' into copilot/change-objects-to-maps

Author: pmcelhaney

.changeset/add-jsdoc-generation.md

@@ -0,0 +1,13 @@
+---
+"counterfact": minor
+---
+
+Add JSDoc comment generation for types from OpenAPI metadata
+
+Generated TypeScript types now include inline JSDoc comments derived from the OpenAPI spec:
+
+- Schema-level JSDoc from `description`/`summary`
+- Property-level JSDoc including `description`, `@example`, `@default`, `@format`, and `@deprecated`
+- Operation-level JSDoc from operation `summary`/`description`
+
+This improves IDE hover documentation and AI-assisted development workflows.

.github/workflows/create-issues.yml

@@ -16,7 +16,7 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Install Python dependencies
         run: pip install pyyaml

src/typescript-generator/coder.ts

@@ -20,6 +20,10 @@ export class Coder {
     return "";
   }
 
+  public jsdoc(): string {
+    return "";
+  }
+
   public write(script: Script): string {
     if (this.requirement.isReference) {
       return script.import(this);
@@ -83,6 +87,7 @@ export interface ExportStatement {
   id: string;
   isDefault: boolean;
   isType: boolean;
+  jsdoc: string;
   typeDeclaration: string;
   name?: string;
   code?: string | { raw: string };

src/typescript-generator/jsdoc.ts

@@ -0,0 +1,59 @@
+/**
+ * Builds a JSDoc comment string from OpenAPI schema metadata.
+ * Returns an empty string if there is no relevant metadata.
+ */
+export function buildJsDoc(data: Record<string, unknown>): string {
+  const lines: string[] = [];
+
+  const description = data["description"] as string | undefined;
+  const summary = data["summary"] as string | undefined;
+  const example = data["example"];
+  const examples = data["examples"] as
+    | Record<string, { value?: unknown }>
+    | undefined;
+  const defaultValue = data["default"];
+  const format = data["format"] as string | undefined;
+  const deprecated = data["deprecated"] as boolean | undefined;
+
+  const mainText = description ?? summary;
+
+  if (mainText) {
+    // Escape */ to prevent prematurely closing the JSDoc block
+    const escaped = String(mainText).replace(/\*\//gu, "* /");
+    const textLines = escaped.split("\n");
+
+    for (const line of textLines) {
+      lines.push(` * ${line}`);
+    }
+  }
+
+  if (format !== undefined) {
+    lines.push(` * @format ${format}`);
+  }
+
+  if (defaultValue !== undefined) {
+    lines.push(` * @default ${JSON.stringify(defaultValue)}`);
+  }
+
+  // Use scalar `example`, or fall back to the first value from `examples`
+  const exampleValue =
+    example !== undefined
+      ? example
+      : examples !== undefined
+        ? Object.values(examples)[0]?.value
+        : undefined;
+
+  if (exampleValue !== undefined) {
+    lines.push(` * @example ${JSON.stringify(exampleValue)}`);
+  }
+
+  if (deprecated === true) {
+    lines.push(` * @deprecated`);
+  }
+
+  if (lines.length === 0) {
+    return "";
+  }
+
+  return `/**\n${lines.join("\n")}\n */\n`;
+}

src/typescript-generator/operation-type-coder.ts

@@ -1,6 +1,7 @@
 import nodePath from "node:path";
 
 import { CONTEXT_FILE_TOKEN } from "./context-file-token.js";
+import { buildJsDoc } from "./jsdoc.js";
 import { ParameterExportTypeCoder } from "./parameter-export-type-coder.js";
 import { ParametersTypeCoder } from "./parameters-type-coder.js";
 import { READ_ONLY_COMMENTS } from "./read-only-comments.js";
@@ -117,6 +118,10 @@ export class OperationTypeCoder extends TypeCoder {
       : `HTTP_${this.requestMethod.toUpperCase()}`;
   }
 
+  public override jsdoc(): string {
+    return buildJsDoc(this.requirement.data);
+  }
+
   public override names(): Generator<string> {
     return super.names(this.getOperationBaseName());
   }

src/typescript-generator/parameters-type-coder.ts

@@ -1,5 +1,6 @@
 import nodePath from "node:path";
 
+import { buildJsDoc } from "./jsdoc.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
 import type { Requirement } from "./requirement.js";
@@ -39,9 +40,12 @@ export class ParametersTypeCoder extends TypeCoder {
           ? parameter.get("schema")!
           : parameter;
 
-        return `"${name}"${optionalFlag}: ${new SchemaTypeCoder(schema).write(
-          script,
-        )}`;
+        const comment = buildJsDoc(parameter.data);
+        const commentPrefix = comment ? `\n${comment}` : "";
+
+        const typeString = new SchemaTypeCoder(schema).write(script);
+
+        return `${commentPrefix}"${name}"${optionalFlag}: ${typeString}`;
       });
 
     if (typeDefinitions.length === 0) {

src/typescript-generator/schema-type-coder.ts

@@ -1,3 +1,4 @@
+import { buildJsDoc } from "./jsdoc.js";
 import { TypeCoder } from "./type-coder.js";
 import type { Requirement } from "./requirement.js";
 import type { Script } from "./script.js";
@@ -9,6 +10,10 @@ export class SchemaTypeCoder extends TypeCoder {
     );
   }
 
+  public override jsdoc(): string {
+    return buildJsDoc(this.requirement.data);
+  }
+
   public additionalPropertiesType(script: Script): string {
     const { additionalProperties, properties } = this.requirement.data as {
       additionalProperties: { type?: string };
@@ -51,9 +56,12 @@ export class SchemaTypeCoder extends TypeCoder {
         typedData.required?.includes(name) || propertyData.required === true;
       const optionalFlag = isRequired ? "" : "?";
 
-      return `"${name}"${optionalFlag}: ${new SchemaTypeCoder(property).write(
-        script,
-      )}`;
+      const comment = buildJsDoc(property.data);
+      const commentPrefix = comment ? `\n${comment}` : "";
+
+      return `${commentPrefix}"${name}"${optionalFlag}: ${new SchemaTypeCoder(
+        property,
+      ).write(script)}`;
     });
 
     if (typedData.additionalProperties) {

src/typescript-generator/script.ts

@@ -78,6 +78,7 @@ export class Script {
       id: coder.id,
       isDefault,
       isType,
+      jsdoc: "",
       typeDeclaration: coder.typeDeclaration(this.exports, this),
     };
 
@@ -87,6 +88,7 @@ export class Script {
       .then((availableCoder) => {
         exportStatement.name = name;
         exportStatement.code = availableCoder.write(this);
+        exportStatement.jsdoc = availableCoder.jsdoc();
 
         return availableCoder;
       })
@@ -227,13 +229,21 @@ export class Script {
   public exportStatements(): string[] {
     return Array.from(
       this.exports.values(),
-      ({ beforeExport, code, isDefault, isType, name, typeDeclaration }) => {
+      ({
+        beforeExport,
+        code,
+        isDefault,
+        isType,
+        jsdoc,
+        name,
+        typeDeclaration,
+      }) => {
         if (typeof code === "object" && code !== null && "raw" in code) {
           return code.raw;
         }
 
         if (isDefault) {
-          return `${beforeExport}export default ${code as string};`;
+          return `${jsdoc}${beforeExport}export default ${code as string};`;
         }
 
         const keyword = isType ? "type" : "const";
@@ -242,7 +252,7 @@ export class Script {
             ? ""
             : `:${typeDeclaration ?? ""}`;
 
-        return `${beforeExport}export ${keyword} ${name ?? ""}${typeAnnotation} = ${code as string};`;
+        return `${jsdoc}${beforeExport}export ${keyword} ${name ?? ""}${typeAnnotation} = ${code as string};`;
       },
     );
   }