@idealyst/tooling 1.2.3

package/README.md

@@ -0,0 +1,185 @@
+# @idealyst/tooling
+
+Code analysis and validation utilities for Idealyst Framework. Provides shared tools for babel plugins, CLI, and MCP to validate cross-platform React/React Native code.
+
+## Installation
+
+```bash
+yarn add @idealyst/tooling
+# or
+npm install @idealyst/tooling
+```
+
+## Features
+
+- **Platform Import Analyzer**: Validates that component files don't use platform-specific primitives unless appropriately suffixed
+- **File Classifier**: Classifies files by their extension (.web.tsx, .native.tsx, etc.)
+- **Import Parser**: Parses TypeScript/JavaScript imports using the TypeScript compiler API
+- **Primitive Rules**: Built-in lists of React Native and React DOM primitives
+
+## Usage
+
+### Platform Import Analysis
+
+The main feature is validating that shared component files don't accidentally use platform-specific imports:
+
+```typescript
+import { analyzePlatformImports, analyzeFiles } from '@idealyst/tooling';
+
+// Single file analysis
+const result = analyzePlatformImports(
+  'src/components/Button.tsx',
+  sourceCode,
+  { severity: 'error' }
+);
+
+if (!result.passed) {
+  for (const violation of result.violations) {
+    console.error(`${violation.filePath}:${violation.line}:${violation.column}`);
+    console.error(`  ${violation.message}`);
+  }
+}
+
+// Batch analysis
+const results = analyzeFiles(
+  [
+    { path: 'Button.tsx', content: buttonSource },
+    { path: 'Button.web.tsx', content: webSource },
+    { path: 'Button.native.tsx', content: nativeSource },
+  ],
+  {
+    severity: 'warning',
+    ignoredPatterns: ['**/*.test.tsx'],
+  }
+);
+
+const failedFiles = results.filter(r => !r.passed);
+```
+
+### File Classification
+
+Classify files based on their extension patterns:
+
+```typescript
+import { classifyFile, isSharedFile } from '@idealyst/tooling';
+
+classifyFile('Button.tsx');        // 'shared'
+classifyFile('Button.web.tsx');    // 'web'
+classifyFile('Button.native.tsx'); // 'native'
+classifyFile('Button.styles.tsx'); // 'styles'
+classifyFile('types.ts');          // 'types'
+
+// Check if a file should be validated for cross-platform imports
+if (isSharedFile(filePath)) {
+  // This file should NOT have platform-specific imports
+}
+```
+
+### Import Parsing
+
+Parse imports from source code:
+
+```typescript
+import { parseImports } from '@idealyst/tooling';
+
+const imports = parseImports(sourceCode, 'Button.tsx');
+
+for (const imp of imports) {
+  console.log(`${imp.name} from '${imp.source}' (${imp.platform})`);
+}
+```
+
+### Primitive Rules
+
+Access built-in primitive lists:
+
+```typescript
+import {
+  REACT_NATIVE_PRIMITIVES,
+  REACT_DOM_PRIMITIVES,
+  isReactNativePrimitive,
+  isReactDomPrimitive,
+} from '@idealyst/tooling';
+
+// Check if a name is a known primitive
+isReactNativePrimitive('View');      // true
+isReactNativePrimitive('div');       // false
+isReactDomPrimitive('createPortal'); // true
+```
+
+## API Reference
+
+### `analyzePlatformImports(filePath, sourceCode, options?)`
+
+Analyze a single file for platform import violations.
+
+**Options:**
+- `severity`: Default severity level (`'error'` | `'warning'` | `'info'`)
+- `additionalNativePrimitives`: Extra primitives to flag as React Native
+- `additionalDomPrimitives`: Extra primitives to flag as React DOM
+- `ignoredPrimitives`: Primitives to skip validation for
+- `ignoredPatterns`: Glob patterns for files to skip
+- `additionalNativeSources`: Extra module sources treated as React Native
+- `additionalDomSources`: Extra module sources treated as React DOM
+
+**Returns:** `AnalysisResult` with violations and metadata.
+
+### `analyzeFiles(files, options?)`
+
+Analyze multiple files at once.
+
+### `classifyFile(filePath)`
+
+Classify a file by its extension pattern.
+
+**Returns:** `'shared'` | `'web'` | `'native'` | `'styles'` | `'types'` | `'other'`
+
+### `parseImports(sourceCode, filePath?, options?)`
+
+Parse all imports from source code.
+
+**Returns:** Array of `ImportInfo` objects.
+
+## Validation Rules
+
+### Shared Files (`.tsx`, `.jsx`)
+
+Should NOT import:
+- React Native primitives (`View`, `Text`, `TouchableOpacity`, etc.)
+- React DOM APIs (`createPortal`, `flushSync`, etc.)
+
+### Web Files (`.web.tsx`, `.web.jsx`)
+
+Should NOT import:
+- React Native primitives
+
+### Native Files (`.native.tsx`, `.native.jsx`)
+
+Should NOT import:
+- React DOM APIs
+
+## Built-in Primitives
+
+### React Native
+
+Core: `View`, `Text`, `Image`, `ScrollView`, `FlatList`, `SectionList`
+
+Interactive: `TouchableOpacity`, `TouchableHighlight`, `Pressable`, `Button`
+
+Input: `TextInput`, `Switch`
+
+Modal: `Modal`, `Alert`, `StatusBar`
+
+Animation: `Animated`, `Easing`, `LayoutAnimation`
+
+Platform: `Platform`, `Dimensions`, `BackHandler`, `Keyboard`
+
+Safety: `SafeAreaView`, `KeyboardAvoidingView`
+
+### React DOM
+
+APIs: `createPortal`, `flushSync`, `createRoot`, `hydrateRoot`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@idealyst/tooling",
+  "version": "1.2.3",
+  "description": "Code analysis and validation utilities for Idealyst Framework",
+  "readme": "README.md",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IdealystIO/idealyst-framework.git",
+    "directory": "packages/tooling"
+  },
+  "author": "Your Name <your.email@example.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "require": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./vite": {
+      "import": "./src/vite-plugin.ts",
+      "require": "./src/vite-plugin.ts",
+      "types": "./src/vite-plugin.ts"
+    },
+    "./docs": {
+      "import": "./src/analyzer/index.ts",
+      "require": "./src/analyzer/index.ts",
+      "types": "./src/analyzer/index.ts"
+    },
+    "./analyzers": {
+      "import": "./src/analyzers/index.ts",
+      "require": "./src/analyzers/index.ts",
+      "types": "./src/analyzers/index.ts"
+    },
+    "./rules": {
+      "import": "./src/rules/index.ts",
+      "require": "./src/rules/index.ts",
+      "types": "./src/rules/index.ts"
+    },
+    "./utils": {
+      "import": "./src/utils/index.ts",
+      "require": "./src/utils/index.ts",
+      "types": "./src/utils/index.ts"
+    }
+  },
+  "scripts": {
+    "prepublishOnly": "echo 'Publishing TypeScript source directly'",
+    "publish:npm": "npm publish",
+    "test": "jest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "tsx": "^4.21.0",
+    "vite": "^7.3.1"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "tooling",
+    "code-analysis",
+    "validation",
+    "react",
+    "react-native",
+    "cross-platform",
+    "idealyst"
+  ]
+}

package/src/analyzer/component-analyzer.ts

@@ -0,0 +1,418 @@
+/**
+ * Component Analyzer - Extracts component prop definitions using TypeScript Compiler API.
+ *
+ * Analyzes:
+ * - types.ts files for prop interfaces
+ * - JSDoc comments for descriptions
+ * - Static .description properties on components
+ * - Theme-derived types (Intent, Size) resolved to actual values
+ */
+
+import * as ts from 'typescript';
+import * as fs from 'fs';
+import * as path from 'path';
+import type {
+  ComponentRegistry,
+  ComponentDefinition,
+  PropDefinition,
+  ComponentAnalyzerOptions,
+  ThemeValues,
+  ComponentCategory,
+} from './types';
+import { analyzeTheme } from './theme-analyzer';
+
+/**
+ * Analyze components and generate a registry.
+ */
+export function analyzeComponents(options: ComponentAnalyzerOptions): ComponentRegistry {
+  const { componentPaths, themePath, include, exclude, includeInternal = false } = options;
+
+  const registry: ComponentRegistry = {};
+
+  // First, analyze the theme to get valid values
+  const themeValues = analyzeTheme(themePath, false);
+
+  // Scan each component path
+  for (const componentPath of componentPaths) {
+    const resolvedPath = path.resolve(componentPath);
+
+    if (!fs.existsSync(resolvedPath)) {
+      console.warn(`[component-analyzer] Path not found: ${resolvedPath}`);
+      continue;
+    }
+
+    // Find all component directories (those with index.ts or types.ts)
+    const componentDirs = findComponentDirs(resolvedPath);
+
+    for (const dir of componentDirs) {
+      const componentName = path.basename(dir);
+
+      // Apply include/exclude filters
+      if (include && !include.includes(componentName)) continue;
+      if (exclude && exclude.includes(componentName)) continue;
+      if (!includeInternal && componentName.startsWith('_')) continue;
+
+      const definition = analyzeComponentDir(dir, componentName, themeValues);
+      if (definition) {
+        registry[componentName] = definition;
+      }
+    }
+  }
+
+  return registry;
+}
+
+/**
+ * Find all component directories in a path.
+ */
+function findComponentDirs(basePath: string): string[] {
+  const dirs: string[] = [];
+
+  const entries = fs.readdirSync(basePath, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const dirPath = path.join(basePath, entry.name);
+
+    // Check if it's a component directory (has index.ts or types.ts)
+    const hasIndex = fs.existsSync(path.join(dirPath, 'index.ts'));
+    const hasTypes = fs.existsSync(path.join(dirPath, 'types.ts'));
+
+    if (hasIndex || hasTypes) {
+      dirs.push(dirPath);
+    }
+  }
+
+  return dirs;
+}
+
+/**
+ * Analyze a single component directory.
+ */
+function analyzeComponentDir(
+  dir: string,
+  componentName: string,
+  themeValues: ThemeValues
+): ComponentDefinition | null {
+  // Find all TypeScript files in the component directory
+  const tsFiles = fs.readdirSync(dir)
+    .filter(f => f.endsWith('.ts') || f.endsWith('.tsx'))
+    .map(f => path.join(dir, f));
+
+  if (tsFiles.length === 0) {
+    return null;
+  }
+
+  // Create TypeScript program with all files
+  const program = ts.createProgram(tsFiles, {
+    target: ts.ScriptTarget.ES2020,
+    module: ts.ModuleKind.ESNext,
+    jsx: ts.JsxEmit.React,
+    strict: true,
+    esModuleInterop: true,
+    skipLibCheck: true,
+  });
+
+  const typeChecker = program.getTypeChecker();
+
+  // Search all files for the props interface
+  const propsInterfaceName = `${componentName}Props`;
+  const altNames = [`${componentName}ComponentProps`, 'Props'];
+  let propsInterface: ts.InterfaceDeclaration | ts.TypeAliasDeclaration | null = null;
+  let interfaceDescription: string | undefined;
+  let foundInFile: ts.SourceFile | null = null;
+
+  // Search each file for the props interface
+  for (const filePath of tsFiles) {
+    const sourceFile = program.getSourceFile(filePath);
+    if (!sourceFile) continue;
+
+    // First try the main props interface name
+    ts.forEachChild(sourceFile, (node) => {
+      if (ts.isInterfaceDeclaration(node) && node.name.text === propsInterfaceName) {
+        propsInterface = node;
+        interfaceDescription = getJSDocDescription(node);
+        foundInFile = sourceFile;
+      }
+      if (ts.isTypeAliasDeclaration(node) && node.name.text === propsInterfaceName) {
+        propsInterface = node;
+        interfaceDescription = getJSDocDescription(node);
+        foundInFile = sourceFile;
+      }
+    });
+
+    if (propsInterface) break;
+  }
+
+  // If not found, try alternate naming conventions
+  if (!propsInterface) {
+    for (const altName of altNames) {
+      for (const filePath of tsFiles) {
+        const sourceFile = program.getSourceFile(filePath);
+        if (!sourceFile) continue;
+
+        ts.forEachChild(sourceFile, (node) => {
+          if ((ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) && node.name.text === altName) {
+            propsInterface = node;
+            interfaceDescription = getJSDocDescription(node);
+            foundInFile = sourceFile;
+          }
+        });
+
+        if (propsInterface) break;
+      }
+      if (propsInterface) break;
+    }
+  }
+
+  // If we couldn't find a props interface, skip this component
+  if (!propsInterface) {
+    return null;
+  }
+
+  // Extract props
+  const props: Record<string, PropDefinition> = {};
+
+  if (propsInterface) {
+    const type = typeChecker.getTypeAtLocation(propsInterface);
+    const properties = type.getProperties();
+
+    for (const prop of properties) {
+      const propDef = analyzeProperty(prop, typeChecker, themeValues);
+      if (propDef && !isInternalProp(propDef.name)) {
+        props[propDef.name] = propDef;
+      }
+    }
+  }
+
+  // Get description from the props interface JSDoc (single source of truth in types.ts)
+  const description = interfaceDescription;
+
+  // Determine category
+  const category = inferCategory(componentName);
+
+  return {
+    name: componentName,
+    description,
+    props,
+    category,
+    filePath: path.relative(process.cwd(), dir),
+  };
+}
+
+/**
+ * Analyze a single property symbol.
+ */
+function analyzeProperty(
+  symbol: ts.Symbol,
+  typeChecker: ts.TypeChecker,
+  themeValues: ThemeValues
+): PropDefinition | null {
+  const name = symbol.getName();
+  const declarations = symbol.getDeclarations();
+
+  if (!declarations || declarations.length === 0) return null;
+
+  const declaration = declarations[0];
+  const type = typeChecker.getTypeOfSymbolAtLocation(symbol, declaration);
+  const typeString = typeChecker.typeToString(type);
+
+  // Get JSDoc description
+  const description = ts.displayPartsToString(symbol.getDocumentationComment(typeChecker)) || undefined;
+
+  // Check if required
+  const required = !(symbol.flags & ts.SymbolFlags.Optional);
+
+  // Extract values for union types / theme types
+  const values = extractPropValues(type, typeString, typeChecker, themeValues);
+
+  // Extract default value (from JSDoc @default tag)
+  const defaultValue = extractDefaultValue(symbol);
+
+  return {
+    name,
+    type: simplifyTypeName(typeString),
+    values: values.length > 0 ? values : undefined,
+    default: defaultValue,
+    description,
+    required,
+  };
+}
+
+/**
+ * Extract valid values for a prop type.
+ */
+function extractPropValues(
+  type: ts.Type,
+  typeString: string,
+  typeChecker: ts.TypeChecker,
+  themeValues: ThemeValues
+): string[] {
+  // Handle theme-derived types
+  if (typeString === 'Intent' || typeString.includes('Intent')) {
+    return themeValues.intents;
+  }
+  if (typeString === 'Size' || typeString.includes('Size')) {
+    // Return generic sizes - most components use the same keys
+    return ['xs', 'sm', 'md', 'lg', 'xl'];
+  }
+
+  // Handle union types
+  if (type.isUnion()) {
+    const values: string[] = [];
+    for (const unionType of type.types) {
+      if (unionType.isStringLiteral()) {
+        values.push(unionType.value);
+      } else if ((unionType as any).intrinsicName === 'true') {
+        values.push('true');
+      } else if ((unionType as any).intrinsicName === 'false') {
+        values.push('false');
+      }
+    }
+    if (values.length > 0) return values;
+  }
+
+  // Handle boolean
+  if (typeString === 'boolean') {
+    return ['true', 'false'];
+  }
+
+  return [];
+}
+
+/**
+ * Extract default value from JSDoc @default tag.
+ */
+function extractDefaultValue(symbol: ts.Symbol): string | number | boolean | undefined {
+  const tags = symbol.getJsDocTags();
+  for (const tag of tags) {
+    if (tag.name === 'default' && tag.text) {
+      const value = ts.displayPartsToString(tag.text);
+      // Try to parse as JSON
+      try {
+        return JSON.parse(value);
+      } catch {
+        return value;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Get JSDoc description from a node.
+ */
+function getJSDocDescription(node: ts.Node): string | undefined {
+  const jsDocs = (node as any).jsDoc as ts.JSDoc[] | undefined;
+  if (!jsDocs || jsDocs.length === 0) return undefined;
+
+  const firstDoc = jsDocs[0];
+  if (firstDoc.comment) {
+    if (typeof firstDoc.comment === 'string') {
+      return firstDoc.comment;
+    }
+    // Handle NodeArray of JSDocComment
+    return (firstDoc.comment as ts.NodeArray<ts.JSDocComment>)
+      .map(c => (c as any).text || '')
+      .join('');
+  }
+  return undefined;
+}
+
+/**
+ * Simplify type names for display.
+ */
+function simplifyTypeName(typeString: string): string {
+  // Remove import paths
+  typeString = typeString.replace(/import\([^)]+\)\./g, '');
+
+  // Simplify common complex types
+  if (typeString.includes('ReactNode')) return 'ReactNode';
+  if (typeString.includes('StyleProp')) return 'Style';
+
+  return typeString;
+}
+
+/**
+ * Check if a prop should be excluded (internal/inherited).
+ */
+function isInternalProp(name: string): boolean {
+  const internalProps = [
+    'ref',
+    'key',
+    'children',
+    'style',
+    'testID',
+    'nativeID',
+    'accessible',
+    'accessibilityActions',
+    'accessibilityComponentType',
+    'accessibilityElementsHidden',
+    'accessibilityHint',
+    'accessibilityIgnoresInvertColors',
+    'accessibilityLabel',
+    'accessibilityLabelledBy',
+    'accessibilityLanguage',
+    'accessibilityLiveRegion',
+    'accessibilityRole',
+    'accessibilityState',
+    'accessibilityTraits',
+    'accessibilityValue',
+    'accessibilityViewIsModal',
+    'collapsable',
+    'focusable',
+    'hasTVPreferredFocus',
+    'hitSlop',
+    'importantForAccessibility',
+    'needsOffscreenAlphaCompositing',
+    'onAccessibilityAction',
+    'onAccessibilityEscape',
+    'onAccessibilityTap',
+    'onLayout',
+    'onMagicTap',
+    'onMoveShouldSetResponder',
+    'onMoveShouldSetResponderCapture',
+    'onResponderEnd',
+    'onResponderGrant',
+    'onResponderMove',
+    'onResponderReject',
+    'onResponderRelease',
+    'onResponderStart',
+    'onResponderTerminate',
+    'onResponderTerminationRequest',
+    'onStartShouldSetResponder',
+    'onStartShouldSetResponderCapture',
+    'pointerEvents',
+    'removeClippedSubviews',
+    'renderToHardwareTextureAndroid',
+    'shouldRasterizeIOS',
+    'tvParallaxMagnification',
+    'tvParallaxProperties',
+    'tvParallaxShiftDistanceX',
+    'tvParallaxShiftDistanceY',
+    'tvParallaxTiltAngle',
+  ];
+
+  return internalProps.includes(name) || name.startsWith('accessibility');
+}
+
+/**
+ * Infer component category from name.
+ */
+function inferCategory(componentName: string): ComponentCategory {
+  const formComponents = ['Button', 'Input', 'Checkbox', 'Select', 'Switch', 'RadioButton', 'Slider', 'TextArea'];
+  const displayComponents = ['Text', 'Card', 'Badge', 'Chip', 'Avatar', 'Icon', 'Skeleton', 'Alert', 'Tooltip'];
+  const layoutComponents = ['View', 'Screen', 'Divider'];
+  const navigationComponents = ['TabBar', 'Breadcrumb', 'Menu', 'List', 'Link'];
+  const overlayComponents = ['Dialog', 'Popover', 'Modal'];
+  const dataComponents = ['Table', 'Progress', 'Accordion'];
+
+  if (formComponents.includes(componentName)) return 'form';
+  if (displayComponents.includes(componentName)) return 'display';
+  if (layoutComponents.includes(componentName)) return 'layout';
+  if (navigationComponents.includes(componentName)) return 'navigation';
+  if (overlayComponents.includes(componentName)) return 'overlay';
+  if (dataComponents.includes(componentName)) return 'data';
+
+  return 'display'; // Default
+}

package/src/analyzer/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Component and Theme Analyzers
+ *
+ * Tools for extracting component metadata from TypeScript source code.
+ * Used by both the Vite plugin (for docs generation) and MCP server (for IDE assistance).
+ * Also used by the Babel plugin for $iterator expansion.
+ */
+
+export { analyzeComponents } from './component-analyzer';
+export {
+  analyzeTheme,
+  loadThemeKeys,
+  resetThemeCache,
+  type BabelThemeKeys,
+} from './theme-analyzer';
+export * from './types';