feat: Add --raw-jsdoc option to include full JSDoc in schema

README.md

@@ -47,6 +47,7 @@ By default, the command-line generator will use the `tsconfig.json` file in the
   -e, --expose <expose>          Type exposing (choices: "all", "none", "export", default: "export")
   -j, --jsDoc <extended>         Read JsDoc annotations (choices: "none", "basic", "extended", default: "extended")
   --markdown-description         Generate `markdownDescription` in addition to `description`.
+  --raw-jsdoc                    Include the full raw JSDoc comment as `rawJsDoc` in the schema.
   --functions <functions>        How to handle functions. `fail` will throw an error. `comment` will add a comment. `hide` will treat the function like a NeverType or HiddenType.
                                  (choices: "fail", "comment", "hide", default: "comment")
   --minify                       Minify generated schema (default: false)

factory/parser.ts

@@ -77,7 +77,7 @@ export function createParser(program: ts.Program, config: CompletedConfig, augme
         if (config.jsDoc === "extended") {
             return new AnnotatedNodeParser(
                 nodeParser,
-                new ExtendedAnnotationsReader(typeChecker, extraTags, config.markdownDescription),
+                new ExtendedAnnotationsReader(typeChecker, extraTags, config.markdownDescription, config.rawJsDoc),
             );
         } else if (config.jsDoc === "basic") {
             return new AnnotatedNodeParser(nodeParser, new BasicAnnotationsReader(extraTags));

src/AnnotationsReader/ExtendedAnnotationsReader.ts

@@ -2,13 +2,15 @@ import json5 from "json5";
 import type ts from "typescript";
 import type { Annotations } from "../Type/AnnotatedType.js";
 import { symbolAtNode } from "../Utils/symbolAtNode.js";
+import { getRawJsDoc } from "../Utils/getRawJsDoc.js";
 import { BasicAnnotationsReader } from "./BasicAnnotationsReader.js";
 
 export class ExtendedAnnotationsReader extends BasicAnnotationsReader {
     public constructor(
         private typeChecker: ts.TypeChecker,
         extraTags?: Set<string>,
         private markdownDescription?: boolean,
+        private rawJsDoc?: boolean,
     ) {
         super(extraTags);
     }
@@ -44,21 +46,34 @@ export class ExtendedAnnotationsReader extends BasicAnnotationsReader {
             return undefined;
         }
 
+        const annotations: { description?: string; markdownDescription?: string; rawJsDoc?: string } = {};
+
         const comments: ts.SymbolDisplayPart[] = symbol.getDocumentationComment(this.typeChecker);
-        if (!comments || !comments.length) {
-            return undefined;
-        }
 
-        const markdownDescription = comments
-            .map((comment) => comment.text)
-            .join(" ")
-            .replace(/\r/g, "")
-            .trim();
+        if (comments && comments.length) {
+            const markdownDescription = comments
+                .map((comment) => comment.text)
+                .join(" ")
+                .replace(/\r/g, "")
+                .trim();
 
-        const description = markdownDescription.replace(/(?<=[^\n])\n(?=[^\n*-])/g, " ").trim();
+            annotations.description = markdownDescription.replace(/(?<=[^\n])\n(?=[^\n*-])/g, " ").trim();
+
+            if (this.markdownDescription) {
+                annotations.markdownDescription = markdownDescription;
+            }
+        }
 
-        return this.markdownDescription ? { description, markdownDescription } : { description };
+        if (this.rawJsDoc) {
+            const rawJsDoc = getRawJsDoc(node)?.trim();
+            if (rawJsDoc) {
+                annotations.rawJsDoc = rawJsDoc;
+            }
+        }
+
+        return Object.keys(annotations).length ? annotations : undefined;
     }
+
     private getTypeAnnotation(node: ts.Node): Annotations | undefined {
         const symbol = symbolAtNode(node);
         if (!symbol) {

src/Config.ts

@@ -8,6 +8,7 @@ export interface Config {
     topRef?: boolean;
     jsDoc?: "none" | "extended" | "basic";
     markdownDescription?: boolean;
+    rawJsDoc?: boolean;
     sortProps?: boolean;
     strictTuples?: boolean;
     skipTypeCheck?: boolean;
@@ -27,6 +28,7 @@ export const DEFAULT_CONFIG: Omit<Required<Config>, "path" | "type" | "schemaId"
     topRef: true,
     jsDoc: "extended",
     markdownDescription: false,
+    rawJsDoc: false,
     sortProps: true,
     strictTuples: false,
     skipTypeCheck: false,

src/Utils/getRawJsDoc.ts

@@ -0,0 +1,39 @@
+import ts from "typescript";
+
+export function getRawJsDoc(node: ts.Node): string | undefined {
+    const sourceFile = node.getSourceFile();
+    const jsDocNodes = ts.getJSDocCommentsAndTags(node);
+
+    if (!jsDocNodes || jsDocNodes.length === 0) {
+        return undefined;
+    }
+
+    let rawText = "";
+
+    for (const jsDoc of jsDocNodes) {
+        rawText += jsDoc.getFullText(sourceFile) + "\n";
+    }
+
+    rawText = rawText.trim();
+
+    return getTextWithoutStars(rawText).trim();
+}
+
+function getTextWithoutStars(inputText: string) {
+    const innerTextWithStars = inputText.replace(/^\/\*\*[^\S\n]*\n?/, "").replace(/(\r?\n)?[^\S\n]*\*\/$/, "");
+
+    return innerTextWithStars
+        .split(/\n/)
+        .map((line) => {
+            const trimmedLine = line.trimStart();
+
+            if (trimmedLine[0] !== "*") {
+                return line;
+            }
+
+            const textStartPos = trimmedLine[1] === " " ? 2 : 1;
+
+            return trimmedLine.substring(textStartPos);
+        })
+        .join("\n");
+}

test/config.test.ts

@@ -64,10 +64,14 @@ function assertSchema(
         expect(typeof actual).toBe("object");
         expect(actual).toEqual(expected);
 
+        const keywords: string[] = [];
+        if (config.markdownDescription) keywords.push("markdownDescription");
+        if (config.rawJsDoc) keywords.push("rawJsDoc");
+
         const validator = new Ajv({
             // skip full check if we are not encoding refs
             validateFormats: config.encodeRefs === false ? undefined : true,
-            keywords: config.markdownDescription ? ["markdownDescription"] : undefined,
+            keywords: keywords.length ? keywords : undefined,
         });
 
         addFormats(validator);
@@ -341,6 +345,18 @@ describe("config", () => {
             markdownDescription: true,
         }),
     );
+    it(
+        "jsdoc-raw",
+        assertSchema("jsdoc-raw", {
+            type: "MyObject",
+            expose: "export",
+            topRef: false,
+            jsDoc: "extended",
+            sortProps: true,
+            markdownDescription: true,
+            rawJsDoc: true,
+        }),
+    );
     it(
         "tsconfig-support",
         assertSchema(

test/config/jsdoc-raw/main.ts

@@ -0,0 +1,169 @@
+/**
+ * @title Raw Test Schema Interface
+ * @description Top-level interface: This interface is used to test the rawJsDoc output.
+ * It includes various formatting quirks, inline tags such as {@link SomeReference}, and multiple JSDoc sections.
+ *
+ * @markdownDescription **Markdown version:** Markdown description which should be <b>preserved</b>
+ *
+ * Additional info: Top-level details should be completely preserved in raw form.
+ */
+export interface MyObject {
+    /**
+     * @title Single-line Title and Description
+     * @description Single-line comment for raw extraction.
+     */
+    singleLine: string;
+
+    /**
+     * @title Multiline Field Title
+     * @description This is a multiline description.
+     * It spans multiple lines to test the preservation of newlines.
+     *
+     * @note 123
+     * @format date-time
+     */
+    multilineField: number;
+
+    /**
+     * This field has a comment without explicit tags.
+     * It includes an inline reference: {@link ExampleReference} and extra text on several lines.
+     *
+     * The raw output should preserve this whole block as is.
+     */
+    noTagField: boolean;
+
+    /**
+     * @title Field with Special Formatting
+     * @description   Extra spaces and indentation should be preserved.
+     *
+     * @pattern /^\w+$/
+     */
+    specialFormat: string;
+
+    /**
+     * Some initial descriptive text that is not tagged.
+     *
+     * @description Field with initial untagged text followed by a tag.
+     * @default 42
+     *
+     * Further comments in the same block should be preserved entirely.
+     */
+    initialText: number;
+
+    /**
+     * Some *code block*:
+     * ```yaml
+     * name: description
+     * length: 42
+     * ```
+     *
+     * Some list:
+     * - one
+     * - two
+     * - and three...
+     *
+     * @description This field tests `inline code` and <b>bold text</b>.
+     *
+     * Also includes an inline link: {@link https://example.com} and additional commentary.
+     */
+    markdownField: string;
+
+    /**
+     * @title Tag Only Field
+     * @note Only raw content should be available.
+     * @customTag Tag only content!
+     */
+    tagOnlyField: string;
+
+    /**
+     * @title Tag Only Field
+     * @description
+     * @note Only raw content should be available.
+     * @customTag Tag only content!
+     */
+    tagOnlyFieldWithDescription: string;
+
+    /** Some text */
+    oneLineJsDoc: string;
+
+    /** Some *text* - {@link https://example.com} - @see the `link` */
+    oneLineJsDocComplex: string;
+
+    /**  */
+    emptyJsDoc1?: null;
+
+    /**
+     *
+     */
+    emptyJsDoc2?: null;
+
+    noJsDoc?: null;
+
+    /**
+     * Some ignored comment description
+     *
+     * @description Export field description
+     * @default {"length": 10}
+     * @nullable
+     */
+    exportString: MyExportString;
+    /**
+     * @description Export field description
+     * @default "private"
+     */
+    privateString: MyPrivateString;
+
+    /**
+     * @title Non empty array
+     */
+    numberArray: MyNonEmptyArray<number>;
+
+    /**
+     * @nullable
+     */
+    number: number;
+
+    /**
+     * Some more examples:
+     * ```yaml
+     * name: description
+     * length: 42
+     * ```
+     */
+    description: InheritedExample["description"];
+
+    /**
+     * @default ""
+     */
+    inheritedDescription: InheritedExample["description"];
+}
+
+/**
+ * @title My export string
+ */
+export type MyExportString = string;
+/**
+ * @title My private string
+ */
+type MyPrivateString = string;
+/**
+ * @minItems 1
+ */
+export type MyNonEmptyArray<T> = T[];
+
+/**
+ * @title Inherited Example Interface
+ * @description This interface is used to test inherited descriptions.
+ */
+export interface InheritedExample {
+    /**
+     * This is an inherited description.
+     *
+     * It may include multiple at-tags:
+     * @title Inherited Title
+     * @description Inherited description text.
+     *
+     * It contains an inline link: {@link https://example.com} and additional commentary.
+     */
+    description: string;
+}