feat(cli): add metadata command for API surface extraction

Add new `fluentui-cli metadata` command that parses .d.ts build output
to extract the complete API surface of a Fluent UI package.

Features:
- Parses .d.ts files using ts-morph to extract all exported symbols
- Classifies exports into Components, Hooks, Types, and Others
- Extracts JSDoc descriptions, tags, type signatures, and member details
- Supports JSON (default), Markdown, and HTML output formats
- Cross-package $ref resolution via metadata.json (JSON Schema style)
- Entry resolution from package.json "types" field or --entry override

CLI options:
  --entry, -e    Path to index.d.ts (default: from package.json)
  --reporter, -r Output format: json | markdown | html
  --output, -o   Output file path (default: stdout)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Hotell

tools/cli/src/cli.ts

@@ -2,13 +2,15 @@ import yargs from 'yargs';
 
 import migrateCommand from './commands/migrate';
 import reportCommand from './commands/report';
+import metadataCommand from './commands/metadata';
 
 export async function main(argv: string[]): Promise<void> {
   await yargs(argv)
     .scriptName('fluentui-cli')
     .usage('$0 <command> [options]')
     .command(migrateCommand)
     .command(reportCommand)
+    .command(metadataCommand)
     .demandCommand(1, 'You need to specify a command to run.')
     .help()
     .strict()

tools/cli/src/commands/metadata/__fixtures__/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@fluentui/sample-button",
+  "version": "1.0.0",
+  "types": "./sample-button.d.ts"
+}

tools/cli/src/commands/metadata/__fixtures__/sample-button.d.ts

@@ -0,0 +1,90 @@
+import * as React from 'react';
+
+/**
+ * Props for the SampleButton component.
+ */
+export declare interface SampleButtonProps {
+  /**
+   * The visual style of the button.
+   *
+   * @default 'secondary'
+   */
+  appearance?: 'primary' | 'secondary' | 'outline';
+  /**
+   * Whether the button is disabled.
+   *
+   * @default false
+   */
+  disabled?: boolean;
+  /** The size of the button. */
+  size?: 'small' | 'medium' | 'large';
+}
+
+/**
+ * State for the SampleButton component.
+ */
+export declare interface SampleButtonState {
+  appearance: 'primary' | 'secondary' | 'outline';
+  disabled: boolean;
+}
+
+/**
+ * Slots for the SampleButton component.
+ */
+export declare type SampleButtonSlots = {
+  /** Root element of the button. */
+  root: HTMLButtonElement;
+  /** Optional icon slot. */
+  icon?: HTMLSpanElement;
+};
+
+/**
+ * SampleButton gives people a way to trigger an action.
+ */
+export declare const SampleButton: React.ForwardRefExoticComponent<
+  SampleButtonProps & React.RefAttributes<HTMLButtonElement>
+>;
+
+export declare const sampleButtonClassNames: Record<string, string>;
+
+/**
+ * Hook to create SampleButton state.
+ * @param props - User provided props to the SampleButton component.
+ * @param ref - User provided ref.
+ */
+export declare const useSampleButton_unstable: (
+  props: SampleButtonProps,
+  ref: React.Ref<HTMLButtonElement>,
+) => SampleButtonState;
+
+export declare const useSampleButtonStyles_unstable: (state: SampleButtonState) => SampleButtonState;
+
+/**
+ * Renders SampleButton from state.
+ */
+export declare const renderSampleButton_unstable: (state: SampleButtonState) => JSX.Element;
+
+/**
+ * @internal
+ * Internal context value.
+ */
+export declare interface SampleButtonContextValue {
+  size?: 'small' | 'medium' | 'large';
+}
+
+/**
+ * Size options for the button.
+ */
+export declare type SampleButtonSize = 'small' | 'medium' | 'large';
+
+/**
+ * @deprecated Use SampleButtonSize instead.
+ */
+export declare enum ButtonVariant {
+  Primary = 'primary',
+  Secondary = 'secondary',
+}
+
+export declare function useToggleState(props: SampleButtonProps): SampleButtonState;
+
+export {};

tools/cli/src/commands/metadata/handler.spec.ts

@@ -0,0 +1,65 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+
+import { handler } from './handler';
+
+const FIXTURES_DIR = path.resolve(__dirname, '__fixtures__');
+const SAMPLE_DTS = path.join(FIXTURES_DIR, 'sample-button.d.ts');
+
+describe('metadata handler', () => {
+  let logSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation();
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+  });
+
+  it('should output JSON metadata for a .d.ts entry file', async () => {
+    await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'json' });
+
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    const output = JSON.parse(logSpy.mock.calls[0][0]);
+
+    expect(output.package.name).toBe('@fluentui/sample-button');
+    expect(output.categories.components).toHaveProperty('SampleButton');
+    expect(output.categories.hooks).toHaveProperty('useSampleButton_unstable');
+    expect(output.categories.types).toHaveProperty('SampleButtonProps');
+    expect(output.categories.others).toHaveProperty('sampleButtonClassNames');
+  });
+
+  it('should output markdown when reporter=markdown', async () => {
+    await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'markdown' });
+
+    const output: string = logSpy.mock.calls[0][0];
+    expect(output).toContain('# API Metadata:');
+    expect(output).toContain('## Components');
+    expect(output).toContain('SampleButton');
+  });
+
+  it('should output HTML when reporter=html', async () => {
+    await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'html' });
+
+    const output: string = logSpy.mock.calls[0][0];
+    expect(output).toContain('<!DOCTYPE html>');
+    expect(output).toContain('SampleButton');
+  });
+
+  it('should write to file when --output is specified', async () => {
+    const tmpOutput = path.join(FIXTURES_DIR, '__test-output__.json');
+
+    try {
+      await handler({ _: ['metadata'], $0: 'fluentui-cli', entry: SAMPLE_DTS, reporter: 'json', output: tmpOutput });
+
+      expect(fs.existsSync(tmpOutput)).toBe(true);
+      const content = JSON.parse(fs.readFileSync(tmpOutput, 'utf-8'));
+      expect(content.package.name).toBe('@fluentui/sample-button');
+    } finally {
+      if (fs.existsSync(tmpOutput)) {
+        fs.unlinkSync(tmpOutput);
+      }
+    }
+  });
+});

tools/cli/src/commands/metadata/handler.ts

@@ -0,0 +1,96 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { CommandHandler } from '../../utils/types';
+import type { MetadataArgs, MetadataOutput } from './impl/types';
+import { resolveEntry, readPackageInfo } from './impl/entry-resolver';
+import { parseDtsEntry } from './impl/dts-parser';
+import { loadDependencyMetadata, buildCrossPackageRef } from './impl/cross-package-resolver';
+import { formatMetadataAsMarkdown } from './impl/markdown-formatter';
+import { formatMetadataAsHtml } from './impl/html-formatter';
+
+const LEGEND = {
+  components: { name: 'Components', description: 'React components (ForwardRef, FC, class)' },
+  hooks: { name: 'Hooks', description: 'React hooks (use* convention)' },
+  types: { name: 'Types', description: 'Interfaces, type aliases, and enums' },
+  others: { name: 'Others', description: 'Constants, render functions, and utilities' },
+};
+
+export const handler: CommandHandler<MetadataArgs> = async argv => {
+  const { entry, reporter = 'json', output } = argv;
+
+  // 1. Resolve entry .d.ts
+  const entryPath = resolveEntry(entry);
+  const packageInfo = readPackageInfo(path.dirname(entryPath));
+
+  // 2. Parse the .d.ts
+  const parseResult = parseDtsEntry(entryPath);
+
+  // 3. Resolve cross-package $refs
+  const cwd = process.cwd();
+  const depMetadataCache = new Map<string, MetadataOutput | null>();
+
+  for (const pkgSpec of parseResult.importedPackages) {
+    if (!depMetadataCache.has(pkgSpec)) {
+      depMetadataCache.set(pkgSpec, loadDependencyMetadata(pkgSpec, cwd));
+    }
+  }
+
+  // Enhance component propsType refs with cross-package resolution
+  for (const comp of Object.values(parseResult.components)) {
+    if (comp.propsType && '$ref' in comp.propsType) {
+      const localRef = comp.propsType.$ref;
+      const symbolName = localRef.split('/').pop()!;
+
+      // If the type isn't in our own types, check dependencies
+      if (!(symbolName in parseResult.types)) {
+        for (const [pkgSpec, depMetadata] of depMetadataCache) {
+          if (depMetadata) {
+            const crossRef = buildCrossPackageRef(pkgSpec, symbolName, depMetadata);
+            if (crossRef) {
+              comp.propsType = crossRef;
+              break;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // 4. Assemble output
+  const metadataOutput: MetadataOutput = {
+    package: packageInfo,
+    legend: LEGEND,
+    categories: {
+      components: parseResult.components,
+      hooks: parseResult.hooks,
+      types: parseResult.types,
+      others: parseResult.others,
+    },
+  };
+
+  // 5. Format
+  let formatted: string;
+  switch (reporter) {
+    case 'markdown':
+      formatted = formatMetadataAsMarkdown(metadataOutput);
+      break;
+    case 'html':
+      formatted = formatMetadataAsHtml(metadataOutput);
+      break;
+    case 'json':
+    default:
+      formatted = JSON.stringify(metadataOutput, null, 2);
+      break;
+  }
+
+  // 6. Output
+  if (output) {
+    const outputPath = path.resolve(cwd, output);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, formatted, 'utf-8');
+    console.log(`Metadata written to ${outputPath}`);
+  } else {
+    console.log(formatted);
+  }
+};

tools/cli/src/commands/metadata/impl/cross-package-resolver.spec.ts

@@ -0,0 +1,60 @@
+import type { MetadataOutput } from './types';
+import { loadDependencyMetadata, buildCrossPackageRef } from './cross-package-resolver';
+
+describe('cross-package-resolver', () => {
+  const mockMetadata: MetadataOutput = {
+    package: { name: '@fluentui/react-utilities', version: '1.0.0' },
+    legend: {},
+    categories: {
+      components: {},
+      hooks: {},
+      types: {
+        ComponentProps: {
+          name: 'ComponentProps',
+          description: 'Base component props type.',
+          typeSignature: '...',
+          tags: {},
+          kind: 'type-alias',
+          members: {},
+        },
+      },
+      others: {
+        slot: {
+          name: 'slot',
+          description: 'Slot utility.',
+          typeSignature: '...',
+          tags: {},
+          kind: 'function',
+        },
+      },
+    },
+  };
+
+  describe('buildCrossPackageRef', () => {
+    it('should return a $ref when the symbol exists in types', () => {
+      const result = buildCrossPackageRef('@fluentui/react-utilities', 'ComponentProps', mockMetadata);
+
+      expect(result).toEqual({ $ref: '@fluentui/react-utilities#/categories/types/ComponentProps' });
+    });
+
+    it('should return a $ref when the symbol exists in others', () => {
+      const result = buildCrossPackageRef('@fluentui/react-utilities', 'slot', mockMetadata);
+
+      expect(result).toEqual({ $ref: '@fluentui/react-utilities#/categories/others/slot' });
+    });
+
+    it('should return null when the symbol does not exist', () => {
+      const result = buildCrossPackageRef('@fluentui/react-utilities', 'NonExistent', mockMetadata);
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('loadDependencyMetadata', () => {
+    it('should return null for a non-existent package', () => {
+      const result = loadDependencyMetadata('__non_existent_package__', '/');
+
+      expect(result).toBeNull();
+    });
+  });
+});