feat: Support awsuiSystem jsdoc tags

just-boris · just-boris · commit 2285ec35746f · 2025-04-09T15:59:01.000+02:00
diff --git a/fixtures/components/system-tag/button/index.tsx b/fixtures/components/system-tag/button/index.tsx
@@ -0,0 +1,10 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as React from 'react';
+import { ButtonProps } from './interfaces';
+
+export { ButtonProps };
+
+export default function Button(props: ButtonProps) {
+  return <div />;
+}
diff --git a/fixtures/components/system-tag/button/interfaces.ts b/fixtures/components/system-tag/button/interfaces.ts
@@ -0,0 +1,28 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export interface ButtonProps {
+  variant?: ButtonProps.Variant;
+
+  /**
+   * @awsuiSystem core
+   */
+  size: 'small' | 'medium' | 'large';
+
+  color?:
+    | 'normal'
+    /** @awsuiSystem core */
+    | 'danger';
+}
+
+export namespace ButtonProps {
+  export type Variant =
+    | 'primary'
+    | 'secondary'
+    /** @awsuiSystem core */
+    | 'fire'
+    /**
+     * @awsuiSystem core
+     * @awsuiSystem experimental
+     */
+    | 'ultra';
+}
diff --git a/fixtures/components/system-tag/tree/index.tsx b/fixtures/components/system-tag/tree/index.tsx
@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as React from 'react';
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface TreeProps {}
+
+/**
+ * @awsuiSystem core
+ */
+export default function Tree() {
+  return <div />;
+}
diff --git a/fixtures/components/system-tag/tsconfig.json b/fixtures/components/system-tag/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./**/*.tsx"]
+}
diff --git a/src/components/component-definition.ts b/src/components/component-definition.ts
@@ -10,14 +10,26 @@ import type {
   ComponentRegion,
   EventHandler,
 } from './interfaces';
-import type { ExpandedProp } from './extractor';
+import type { ExpandedProp, ExtractedDescription } from './extractor';
 import { getObjectDefinition } from './object-definition';
 
-function getCommentTag(property: ExpandedProp, name: string) {
-  const tag = property.description.tags.find(tag => tag.name === name);
+function getCommentTag(description: ExtractedDescription, name: string) {
+  const tag = description.tags.find(tag => tag.name === name);
   return tag ? tag.text ?? '' : undefined;
 }
 
+function getMultipleCommentTag(description: ExtractedDescription, name: string) {
+  const tags = description.tags
+    .filter(tag => tag.name === name)
+    .map(tag => {
+      if (!tag.text) {
+        throw new Error(`Tag ${name} is missing text`);
+      }
+      return tag.text;
+    });
+  return tags.length > 0 ? tags : undefined;
+}
+
 function castI18nTag(tag: string | undefined) {
   return tag === undefined ? undefined : true;
 }
@@ -27,6 +39,7 @@ export function buildComponentDefinition(
   props: Array<ExpandedProp>,
   functions: Array<ExpandedProp>,
   defaultValues: Record<string, string>,
+  componentDescription: ExtractedDescription,
   checker: ts.TypeChecker
 ): ComponentDefinition {
   const regions = props.filter(prop => prop.type === 'React.ReactNode');
@@ -36,15 +49,18 @@ export function buildComponentDefinition(
   return {
     name,
     releaseStatus: 'stable',
+    description: componentDescription.text,
+    systemTag: getMultipleCommentTag(componentDescription, 'awsuiSystem'),
     regions: regions.map(
       (region): ComponentRegion => ({
         name: region.name,
-        displayName: getCommentTag(region, 'displayname'),
+        displayName: getCommentTag(region.description, 'displayname'),
         description: region.description.text,
         isDefault: region.name === 'children',
-        visualRefreshTag: getCommentTag(region, 'visualrefresh'),
-        deprecatedTag: getCommentTag(region, 'deprecated'),
-        i18nTag: castI18nTag(getCommentTag(region, 'i18n')),
+        systemTag: getMultipleCommentTag(region.description, 'awsuiSystem'),
+        visualRefreshTag: getCommentTag(region.description, 'visualrefresh'),
+        deprecatedTag: getCommentTag(region.description, 'deprecated'),
+        i18nTag: castI18nTag(getCommentTag(region.description, 'i18n')),
       })
     ),
     functions: functions.map(
@@ -66,35 +82,41 @@ export function buildComponentDefinition(
       })
     ),
     properties: onlyProps.map((property): ComponentProperty => {
-      const { type, inlineType } = getObjectDefinition(property.type, property.rawType, checker);
+      const { type, inlineType } = getObjectDefinition(property.type, property.rawType, property.rawTypeNode, checker);
       return {
         name: property.name,
         type: type,
         inlineType: inlineType,
         optional: property.isOptional,
         description: property.description.text,
         defaultValue: defaultValues[property.name],
-        visualRefreshTag: getCommentTag(property, 'visualrefresh'),
-        deprecatedTag: getCommentTag(property, 'deprecated'),
-        analyticsTag: getCommentTag(property, 'analytics'),
-        i18nTag: castI18nTag(getCommentTag(property, 'i18n')),
+        systemTag: getMultipleCommentTag(property.description, 'awsuiSystem'),
+        visualRefreshTag: getCommentTag(property.description, 'visualrefresh'),
+        deprecatedTag: getCommentTag(property.description, 'deprecated'),
+        analyticsTag: getCommentTag(property.description, 'analytics'),
+        i18nTag: castI18nTag(getCommentTag(property.description, 'i18n')),
       };
     }),
     events: events.map((event): EventHandler => {
-      const { detailType, detailInlineType, cancelable } = extractEventDetails(event.rawType, checker);
+      const { detailType, detailInlineType, cancelable } = extractEventDetails(
+        event.rawType,
+        event.rawTypeNode,
+        checker
+      );
       return {
         name: event.name,
         description: event.description.text,
         cancelable,
         detailType,
         detailInlineType,
-        deprecatedTag: getCommentTag(event, 'deprecated'),
+        systemTag: getMultipleCommentTag(event.description, 'awsuiSystem'),
+        deprecatedTag: getCommentTag(event.description, 'deprecated'),
       };
     }),
   };
 }
 
-function extractEventDetails(type: ts.Type, checker: ts.TypeChecker) {
+function extractEventDetails(type: ts.Type, typeNode: ts.TypeNode | undefined, checker: ts.TypeChecker) {
   const realType = type.getNonNullableType();
   const handlerName = realType.aliasSymbol?.getName();
   if (handlerName !== 'CancelableEventHandler' && handlerName !== 'NonCancelableEventHandler') {
@@ -103,7 +125,7 @@ function extractEventDetails(type: ts.Type, checker: ts.TypeChecker) {
   const cancelable = handlerName === 'CancelableEventHandler';
   const detailType = realType.aliasTypeArguments?.[0];
   if (detailType && detailType.getProperties().length > 0) {
-    const { type, inlineType } = getObjectDefinition(stringifyType(detailType, checker), detailType, checker);
+    const { type, inlineType } = getObjectDefinition(stringifyType(detailType, checker), detailType, typeNode, checker);
     return {
       detailType: type,
       detailInlineType: inlineType,
diff --git a/src/components/extractor.ts b/src/components/extractor.ts
@@ -10,15 +10,18 @@ import {
   unwrapNamespaceDeclaration,
 } from './type-utils';
 
+export interface ExtractedDescription {
+  text: string | undefined;
+  tags: Array<{ name: string; text: string | undefined }>;
+}
+
 export interface ExpandedProp {
   name: string;
   type: string;
   isOptional: boolean;
   rawType: ts.Type;
-  description: {
-    text: string | undefined;
-    tags: Array<{ name: string; text: string | undefined }>;
-  };
+  rawTypeNode: ts.TypeNode | undefined;
+  description: ExtractedDescription;
 }
 
 export function extractDefaultValues(exportSymbol: ts.Symbol, checker: ts.TypeChecker) {
@@ -87,6 +90,7 @@ export function extractProps(propsSymbol: ts.Symbol, checker: ts.TypeChecker) {
         name: value.name,
         type: stringifyType(type, checker),
         rawType: type,
+        rawTypeNode: (declaration as ts.PropertyDeclaration).type,
         isOptional: isOptional(type),
         description: getDescription(value.getDocumentationComment(checker), declaration),
       };
@@ -124,6 +128,7 @@ export function extractFunctions(propsSymbol: ts.Symbol, checker: ts.TypeChecker
         name: value.name,
         type: stringifyType(realType, checker),
         rawType: realType,
+        rawTypeNode: (declaration as ts.PropertyDeclaration).type,
         isOptional: isOptional(type),
         description: getDescription(value.getDocumentationComment(checker), declaration),
       };
diff --git a/src/components/index.ts b/src/components/index.ts
@@ -8,6 +8,7 @@ import { buildComponentDefinition } from './component-definition';
 import { extractDefaultValues, extractExports, extractFunctions, extractProps } from './extractor';
 import type { ComponentDefinition } from './interfaces';
 import { bootstrapTypescriptProject } from '../bootstrap/typescript';
+import { extractDeclaration, getDescription } from './type-utils';
 
 function componentNameFromPath(componentPath: string) {
   const directoryName = pathe.dirname(componentPath);
@@ -51,7 +52,11 @@ export function documentComponents(
       const props = extractProps(propsSymbol, checker);
       const functions = extractFunctions(propsSymbol, checker);
       const defaultValues = extractDefaultValues(componentSymbol, checker);
+      const componentDescription = getDescription(
+        componentSymbol.getDocumentationComment(checker),
+        extractDeclaration(componentSymbol)
+      );
 
-      return buildComponentDefinition(name, props, functions, defaultValues, checker);
+      return buildComponentDefinition(name, props, functions, defaultValues, componentDescription, checker);
     });
 }
diff --git a/src/components/interfaces.ts b/src/components/interfaces.ts
@@ -8,33 +8,35 @@ export interface ComponentDefinition {
   version?: string;
   /** @deprecated */
   description?: string;
+  systemTag?: Array<string>;
   properties: ComponentProperty[];
   regions: ComponentRegion[];
   functions: ComponentFunction[];
   events: EventHandler[];
 }
 
-export interface ComponentProperty {
+interface Taggable {
+  analyticsTag?: string;
+  deprecatedTag?: string;
+  visualRefreshTag?: string;
+  i18nTag?: true | undefined;
+  systemTag?: Array<string>;
+}
+
+export interface ComponentProperty extends Taggable {
   name: string;
   description?: string;
   optional: boolean;
   type: string;
   inlineType?: TypeDefinition;
   defaultValue?: string;
-  analyticsTag?: string;
-  deprecatedTag?: string;
-  visualRefreshTag?: string;
-  i18nTag?: true | undefined;
 }
 
-export interface ComponentRegion {
+export interface ComponentRegion extends Taggable {
   name: string;
   description?: string;
   displayName?: string;
   isDefault: boolean;
-  deprecatedTag?: string;
-  visualRefreshTag?: string;
-  i18nTag?: true | undefined;
 }
 
 export interface ComponentFunction {
@@ -73,14 +75,14 @@ export interface FunctionParameter {
 export interface UnionTypeDefinition {
   name: string;
   type: 'union';
+  systemTag?: Record<string, Array<string>>;
   values: string[];
 }
 
-export interface EventHandler {
+export interface EventHandler extends Taggable {
   name: string;
   description?: string;
   detailType?: string;
   detailInlineType?: TypeDefinition;
   cancelable: boolean;
-  deprecatedTag?: string;
 }
diff --git a/src/components/object-definition.ts b/src/components/object-definition.ts
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import ts from 'typescript';
 import type { TypeDefinition, UnionTypeDefinition } from './interfaces';
-import { extractDeclaration, isOptional, stringifyType } from './type-utils';
+import { extractDeclaration, extractMemberComments, isOptional, stringifyType } from './type-utils';
 
 function isArrayType(type: ts.Type) {
   const symbol = type.getSymbol();
@@ -15,6 +15,7 @@ function isArrayType(type: ts.Type) {
 export function getObjectDefinition(
   type: string,
   rawType: ts.Type,
+  rawTypeNode: ts.TypeNode | undefined,
   checker: ts.TypeChecker
 ): { type: string; inlineType?: TypeDefinition } {
   const realType = rawType.getNonNullableType();
@@ -31,7 +32,7 @@ export function getObjectDefinition(
     return { type };
   }
   if (realType.isUnionOrIntersection()) {
-    return getUnionTypeDefinition(realTypeName, realType, checker);
+    return getUnionTypeDefinition(realTypeName, realType, rawTypeNode, checker);
   }
   if (realType.getProperties().length > 0) {
     return {
@@ -78,36 +79,47 @@ export function getObjectDefinition(
   return { type };
 }
 
+function getSimpleType(type: ts.UnionOrIntersectionType) {
+  if (type.types.every(subtype => subtype.isStringLiteral())) {
+    return 'string';
+  }
+  if (type.types.every(subtype => subtype.isNumberLiteral())) {
+    return 'number';
+  }
+  return undefined;
+}
+
 function getUnionTypeDefinition(
   realTypeName: string,
   realType: ts.UnionOrIntersectionType,
+  typeNode: ts.TypeNode | undefined,
   checker: ts.TypeChecker
 ): { type: string; inlineType: UnionTypeDefinition } {
-  if (realType.types.every(subtype => subtype.isStringLiteral())) {
-    return {
-      type: 'string',
-      inlineType: {
-        name: realTypeName,
-        type: 'union',
-        values: realType.types.map(subtype => (subtype as ts.StringLiteralType).value),
-      },
-    };
-  } else if (realType.types.every(subtype => subtype.isNumberLiteral())) {
-    return {
-      type: 'number',
-      inlineType: {
-        name: realTypeName,
-        type: 'union',
-        values: realType.types.map(subtype => (subtype as ts.NumberLiteralType).value.toString()),
-      },
-    };
-  }
+  const memberComments = extractMemberComments(realType, typeNode);
+  const values = realType.types.map(subtype =>
+    subtype.isLiteral() ? subtype.value.toString() : stringifyType(subtype, checker)
+  );
+
   return {
-    type: realTypeName,
+    type: getSimpleType(realType) ?? realTypeName,
     inlineType: {
       name: realTypeName,
       type: 'union',
-      values: realType.types.map(subtype => stringifyType(subtype, checker)),
+      systemTag: memberComments.length > 0 ? zipMemberComments(values, memberComments) : undefined,
+      values: values,
     },
   };
 }
+
+function zipMemberComments(values: Array<string>, memberComments: Array<string | undefined>) {
+  const systemTag: Record<string, Array<string>> = {};
+  for (const value of values) {
+    const index = values.indexOf(value);
+    const comment = memberComments[index];
+    if (!comment) {
+      continue;
+    }
+    systemTag[value] = Array.from(comment.matchAll(/@awsuiSystem\s+(\w+)/g), ([_, system]) => system);
+  }
+  return systemTag;
+}
diff --git a/src/components/type-utils.ts b/src/components/type-utils.ts
diff --git a/test/components/system-tag.test.ts b/test/components/system-tag.test.ts
