(superset) 07/09: docs(js-to-ts): enhance AGENT.md with PropTypes auto-generation and ESLint best practices

[ma...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

maximebeauchemin pushed a commit to branch js-to-ts
in repository https://gitbox.apache.org/repos/asf/superset.git

commit 1f1b0389cedc1415983f07f0671f0d8b64abb646
Author: Maxime Beauchemin <ma...@gmail.com>
AuthorDate: Sun Sep 7 15:54:03 2025 -0700

    docs(js-to-ts): enhance AGENT.md with PropTypes auto-generation and ESLint best practices
---
 .claude/projects/js-to-ts/AGENT.md | 102 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 100 insertions(+), 2 deletions(-)

diff --git a/.claude/projects/js-to-ts/AGENT.md b/.claude/projects/js-to-ts/AGENT.md
index eeea09f723..6f0a0c4de8 100644
--- a/.claude/projects/js-to-ts/AGENT.md
+++ b/.claude/projects/js-to-ts/AGENT.md
@@ -284,6 +284,103 @@ type UserDisplayInfo = Pick<User, 'firstName' | 'lastName' | 'email'>;
 
 ---
 
+## 🎯 PropTypes Auto-Generation (Elegant Approach)
+
+**IMPORTANT**: Superset has `babel-plugin-typescript-to-proptypes` configured to automatically generate PropTypes from TypeScript interfaces. Use this instead of manual PropTypes duplication!
+
+### ❌ Manual PropTypes Duplication (Avoid This)
+```typescript
+export interface MyComponentProps {
+  title: string;
+  count?: number;
+}
+
+// 8+ lines of manual PropTypes duplication 😱
+const propTypes = PropTypes.shape({
+  title: PropTypes.string.isRequired,
+  count: PropTypes.number,
+});
+
+export default propTypes;
+```
+
+### ✅ Auto-Generated PropTypes (Use This)
+```typescript
+import { InferProps } from 'prop-types';
+
+export interface MyComponentProps {
+  title: string;
+  count?: number;
+}
+
+// Single validator function - babel plugin auto-generates PropTypes! ✨
+export default function MyComponentValidator(props: MyComponentProps) {
+  return null; // PropTypes auto-assigned by babel-plugin-typescript-to-proptypes
+}
+
+// Optional: For consumers needing PropTypes type inference
+export type MyComponentPropsInferred = InferProps<typeof MyComponentValidator>;
+```
+
+### Migration Pattern for Type-Only Files
+
+**When migrating type-only files with manual PropTypes:**
+
+1. **Keep the TypeScript interfaces** (single source of truth)
+2. **Replace manual PropTypes** with validator function
+3. **Remove PropTypes imports** and manual shape definitions
+4. **Add InferProps import** if type inference needed
+
+**Example Migration:**
+```typescript
+// Before: 25+ lines with manual PropTypes duplication
+export interface AdhocFilterType { /* ... */ }
+const adhocFilterTypePropTypes = PropTypes.oneOfType([...]);
+
+// After: 3 lines with auto-generation
+export interface AdhocFilterType { /* ... */ }
+export default function AdhocFilterValidator(props: { filter: AdhocFilterType }) {
+  return null; // Auto-generated PropTypes by babel plugin
+}
+```
+
+### Component PropTypes Pattern
+
+**For React components, the babel plugin works automatically:**
+
+```typescript
+interface ComponentProps {
+  title: string;
+  onClick: () => void;
+}
+
+const MyComponent: FC<ComponentProps> = ({ title, onClick }) => {
+  // Component implementation
+};
+
+// PropTypes automatically generated by babel plugin - no manual work needed!
+export default MyComponent;
+```
+
+### Auto-Generation Benefits
+
+- ✅ **Single source of truth**: TypeScript interfaces drive PropTypes
+- ✅ **No duplication**: Eliminate 15-20 lines of manual PropTypes code
+- ✅ **Automatic updates**: Changes to TypeScript automatically update PropTypes
+- ✅ **Type safety**: Compile-time checking ensures PropTypes match interfaces
+- ✅ **Backward compatibility**: Existing JavaScript components continue working
+
+### Babel Plugin Configuration
+
+The plugin is already configured in `babel.config.js`:
+```javascript
+['babel-plugin-typescript-to-proptypes', { loose: true }]
+```
+
+**No additional setup required** - just use TypeScript interfaces and the plugin handles the rest!
+
+---
+
 ## 🧪 Test File Migration Patterns
 
 ### Test File Priority
@@ -382,7 +479,7 @@ grep -A 10 -B 10 "TypeName" src/*/types.ts
 4. **TypeScript validation** - Use proper TypeScript compilation commands:
    - **Per-file validation**: `cd superset-frontend && npx tscw --noEmit --allowJs --composite false --project tsconfig.json {relative-path-to-file}`
    - **Project-wide scan**: `npm run type` (only consider errors related to your files - other agents may be working in parallel)
-5. **ESLint validation** - Run `npm run eslint -- {file}` for each migrated file to ensure formatting/linting
+5. **ESLint validation** - Run `npm run eslint -- --fix {file}` for each migrated file to auto-fix formatting/linting issues
 6. Zero `any` types - use proper TypeScript types
 7. Search existing types before creating new ones
 8. Follow patterns from this guide
@@ -410,7 +507,7 @@ SUCCESS: Atomic Migration of {core-filename}
 
 ## Quality Validation
 - File-level TypeScript compilation: ✅ PASS (using `npx tscw --noEmit --allowJs --composite false --project tsconfig.json {files}`)
-- ESLint validation: ✅ PASS (using `npm run eslint -- {files}`)
+- ESLint validation: ✅ PASS (using `npm run eslint -- --fix {files}` to auto-fix formatting)
 - Zero any types: ✅ PASS
 - Local imports resolved: ✅ PASS
 - Functionality preserved: ✅ PASS
@@ -422,6 +519,7 @@ SUCCESS: Atomic Migration of {core-filename}
 - Type conflicts encountered: {describe any multiple type definitions}
 - Mock patterns used: {describe test mocking approaches}
 - Import hierarchy decisions: {note authoritative type sources used}
+- PropTypes strategy: {AUTO_GENERATED via babel plugin | MANUAL_DUPLICATION_REMOVED | N/A}
 
 ## Improvement Suggestions for Documentation
 - AGENT.md enhancement: {suggest additions to migration guide}