@typespec/tspd 0.70.0-dev.1 → 0.70.0-dev.3

package/dist/src/cli.js

@@ -5,114 +5,96 @@ import yargs from "yargs";
 import { generateExternSignatures } from "./gen-extern-signatures/gen-extern-signatures.js";
 import { generateLibraryDocs } from "./ref-doc/experimental.js";
 try {
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    await import("source-map-support/register.js");
-}
-catch {
-    // package only present in dev.
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  await import("source-map-support/register.js");
+} catch {
+  // package only present in dev.
 }
 function logExperimentalWarning(type) {
-    const log = type === "error"
-        ? (message) => console.error(pc.red(message))
-        : (message) => console.log(pc.yellow(message));
-    log("-".repeat(100));
-    log(`tspd (TypeSpec Library Developer Cli) is experimental and might be ${pc.bold("BREAKING")} between versions.`);
-    if (type === "error") {
-        log(`Add "--enable-experimental" flag to acknowledge this and continue.`);
-    }
-    log("-".repeat(100));
+  const log = type === "error" ? message => console.error(pc.red(message)) : message => console.log(pc.yellow(message));
+  log("-".repeat(100));
+  log(`tspd (TypeSpec Library Developer Cli) is experimental and might be ${pc.bold("BREAKING")} between versions.`);
+  if (type === "error") {
+    log(`Add "--enable-experimental" flag to acknowledge this and continue.`);
+  }
+  log("-".repeat(100));
 }
 async function main() {
-    console.log(`TypeSpec Developer Tools\n`);
-    await yargs(process.argv.slice(2))
-        .scriptName("tspd")
-        .help()
-        .strict()
-        .parserConfiguration({
-        "greedy-arrays": false,
-        "boolean-negation": false,
-    })
-        .option("debug", {
-        type: "boolean",
-        description: "Output debug log messages.",
-        default: false,
-    })
-        .option("pretty", {
-        type: "boolean",
-        description: "Enable color and formatting in TypeSpec's output to make compiler errors easier to read.",
-        default: true,
-    })
-        .option("enable-experimental", {
-        type: "boolean",
-        description: "Acknowledge that the tspd command line is experiemental.",
-        default: false,
-    })
-        .check((args) => {
-        if (args["enable-experimental"]) {
-            logExperimentalWarning("log");
-            return true;
-        }
-        else {
-            logExperimentalWarning("error");
-            process.exit(1);
-        }
-    })
-        .command("doc <entrypoint>", "Generate documentation for a TypeSpec library.", (cmd) => {
-        return cmd
-            .positional("entrypoint", {
-            description: "Path to the library entrypoint.",
-            type: "string",
-            demandOption: true,
-        })
-            .option("output-dir", {
-            type: "string",
-        })
-            .positional("skip-js", {
-            description: "Skip generating JS API docs.",
-            type: "boolean",
-        });
-    }, async (args) => {
-        const resolvedRoot = resolvePath(process.cwd(), args.entrypoint);
-        const host = NodeHost;
-        const diagnostics = await generateLibraryDocs(resolvedRoot, args["output-dir"] ?? resolvePath(resolvedRoot, "docs"), {
-            skipJSApi: args["skip-js"],
-        });
-        // const diagnostics = await generateExternSignatures(host, resolvedRoot);
-        if (diagnostics.length > 0) {
-            logDiagnostics(diagnostics, host.logSink);
-        }
-    })
-        .command("gen-extern-signature <entrypoint>", "Format given list of TypeSpec files.", (cmd) => {
-        return cmd.positional("entrypoint", {
-            description: "Path to the library entrypoint.",
-            type: "string",
-            demandOption: true,
-        });
-    }, async (args) => {
-        const resolvedRoot = resolvePath(process.cwd(), args.entrypoint);
-        const host = NodeHost;
-        const diagnostics = await generateExternSignatures(host, resolvedRoot);
-        if (diagnostics.length > 0) {
-            logDiagnostics(diagnostics, host.logSink);
-        }
-    })
-        .demandCommand(1, "You must use one of the supported commands.").argv;
+  console.log(`TypeSpec Developer Tools\n`);
+  await yargs(process.argv.slice(2)).scriptName("tspd").help().strict().parserConfiguration({
+    "greedy-arrays": false,
+    "boolean-negation": false
+  }).option("debug", {
+    type: "boolean",
+    description: "Output debug log messages.",
+    default: false
+  }).option("pretty", {
+    type: "boolean",
+    description: "Enable color and formatting in TypeSpec's output to make compiler errors easier to read.",
+    default: true
+  }).option("enable-experimental", {
+    type: "boolean",
+    description: "Acknowledge that the tspd command line is experiemental.",
+    default: false
+  }).check(args => {
+    if (args["enable-experimental"]) {
+      logExperimentalWarning("log");
+      return true;
+    } else {
+      logExperimentalWarning("error");
+      process.exit(1);
+    }
+  }).command("doc <entrypoint>", "Generate documentation for a TypeSpec library.", cmd => {
+    return cmd.positional("entrypoint", {
+      description: "Path to the library entrypoint.",
+      type: "string",
+      demandOption: true
+    }).option("output-dir", {
+      type: "string"
+    }).positional("skip-js", {
+      description: "Skip generating JS API docs.",
+      type: "boolean"
+    });
+  }, async args => {
+    const resolvedRoot = resolvePath(process.cwd(), args.entrypoint);
+    const host = NodeHost;
+    const diagnostics = await generateLibraryDocs(resolvedRoot, args["output-dir"] ?? resolvePath(resolvedRoot, "docs"), {
+      skipJSApi: args["skip-js"]
+    });
+    // const diagnostics = await generateExternSignatures(host, resolvedRoot);
+    if (diagnostics.length > 0) {
+      logDiagnostics(diagnostics, host.logSink);
+    }
+  }).command("gen-extern-signature <entrypoint>", "Format given list of TypeSpec files.", cmd => {
+    return cmd.positional("entrypoint", {
+      description: "Path to the library entrypoint.",
+      type: "string",
+      demandOption: true
+    });
+  }, async args => {
+    const resolvedRoot = resolvePath(process.cwd(), args.entrypoint);
+    const host = NodeHost;
+    const diagnostics = await generateExternSignatures(host, resolvedRoot);
+    if (diagnostics.length > 0) {
+      logDiagnostics(diagnostics, host.logSink);
+    }
+  }).demandCommand(1, "You must use one of the supported commands.").argv;
 }
 function internalError(error) {
-    // NOTE: An expected error, like one thrown for bad input, shouldn't reach
-    // here, but be handled somewhere else. If we reach here, it should be
-    // considered a bug and therefore we should not suppress the stack trace as
-    // that risks losing it in the case of a bug that does not repro easily.
-    console.error("Internal error!");
-    console.error("File issue at https://github.com/microsoft/typespec");
-    console.error();
-    console.error(error);
-    process.exit(1);
+  // NOTE: An expected error, like one thrown for bad input, shouldn't reach
+  // here, but be handled somewhere else. If we reach here, it should be
+  // considered a bug and therefore we should not suppress the stack trace as
+  // that risks losing it in the case of a bug that does not repro easily.
+
+  console.error("Internal error!");
+  console.error("File issue at https://github.com/microsoft/typespec");
+  console.error();
+  console.error(error);
+  process.exit(1);
 }
-process.on("unhandledRejection", (error) => {
-    console.error("Unhandled promise rejection!");
-    internalError(error);
+process.on("unhandledRejection", error => {
+  console.error("Unhandled promise rejection!");
+  internalError(error);
 });
-main().catch(internalError);
-//# sourceMappingURL=cli.js.map
+main().catch(internalError);

package/dist/src/gen-extern-signatures/components/decorator-signature-tests.d.ts

@@ -0,0 +1,8 @@
+import * as ay from "@alloy-js/core";
+export interface DecoratorSignatureTests {
+    namespaceName: string;
+    dollarDecoratorRefKey: ay.Refkey;
+    dollarDecoratorsTypeRefKey: ay.Refkey;
+}
+export declare function DecoratorSignatureTests({ namespaceName, dollarDecoratorRefKey, dollarDecoratorsTypeRefKey, }: Readonly<DecoratorSignatureTests>): ay.Children;
+//# sourceMappingURL=decorator-signature-tests.d.ts.map

package/dist/src/gen-extern-signatures/components/decorator-signature-tests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator-signature-tests.d.ts","sourceRoot":"","sources":["../../../../src/gen-extern-signatures/components/decorator-signature-tests.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGrC,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,EAAE,CAAC,MAAM,CAAC;IACjC,0BAA0B,EAAE,EAAE,CAAC,MAAM,CAAC;CACvC;AAED,wBAAgB,uBAAuB,CAAC,EACtC,aAAa,EACb,qBAAqB,EACrB,0BAA0B,GAC3B,EAAE,QAAQ,CAAC,uBAAuB,CAAC,eAenC"}

package/dist/src/gen-extern-signatures/components/decorator-signature-tests.js

@@ -0,0 +1,16 @@
+import { createIntrinsic as _$createIntrinsic, createComponent as _$createComponent } from "@alloy-js/core/jsx-runtime";
+import * as ts from "@alloy-js/typescript";
+export function DecoratorSignatureTests({
+  namespaceName,
+  dollarDecoratorRefKey,
+  dollarDecoratorsTypeRefKey
+}) {
+  return [_$createIntrinsic("hbr", {}), _$createIntrinsic("hbr", {}), _$createComponent(ts.VarDeclaration, {
+    name: "_",
+    type: dollarDecoratorsTypeRefKey,
+    doc: "An error here would mean that the exported decorator is not using the same signature. Make sure to have export const $decName: DecNameDecorator = (...) => ...",
+    get children() {
+      return [dollarDecoratorRefKey, `["${namespaceName}"]`];
+    }
+  })];
+}

package/dist/src/gen-extern-signatures/components/decorator-signature-tests.jsx

@@ -0,0 +1,12 @@
+import * as ts from "@alloy-js/typescript";
+export function DecoratorSignatureTests({ namespaceName, dollarDecoratorRefKey, dollarDecoratorsTypeRefKey, }) {
+    return (<>
+      <hbr />
+      <hbr />
+      <ts.VarDeclaration name="_" type={dollarDecoratorsTypeRefKey} doc="An error here would mean that the exported decorator is not using the same signature. Make sure to have export const $decName: DecNameDecorator = (...) => ...">
+        {dollarDecoratorRefKey}
+        {`["${namespaceName}"]`}
+      </ts.VarDeclaration>
+    </>);
+}
+//# sourceMappingURL=decorator-signature-tests.jsx.map

package/dist/src/gen-extern-signatures/components/decorator-signature-tests.jsx.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator-signature-tests.jsx","sourceRoot":"","sources":["../../../../src/gen-extern-signatures/components/decorator-signature-tests.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAQ3C,MAAM,UAAU,uBAAuB,CAAC,EACtC,aAAa,EACb,qBAAqB,EACrB,0BAA0B,GACQ;IAClC,OAAO,CACL,EACE;MAAA,CAAC,GAAG,CAAC,AAAD,EACJ;MAAA,CAAC,GAAG,CAAC,AAAD,EACJ;MAAA,CAAC,EAAE,CAAC,cAAc,CAChB,IAAI,CAAC,GAAG,CACR,IAAI,CAAC,CAAC,0BAA0B,CAAC,CACjC,GAAG,CAAC,gKAAgK,CAEpK;QAAA,CAAC,qBAAqB,CACtB;QAAA,CAAC,KAAK,aAAa,IAAI,CACzB;MAAA,EAAE,EAAE,CAAC,cAAc,CACrB;IAAA,GAAG,CACJ,CAAC;AACJ,CAAC"}

package/dist/src/gen-extern-signatures/components/decorator-signature-type.d.ts

@@ -0,0 +1,16 @@
+import * as ay from "@alloy-js/core";
+import { MixedParameterConstraint, Model } from "@typespec/compiler";
+import { DecoratorSignature } from "../types.js";
+export interface DecoratorSignatureProps {
+    signature: DecoratorSignature;
+}
+/** Render the type of decorator implementation function  */
+export declare function DecoratorSignatureType(props: Readonly<DecoratorSignatureProps>): ay.Children;
+export interface ParameterTsTypeProps {
+    constraint: MixedParameterConstraint;
+}
+export declare function ParameterTsType({ constraint }: ParameterTsTypeProps): ay.Children;
+export declare function ValueOfModelTsInterfaceBody({ model }: {
+    model: Model;
+}): ay.Children;
+//# sourceMappingURL=decorator-signature-type.d.ts.map

package/dist/src/gen-extern-signatures/components/decorator-signature-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator-signature-type.d.ts","sourceRoot":"","sources":["../../../../src/gen-extern-signatures/components/decorator-signature-type.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAErC,OAAO,EAEL,wBAAwB,EACxB,KAAK,EAON,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,QAAQ,CAAC,uBAAuB,CAAC,eAwC9E;AA+BD,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,wBAAwB,CAAC;CACtC;AACD,wBAAgB,eAAe,CAAC,EAAE,UAAU,EAAE,EAAE,oBAAoB,eAiBnE;AAkHD,wBAAgB,2BAA2B,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,eAsBtE"}

package/dist/src/gen-extern-signatures/components/decorator-signature-type.js

@@ -0,0 +1,404 @@
+import { createComponent as _$createComponent, memo as _$memo } from "@alloy-js/core/jsx-runtime";
+import * as ay from "@alloy-js/core";
+import * as ts from "@alloy-js/typescript";
+import { getSourceLocation, isArrayModelType, isUnknownType } from "@typespec/compiler";
+import { SyntaxKind } from "@typespec/compiler/ast";
+import { typespecCompiler } from "../external-packages/compiler.js";
+import { useTspd } from "./tspd-context.js";
+/** Render the type of decorator implementation function  */
+export function DecoratorSignatureType(props) {
+  const {
+    program
+  } = useTspd();
+  const decorator = props.signature.decorator;
+  const parameters = [{
+    name: "context",
+    type: typespecCompiler.DecoratorContext
+  }, {
+    name: decorator.target.name,
+    type: _$createComponent(TargetParameterTsType, {
+      get type() {
+        return decorator.target.type.type;
+      }
+    })
+  }, ...decorator.parameters.map(param => ({
+    // https://github.com/alloy-framework/alloy/issues/144
+    name: param.rest ? `...${param.name}` : param.name,
+    type: param.rest ? ["(", _$memo(() => _$memo(() => !!param.type)() ? _$createComponent(ParameterTsType, {
+      get constraint() {
+        return extractRestParamConstraint(program, param.type);
+      }
+    }) : undefined), ")[]"] : _$createComponent(ParameterTsType, {
+      get constraint() {
+        return param.type;
+      }
+    }),
+    optional: param.optional
+  }))];
+  return _$createComponent(ts.TypeDeclaration, {
+    "export": true,
+    get name() {
+      return props.signature.typeName;
+    },
+    get doc() {
+      return getDocComment(props.signature.decorator);
+    },
+    get children() {
+      return _$createComponent(ts.FunctionType, {
+        parameters: parameters
+      });
+    }
+  });
+}
+
+/** For a rest param of constraint T[] or valueof T[] return the T or valueof T */
+function extractRestParamConstraint(program, constraint) {
+  let valueType;
+  let type;
+  if (constraint.valueType) {
+    if (constraint.valueType.kind === "Model" && isArrayModelType(program, constraint.valueType)) {
+      valueType = constraint.valueType.indexer.value;
+    } else {
+      return undefined;
+    }
+  }
+  if (constraint.type) {
+    if (constraint.type.kind === "Model" && isArrayModelType(program, constraint.type)) {
+      type = constraint.type.indexer.value;
+    } else {
+      return undefined;
+    }
+  }
+  return {
+    entityKind: "MixedParameterConstraint",
+    type,
+    valueType
+  };
+}
+export function ParameterTsType({
+  constraint
+}) {
+  if (constraint.type && constraint.valueType) {
+    return [_$createComponent(TypeConstraintTSType, {
+      get type() {
+        return constraint.type;
+      }
+    }), " | ", _$createComponent(ValueTsType, {
+      get type() {
+        return constraint.valueType;
+      }
+    })];
+  }
+  if (constraint.valueType) {
+    return _$createComponent(ValueTsType, {
+      get type() {
+        return constraint.valueType;
+      }
+    });
+  } else if (constraint.type) {
+    return _$createComponent(TypeConstraintTSType, {
+      get type() {
+        return constraint.type;
+      }
+    });
+  }
+  return typespecCompiler.Type;
+}
+function TargetParameterTsType(props) {
+  const type = props.type;
+  if (type === undefined) {
+    return typespecCompiler.Type;
+  }
+  if (type.kind === "Union") {
+    const variants = [...type.variants.values()].map(x => x.type).map(getTargetType);
+    return ay.join(new Set(variants).values(), {
+      joiner: " | "
+    });
+  } else {
+    return getTargetType(type);
+  }
+}
+function getTargetType(type) {
+  if (type === undefined || isUnknownType(type)) {
+    return typespecCompiler.Type;
+  } else if (type.kind === "Model" && isReflectionType(type)) {
+    return typespecCompiler[type.name];
+  } else if (type.kind === "Scalar") {
+    // Special case for target type if it is a scalar type(e.g. `string`) then it can only be a Scalar.
+    // In the case of regular parameter it could also be a union of the scalar, or a literal matching the scalar or union of both,
+    // so we only change that when isTarget is true.
+    return typespecCompiler.Scalar;
+  } else {
+    return typespecCompiler.Type;
+  }
+}
+function TypeConstraintTSType({
+  type
+}) {
+  if (type.kind === "Model" && isReflectionType(type)) {
+    return typespecCompiler[type.name];
+  } else if (type.kind === "Union") {
+    const variants = [...type.variants.values()].map(x => x.type);
+    if (variants.every(x => isReflectionType(x))) {
+      return ay.join([...new Set(variants)].map(x => getCompilerType(x.name)), {
+        joiner: " | "
+      });
+    } else {
+      return typespecCompiler.Type;
+    }
+  }
+  return typespecCompiler.Type;
+}
+function getCompilerType(name) {
+  return typespecCompiler[name];
+}
+function ValueTsType({
+  type
+}) {
+  const {
+    program
+  } = useTspd();
+  switch (type.kind) {
+    case "Boolean":
+      return `${type.value}`;
+    case "String":
+      return `"${type.value}"`;
+    case "Number":
+      return `${type.value}`;
+    case "Scalar":
+      return _$createComponent(ScalarTsType, {
+        scalar: type
+      });
+    case "Union":
+      return ay.join([...type.variants.values()].map(x => _$createComponent(ValueTsType, {
+        get type() {
+          return x.type;
+        }
+      })), {
+        joiner: " | "
+      });
+    case "Model":
+      if (isArrayModelType(program, type)) {
+        return ["readonly (", _$createComponent(ValueTsType, {
+          get type() {
+            return type.indexer.value;
+          }
+        }), ")[]"];
+      } else if (isReflectionType(type)) {
+        return getValueOfReflectionType(type);
+      } else {
+        // If its exactly the record type use Record<string, T> instead of the model name.
+        if (type.indexer && type.name === "Record" && type.namespace?.name === "TypeSpec") {
+          return ["Record", "<string, ", _$createComponent(ValueTsType, {
+            get type() {
+              return type.indexer.value;
+            }
+          }), ">"];
+        }
+        if (type.name) {
+          return _$createComponent(LocalTypeReference, {
+            type: type
+          });
+        } else {
+          return _$createComponent(ValueOfModelTsType, {
+            model: type
+          });
+        }
+      }
+  }
+  return "unknown";
+}
+function LocalTypeReference({
+  type
+}) {
+  const {
+    addLocalType
+  } = useTspd();
+  addLocalType(type);
+  return _$createComponent(ts.Reference, {
+    get refkey() {
+      return ay.refkey(type);
+    }
+  });
+}
+function ValueOfModelTsType({
+  model
+}) {
+  return _$createComponent(ts.InterfaceExpression, {
+    get children() {
+      return _$createComponent(ValueOfModelTsInterfaceBody, {
+        model: model
+      });
+    }
+  });
+}
+export function ValueOfModelTsInterfaceBody({
+  model
+}) {
+  return _$createComponent(ay.List, {
+    joiner: ";",
+    enderPunctuation: true,
+    get children() {
+      return [_$memo(() => _$memo(() => !!model.indexer?.value)() && _$createComponent(ts.InterfaceMember, {
+        readonly: true,
+        indexer: "key: string",
+        get type() {
+          return _$createComponent(ValueTsType, {
+            get type() {
+              return model.indexer.value;
+            }
+          });
+        }
+      })), _$createComponent(ay.For, {
+        get each() {
+          return model.properties.values();
+        },
+        children: x => _$createComponent(ts.InterfaceMember, {
+          readonly: true,
+          get name() {
+            return x.name;
+          },
+          get optional() {
+            return x.optional;
+          },
+          get type() {
+            return _$createComponent(ValueTsType, {
+              get type() {
+                return x.type;
+              }
+            });
+          }
+        })
+      })];
+    }
+  });
+}
+function ScalarTsType({
+  scalar
+}) {
+  const {
+    program
+  } = useTspd();
+  const isStd = program.checker.isStdType(scalar);
+  if (isStd) {
+    return getStdScalarTSType(scalar);
+  } else if (scalar.baseScalar) {
+    return _$createComponent(ScalarTsType, {
+      get scalar() {
+        return scalar.baseScalar;
+      }
+    });
+  } else {
+    return "unknown";
+  }
+}
+function getStdScalarTSType(scalar) {
+  switch (scalar.name) {
+    case "numeric":
+    case "decimal":
+    case "decimal128":
+    case "float":
+    case "integer":
+    case "int64":
+    case "uint64":
+      return typespecCompiler.Numeric;
+    case "int8":
+    case "int16":
+    case "int32":
+    case "safeint":
+    case "uint8":
+    case "uint16":
+    case "uint32":
+    case "float64":
+    case "float32":
+      return "number";
+    case "string":
+    case "url":
+      return "string";
+    case "boolean":
+      return "boolean";
+    case "plainDate":
+    case "utcDateTime":
+    case "offsetDateTime":
+    case "plainTime":
+    case "duration":
+    case "bytes":
+      return "unknown";
+    default:
+      const _assertNever = scalar.name;
+      return "unknown";
+  }
+}
+function isReflectionType(type) {
+  return type.kind === "Model" && type.namespace?.name === "Reflection" && type.namespace?.namespace?.name === "TypeSpec";
+}
+function getValueOfReflectionType(type) {
+  switch (type.name) {
+    case "EnumMember":
+    case "Enum":
+      return typespecCompiler.EnumValue;
+    case "Model":
+      return "Record<string, unknown>";
+    default:
+      return "unknown";
+  }
+}
+function getDocComment(type) {
+  const docs = type.node?.docs;
+  if (docs === undefined || docs.length === 0) {
+    return "";
+  }
+  const mainContentLines = [];
+  const tagLines = [];
+  for (const doc of docs) {
+    for (const content of doc.content) {
+      for (const line of content.text.split("\n")) {
+        mainContentLines.push(line);
+      }
+    }
+    for (const tag of doc.tags) {
+      tagLines.push();
+      let first = true;
+      const hasContentFirstLine = checkIfTagHasDocOnSameLine(tag);
+      const tagStart = tag.kind === SyntaxKind.DocParamTag || tag.kind === SyntaxKind.DocTemplateTag ? `@${tag.tagName.sv} ${tag.paramName.sv}` : `@${tag.tagName.sv}`;
+      for (const content of tag.content) {
+        for (const line of content.text.split("\n")) {
+          const cleaned = sanitizeDocComment(line);
+          if (first) {
+            if (hasContentFirstLine) {
+              tagLines.push(`${tagStart} ${cleaned}`);
+            } else {
+              tagLines.push(tagStart, cleaned);
+            }
+            first = false;
+          } else {
+            tagLines.push(cleaned);
+          }
+        }
+      }
+    }
+  }
+  const docLines = [...mainContentLines, ...(tagLines.length > 0 ? [""] : []), ...tagLines];
+  return docLines.join("\n");
+}
+function sanitizeDocComment(doc) {
+  // Issue to escape @internal and other tsdoc tags https://github.com/microsoft/TypeScript/issues/47679
+  return doc.replaceAll("@internal", `@_internal`);
+}
+function checkIfTagHasDocOnSameLine(tag) {
+  const start = tag.content[0]?.pos;
+  const end = tag.content[0]?.end;
+  const file = getSourceLocation(tag.content[0]).file;
+  let hasFirstLine = false;
+  for (let i = start; i < end; i++) {
+    const ch = file.text[i];
+    if (ch === "\n") {
+      break;
+    }
+    // Todo reuse compiler whitespace logic or have a way to get this info from the parser.
+    if (ch !== " ") {
+      hasFirstLine = true;
+    }
+  }
+  return hasFirstLine;
+}