Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(docsite): link changelog contributors to their GitHub profiles (#3252)

Joey48b01afd4359
diff --git a/apps/docsite/src/__tests__/changelog-linkify.test.ts b/apps/docsite/src/__tests__/changelog-linkify.test.ts
new file mode 100644
index 0000000000..08cd0662fa
--- /dev/null
+++ b/apps/docsite/src/__tests__/changelog-linkify.test.ts
@@ -0,0 +1,122 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the changelog markdown linkifiers.
+ *
+ * Run: pnpm -F @astryxdesign/docsite test
+ */
+
+import {describe, it, expect} from 'vitest';
+import {
+ linkifyPRs,
+ linkifyContributors,
+ linkifyComponents,
+ stripTitle,
+} from '../components/changelogLinkify';
+
+describe('linkifyPRs', () => {
+ it('links bare PR references', () => {
+ expect(linkifyPRs('Fix spinner (#2717)')).toBe(
+ 'Fix spinner ([#2717](https://github.com/facebook/astryx/pull/2717))',
+ );
+ });
+
+ it('leaves already-linked references untouched', () => {
+ const already = '[#2717](https://github.com/facebook/astryx/pull/2717)';
+ expect(linkifyPRs(already)).toBe(already);
+ });
+});
+
+describe('linkifyContributors', () => {
+ it('links standalone contributor bullets to GitHub profiles', () => {
+ const input = ['- @cixzhang', '- @marie-lucas', '- @nynexman4464'].join(
+ '\n',
+ );
+ expect(linkifyContributors(input)).toBe(
+ [
+ '- [@cixzhang](https://github.com/cixzhang)',
+ '- [@marie-lucas](https://github.com/marie-lucas)',
+ '- [@nynexman4464](https://github.com/nynexman4464)',
+ ].join('\n'),
+ );
+ });
+
+ it('does not touch scoped package-name bullets', () => {
+ const input = '- @astryxdesign/core';
+ expect(linkifyContributors(input)).toBe(input);
+ });
+
+ it('does not touch inline @ mentions inside prose', () => {
+ const input = '- Thanks to @cixzhang for the fix';
+ expect(linkifyContributors(input)).toBe(input);
+ });
+
+ it('handles handles with hyphens but not leading/trailing ones', () => {
+ expect(linkifyContributors('- @marie-lucas')).toBe(
+ '- [@marie-lucas](https://github.com/marie-lucas)',
+ );
+ });
+
+ it('preserves the blank line separating the contributor list from the next block', () => {
+ const input = ['- @cixzhang', '', '---', '', '# 0.1.0'].join('\n');
+ expect(linkifyContributors(input)).toBe(
+ [
+ '- [@cixzhang](https://github.com/cixzhang)',
+ '',
+ '---',
+ '',
+ '# 0.1.0',
+ ].join('\n'),
+ );
+ });
+});
+
+describe('linkifyComponents', () => {
+ it('links bare and XDS-prefixed component names', () => {
+ const names = ['Button'];
+ expect(linkifyComponents('Use Button here', names)).toBe(
+ 'Use [Button](/components/Button) here',
+ );
+ expect(linkifyComponents('Use XDSButton here', names)).toBe(
+ 'Use [XDSButton](/components/Button) here',
+ );
+ });
+
+ it('does not link inside code spans or existing links', () => {
+ const names = ['Button'];
+ expect(linkifyComponents('`Button`', names)).toBe('`Button`');
+ expect(linkifyComponents('[Button](/x)', names)).toBe('[Button](/x)');
+ });
+});
+
+describe('stripTitle', () => {
+ it('removes the leading h1 title line', () => {
+ expect(stripTitle('# @astryxdesign/core\n\n# 0.1.1\n')).toBe('# 0.1.1\n');
+ });
+});
+
+describe('full changelog pipeline', () => {
+ it('linkifies contributors without mangling package bullets or PRs', () => {
+ const md = [
+ '#### Fixes',
+ '',
+ '- Fix Button spinner (#2717)',
+ '- @astryxdesign/core import note',
+ '',
+ '#### Contributors',
+ '',
+ '- @cixzhang',
+ '- @ejhammond',
+ ].join('\n');
+
+ const out = linkifyContributors(linkifyPRs(md));
+ expect(out).toContain(
+ '[#2717](https://github.com/facebook/astryx/pull/2717)',
+ );
+ expect(out).toContain('[@cixzhang](https://github.com/cixzhang)');
+ expect(out).toContain('[@ejhammond](https://github.com/ejhammond)');
+ // Scoped package bullet must remain a plain bullet.
+ expect(out).toContain('- @astryxdesign/core import note');
+ expect(out).not.toContain('[@astryxdesign');
+ });
+});
diff --git a/apps/docsite/src/components/ChangelogView.tsx b/apps/docsite/src/components/ChangelogView.tsx
index dec207e234..30e2f30c95 100644
--- a/apps/docsite/src/components/ChangelogView.tsx
+++ b/apps/docsite/src/components/ChangelogView.tsx
@@ -11,43 +11,13 @@ import {Section} from '@astryxdesign/core/Section';
import {TabList, Tab} from '@astryxdesign/core/TabList';
import {Carousel} from '@astryxdesign/core/Carousel';
import {typeScaleVars} from '@astryxdesign/core/theme/tokens.stylex';
-import {GITHUB_REPO} from '../constants';
import {layout} from '../layout.stylex';
-
-function linkifyPRs(markdown: string): string {
- return markdown.replace(/(?<!\[)#(\d+)/g, `[#$1](${GITHUB_REPO}/pull/$1)`);
-}
-
-function stripTitle(markdown: string): string {
- return markdown.replace(/^#\s+.+\n+/, '');
-}
-
-function linkifyComponents(markdown: string, names: string[]): string {
- if (names.length === 0) {
- return markdown;
- }
-
- const nameToHref = new Map<string, string>();
- for (const name of names) {
- nameToHref.set(name, `/components/${name}`);
- nameToHref.set('XDS' + name, `/components/${name}`);
- }
-
- const sorted = [...nameToHref.keys()].sort((a, b) => b.length - a.length);
- const escaped = sorted.map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
- const pattern = new RegExp(
- '(?<!`|\\[)\\b(' + escaped.join('|') + ')\\b(?!`|\\])',
- 'g',
- );
-
- return markdown.replace(pattern, match => {
- const href = nameToHref.get(match);
- if (!href) {
- return match;
- }
- return '[' + match + '](' + href + ')';
- });
-}
+import {
+ linkifyPRs,
+ linkifyContributors,
+ linkifyComponents,
+ stripTitle,
+} from './changelogLinkify';
interface ChangelogEntry {
pkg: string;
@@ -107,7 +77,7 @@ export function ChangelogView({
{active != null && (
<Markdown headingLevelStart={2}>
{linkifyComponents(
- linkifyPRs(stripTitle(active.content)),
+ linkifyContributors(linkifyPRs(stripTitle(active.content))),
componentNames,
)}
</Markdown>
diff --git a/apps/docsite/src/components/changelogLinkify.ts b/apps/docsite/src/components/changelogLinkify.ts
new file mode 100644
index 0000000000..0f8ac3a284
--- /dev/null
+++ b/apps/docsite/src/components/changelogLinkify.ts
@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Pure markdown post-processors for the changelog view. Each turns a raw
+ * pattern in the rendered CHANGELOG text into a markdown link before it is
+ * handed to <Markdown>. Kept side-effect-free and colocated so they can be
+ * unit tested without rendering the component.
+ */
+
+import {GITHUB_REPO} from '../constants';
+
+// GitHub profile base, derived from the repo URL (e.g. https://github.com).
+const GITHUB_HOST = new URL(GITHUB_REPO).origin;
+
+/** Turn `#1234` PR references into links to the GitHub PR. */
+export function linkifyPRs(markdown: string): string {
+ return markdown.replace(/(?<!\[)#(\d+)/g, `[#$1](${GITHUB_REPO}/pull/$1)`);
+}
+
+/**
+ * Link the `#### Contributors` bullets to GitHub profiles. The changelog
+ * formatter (scripts/format-changelogs.mjs) emits each contributor as a
+ * standalone `- @handle` bullet, so we match a list item whose entire content
+ * is a single handle. This deliberately avoids package-name bullets like
+ * `- @astryxdesign/core` (they contain a `/` and are backticked) and inline
+ * `@` mentions in prose. The handle pattern follows GitHub's username rules
+ * (alphanumeric or hyphens, no leading/trailing hyphen, max 39 chars).
+ */
+export function linkifyContributors(markdown: string): string {
+ return markdown.replace(
+ /^(\s*-\s+)@([A-Za-z\d](?:[A-Za-z\d-]{0,37}[A-Za-z\d])?)[ \t]*$/gm,
+ `$1[@$2](${GITHUB_HOST}/$2)`,
+ );
+}
+
+/** Link bare component names (e.g. `Button`, `XDSButton`) to their doc page. */
+export function linkifyComponents(markdown: string, names: string[]): string {
+ if (names.length === 0) {
+ return markdown;
+ }
+
+ const nameToHref = new Map<string, string>();
+ for (const name of names) {
+ nameToHref.set(name, `/components/${name}`);
+ nameToHref.set('XDS' + name, `/components/${name}`);
+ }
+
+ const sorted = [...nameToHref.keys()].sort((a, b) => b.length - a.length);
+ const escaped = sorted.map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+ const pattern = new RegExp(
+ '(?<!`|\\[)\\b(' + escaped.join('|') + ')\\b(?!`|\\])',
+ 'g',
+ );
+
+ return markdown.replace(pattern, match => {
+ const href = nameToHref.get(match);
+ if (!href) {
+ return match;
+ }
+ return '[' + match + '](' + href + ')';
+ });
+}
+
+/** Strip the leading `# Title` line (the package name h1) from a changelog. */
+export function stripTitle(markdown: string): string {
+ return markdown.replace(/^#\s+.+\n+/, '');
+}