Research: Enhancing AI Discoverability of Shared Packages in a Monorepo

This document outlines strategies to improve how AI tools can discover, understand, and utilize shared packages (especially UI components) within the Ezra monorepo. The goal is to make it easier for AI assistants to effectively leverage these internal libraries.

Current Context

The Ezra project utilizes a monorepo structure with shared packages, likely located in frontend/packages/. Unlike external registries like Shadcn, the primary need is to enhance discoverability within this existing monorepo structure for AI-driven development.

Strategies for AI Discoverability

Here are several approaches, ranging from simple documentation practices to more structured metadata solutions:

1. Rich Code-Level Documentation (JSDoc/TSDoc)

Concept: Embed detailed information directly within the code using JSDoc (for JavaScript) or TSDoc (for TypeScript). AI models are adept at parsing these comments.
Implementation:
- For every shared component, document its purpose, props (including types, descriptions, and default values), and provide usage examples.
- Document exported functions and modules similarly.
Benefits:
- Information is co-located with the code, making it easy to maintain.
- Standardized format that many development tools and AIs understand.

Example (TSDoc for a React component):

import React from 'react';

interface MyButtonProps {
  /**
   * The content to display inside the button.
   */
  children: React.ReactNode;
  /**
   * The visual variant of the button.
   * @default 'primary'
   */
  variant?: 'primary' | 'secondary' | 'destructive';
  /**
   * Optional click handler.
   */
  onClick?: () => void;
}

/**
 * A versatile button component for various actions.
 * @example
 * <MyButton variant="primary" onClick={() => console.log('Clicked!')}>
 *   Click Me
 * </MyButton>
 */
export const MyButton: React.FC<MyButtonProps> = ({ children, variant = 'primary', onClick }) => {
  // ... component implementation ...
  return <button onClick={onClick} className={`my-button ${variant}`}>{children}</button>;
};

2. Comprehensive READMEs per Package

Concept: Each shared package (e.g., frontend/packages/ui, frontend/packages/utils) should have a detailed README.md.
Implementation:
- Overview: Describe the package's purpose and its role in the monorepo.
- Key Components/Modules: List the most important components or utilities provided.
- Usage Instructions: Provide clear examples of how to import and use the package's contents.
- Props/API Documentation: For UI packages, summarize the main components and their primary props (can link to or supplement JSDoc).
Benefits:
- Provides a human-readable entry point for understanding the package.
- AIs can parse markdown for high-level context.

3. Standardized `package.json` Metadata

Concept: Utilize fields in each shared package's package.json to provide structured metadata.
Implementation:
- description: A clear, concise summary of the package.
- keywords: Relevant keywords that an AI could use for searching (e.g., "button", "form", "data-fetching", "ui-component").
- main / module / types: Correctly point to the package's entry points and type definitions.
- Custom fields: Consider adding custom fields if necessary, e.g., "componentType": "UI" or "ezra:packageCategory": "shared-ui".
Benefits:
- Standardized and machine-readable.
- Leverages existing infrastructure.

4. Component Manifest Files (Optional, More Advanced)

Concept: Create a JSON or YAML file (e.g., component-manifest.json) at the root of each UI package, or a central one for all shared components. This file would explicitly list components and their key characteristics.
Implementation:
- The manifest could include: component name, path to source, a brief description, list of primary props, and usage snippets.
- This could be manually maintained or auto-generated via a script that parses JSDoc/TSDoc.
Benefits:
- Provides a structured, queryable inventory of components.
- Can be tailored with specific information an AI might need.

Example (component-manifest.json):

{
  "components": [
    {
      "name": "MyButton",
      "path": "./src/components/MyButton.tsx",
      "description": "A versatile button component.",
      "props": ["children", "variant", "onClick"],
      "category": "Action"
    },
    {
      "name": "UserProfileCard",
      "path": "./src/components/UserProfileCard.tsx",
      "description": "Displays user profile information.",
      "props": ["userId", "showAvatar"],
      "category": "Display"
    }
  ]
}

5. Storybook or Component Explorer Integration

Concept: If you use Storybook, Chromatic, or a similar tool, ensure its output is accessible and potentially parseable.
Implementation:
- Ensure stories are well-written and cover various use cases and prop combinations.
- If the Storybook instance is deployed, an AI could potentially be pointed to it, or its data could be extracted.
- Some tools allow exporting Storybook data as JSON.
Benefits:
- Provides interactive examples and visual documentation.
- Often already maintained for development and QA purposes.

6. Clear Directory Structure and Naming Conventions

Concept: A logical and consistent file and directory structure, along with clear naming conventions for components and files, helps both humans and AI understand the codebase.
Implementation:
- Group related components (e.g., frontend/packages/ui/src/components/forms/, frontend/packages/ui/src/components/display/).
- Use descriptive names (e.g., UserProfileCard.tsx instead of UPC.tsx).
Benefits:
- Improves overall code navigability and predictability.

7. AI-Specific Directives or "Hints" (Experimental)

Concept: Embed special comments or markers in the code that are specifically for AI consumption, providing hints about component usage or capabilities.

Implementation: This is less standardized but could involve comments like:

// AI_HINT: This component is best used for primary calls to action.
// AI_HINT: For forms, combine this with <FormInput> and <FormLabel>.
export const MyButton = ...

Benefits: Could offer very targeted guidance to AI tools.
Drawbacks: Relies on the AI being programmed to recognize these specific hints; less portable.

Recommendations for Ezra

Prioritize JSDoc/TSDoc: This is foundational. Encourage detailed documentation for all shared components and utilities. This provides the richest, most context-aware information for an AI.
Maintain Package READMEs: Ensure each package in frontend/packages/ (and any other shared locations) has a good README.
Enrich package.json: Systematically add descriptive fields and relevant keywords to the package.json of each shared package.
Consider a Lightweight Manifest: If JSDoc parsing proves insufficient or too slow for AI tools, a simple, auto-generated component-manifest.json per UI package could be a good next step. It would list component names, paths, and a brief description.
Consistent Structure: Continue enforcing clear naming and directory structures.

By implementing these strategies, you can significantly improve the ability of AI assistants to understand, navigate, and effectively utilize your monorepo's shared packages, leading to more efficient and accurate AI-assisted development.

1forh/registry-research.md