An open source design system that's fully customizable and agent ready
TypeScript
fix(core): doc-literals guard should skip @deprecated union members (#4085)
Cindy Zhangfd02a9bbab08
diff --git a/packages/core/src/docPropLiterals.test.ts b/packages/core/src/docPropLiterals.test.tsindex 8f88380be4..8b1ed95887 100644--- a/packages/core/src/docPropLiterals.test.ts+++ b/packages/core/src/docPropLiterals.test.ts@@ -103,6 +103,27 @@ function stripComments(src: string): string {return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');}+/**+ * Literal members of a union flagged `@deprecated` in source. Docs shouldn't+ * advertise a deprecated value as a legal option (the prose can still mention+ * it), so the guard doesn't require it to be inlined. Detected from the *raw*+ * declaration, because the registry parses members from comment-stripped+ * source where the `@deprecated` marker is already gone. A member is+ * deprecated when a `@deprecated` JSDoc or line comment immediately precedes+ * it in the union — e.g. a member `'c'` written just after a+ * `@deprecated`-tagged block comment is treated as deprecated and dropped,+ * while undecorated members like `'a'` and `'b'` are kept.+ */+function deprecatedLiteralMembers(rawRhs: string): Set<string> {+ const out = new Set<string>();+ const marker =+ /(?:\/\*\*?[\s\S]*?@deprecated[\s\S]*?\*\/|\/\/[^\n]*@deprecated[^\n]*)\s*\|\s*('[^']*'|-?\d+(?:\.\d+)?|null|undefined)/g;+ for (const m of rawRhs.matchAll(marker)) {+ out.add(m[1]);+ }+ return out;+}+/*** Names a consumer would have to write values for, given a type expression.* Skips string literals, generic parameters, and the type arguments of any@@ -161,13 +182,23 @@ for (const file of findFiles(SRC_DIR, ['.ts', '.tsx'])) {if (file.includes('.test.')) {continue;}- const src = stripComments(readFileSync(file, 'utf8'));+ const raw = readFileSync(file, 'utf8');+ const src = stripComments(raw);+ // Raw type declarations, keyed by name, so we can inspect `@deprecated`+ // markers the comment-stripped `src` has already removed.+ const rawTypeRhs = new Map<string, string>();+ for (const m of raw.matchAll(+ /export type ([A-Z][A-Za-z0-9]*)(?:<[^>]*>)?\s*=\s*([^;]+);/g,+ )) {+ rawTypeRhs.set(m[1], m[2]);+ }for (const m of src.matchAll(/export type ([A-Z][A-Za-z0-9]*)(?:<[^>]*>)?\s*=\s*([^;]+);/g,)) {const [, name, rhsRaw] = m;const rhs = rhsRaw.replace(/\s+/g, ' ').trim();if (LITERAL_UNION.test(rhs)) {+ const deprecated = deprecatedLiteralMembers(rawTypeRhs.get(name) ?? '');literalUnions.set(name,rhs@@ -175,6 +206,7 @@ for (const file of findFiles(SRC_DIR, ['.ts', '.tsx'])) {.split('|').map(s => s.trim()).filter(Boolean)+ .filter(member => !deprecated.has(member)).join(' | '),);} else {@@ -562,6 +594,10 @@ describe('doc prop types surface their literal values (#1645)', () => {expect(literalUnions.get('TableSortDirection')).toBe("'ascending' | 'descending'",);+ // @deprecated members are dropped: SwitchLabelSpacing is+ // `'hug' | 'spread' | (@deprecated) 'default'`, and docs shouldn't have to+ // advertise the deprecated value as a legal option.+ expect(literalUnions.get('SwitchLabelSpacing')).toBe("'hug' | 'spread'");expect([...requiredUnions('InputStatus').keys()]).toContain('InputStatusType',);