@idealyst/tooling

@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

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:

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:

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:

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:

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