feat: forward since jsdoc tag

compile-to-definitions/index.js

@@ -101,6 +101,14 @@ const resolvePath = (root, ref) => {
 };
 
 const preprocessSchema = (schema, root = schema, path = []) => {
+	if (schema.added) {
+		const added =
+			typeof schema.added === "string" ? `@since ${schema.added}` : "@since";
+		schema.description = schema.description
+			? `${schema.description}\n${added}`
+			: added;
+		delete schema.added;
+	}
 	if (schema.experimental) {
 		const experimental =
 			typeof schema.experimental === "string"
@@ -130,6 +138,7 @@ const preprocessSchema = (schema, root = schema, path = []) => {
 					description: result.description,
 					deprecated: result.deprecated,
 					experimental: result.experimental,
+					added: result.added,
 					anyOf: [property],
 				};
 			} else if (
@@ -142,6 +151,7 @@ const preprocessSchema = (schema, root = schema, path = []) => {
 					description: property.description || result.description,
 					deprecated: property.deprecated || result.deprecated,
 					experimental: property.experimental || result.experimental,
+					added: property.added || result.added,
 					anyOf: property.oneOf,
 				};
 				preprocessSchema(schema.properties[key], root, [...path, key]);

format-schemas/index.js

@@ -115,6 +115,8 @@ const PROPERTIES = [
 	"deprecated",
 
 	"experimental",
+
+	"added",
 ];
 
 const processJson = processSchema.bind(null, {

generate-types/index.js

@@ -629,41 +629,29 @@ const printError = (diagnostic) => {
 				.trim();
 
 		let commentText = normalizeText(symbol.getDocumentationComment(checker));
-		const deprecatedTags = symbol
-			.getJsDocTags(checker)
-			.filter((tag) => tag.name === "deprecated");
-
-		const experimentalTags = symbol
-			.getJsDocTags(checker)
-			.filter((tag) => tag.name === "experimental");
+		const jsDocTags = symbol.getJsDocTags(checker);
+		const forwardedTagNames = ["since", "deprecated", "experimental"];
+		const forwardedTags = forwardedTagNames.flatMap((name) =>
+			jsDocTags.filter((tag) => tag.name === name),
+		);
 
-		if (
-			!commentText &&
-			deprecatedTags.length === 0 &&
-			experimentalTags.length === 0
-		) {
+		if (!commentText && forwardedTags.length === 0) {
 			return "";
 		}
 
 		const lines = commentText ? commentText.split("\n") : [];
 
-		for (const tag of deprecatedTags) {
-			const text = normalizeText(tag.text);
-			if (text && !commentText) {
-				lines.push(...text.split("\n"));
-				lines.push("@deprecated");
-			} else {
-				lines.push(text ? `@deprecated ${text}` : "@deprecated");
-			}
-		}
-
-		for (const tag of experimentalTags) {
+		for (const tag of forwardedTags) {
 			const text = normalizeText(tag.text);
-			if (text && !commentText) {
+			if (
+				text &&
+				!commentText &&
+				(tag.name === "deprecated" || tag.name === "experimental")
+			) {
 				lines.push(...text.split("\n"));
-				lines.push("@experimental");
+				lines.push(`@${tag.name}`);
 			} else {
-				lines.push(text ? `@experimental ${text}` : "@experimental");
+				lines.push(text ? `@${tag.name} ${text}` : `@${tag.name}`);
 			}
 		}
 

precompile-schemas/index.js

@@ -111,6 +111,7 @@ const EXCLUDED_PROPERTIES = [
 	"description",
 	"deprecated",
 	"experimental",
+	"added",
 	"cli",
 	"implements",
 	"tsType",

schemas-lint/index.js

@@ -52,6 +52,7 @@ for (const filename of schemas) {
 			"link",
 			"deprecated",
 			"experimental",
+			"added",
 		];
 
 		const isReference = (schema) => {