@idealyst/tooling 1.2.3

package/src/types.ts

@@ -0,0 +1,173 @@
+/**
+ * File type classification based on file extension patterns
+ */
+export type FileType =
+  | 'shared'   // .tsx, .jsx - shared cross-platform files
+  | 'web'      // .web.tsx, .web.jsx - web-specific files
+  | 'native'   // .native.tsx, .native.jsx - React Native-specific files
+  | 'styles'   // .styles.tsx, .styles.ts - style definition files
+  | 'types'    // .types.ts, types.ts - type definition files
+  | 'other';   // non-component files
+
+/**
+ * Platform classification for imports
+ */
+export type Platform = 'react-native' | 'react-dom' | 'neutral';
+
+/**
+ * Violation type describing what kind of platform mismatch occurred
+ */
+export type ViolationType =
+  | 'native-in-shared'  // React Native primitive used in shared file
+  | 'dom-in-shared'     // React DOM primitive used in shared file
+  | 'native-in-web'     // React Native primitive used in web file
+  | 'dom-in-native';    // React DOM primitive used in native file
+
+/**
+ * Severity level for violations
+ */
+export type Severity = 'error' | 'warning' | 'info';
+
+/**
+ * Information about a single import
+ */
+export interface ImportInfo {
+  /** The imported identifier name */
+  name: string;
+  /** Original name if aliased (e.g., `Image as RNImage`) */
+  originalName?: string;
+  /** The module source (e.g., 'react-native', 'react-dom') */
+  source: string;
+  /** The platform this import belongs to */
+  platform: Platform;
+  /** Line number in source file */
+  line: number;
+  /** Column number in source file */
+  column: number;
+  /** Whether this is a default import */
+  isDefault: boolean;
+  /** Whether this is a namespace import (import * as X) */
+  isNamespace: boolean;
+  /** Whether this is a type-only import */
+  isTypeOnly: boolean;
+}
+
+/**
+ * A single violation found during analysis
+ */
+export interface Violation {
+  /** Type of violation */
+  type: ViolationType;
+  /** The primitive/component that caused the violation */
+  primitive: string;
+  /** The module source (e.g., 'react-native', 'react-dom') */
+  source: string;
+  /** Path to the file with the violation */
+  filePath: string;
+  /** Line number where violation occurred */
+  line: number;
+  /** Column number where violation occurred */
+  column: number;
+  /** Human-readable message describing the violation */
+  message: string;
+  /** Severity level of this violation */
+  severity: Severity;
+}
+
+/**
+ * Result of analyzing a single file
+ */
+export interface AnalysisResult {
+  /** Path to the analyzed file */
+  filePath: string;
+  /** Classified type of the file */
+  fileType: FileType;
+  /** List of violations found */
+  violations: Violation[];
+  /** All imports found in the file */
+  imports: ImportInfo[];
+  /** Whether the file passed validation (no violations) */
+  passed: boolean;
+}
+
+/**
+ * Options for configuring the platform import analyzer
+ */
+export interface AnalyzerOptions {
+  /**
+   * Default severity level for violations
+   * @default 'error'
+   */
+  severity?: Severity;
+
+  /**
+   * Additional React Native primitives to flag beyond the built-in list
+   * Useful for flagging custom native-only components
+   */
+  additionalNativePrimitives?: string[];
+
+  /**
+   * Additional React DOM primitives to flag beyond the built-in list
+   * Useful for flagging custom web-only components
+   */
+  additionalDomPrimitives?: string[];
+
+  /**
+   * Primitives to ignore/allow even if they would normally be flagged
+   */
+  ignoredPrimitives?: string[];
+
+  /**
+   * Glob patterns for files to skip analysis on
+   * @example ['**\/*.test.tsx', '**\/*.stories.tsx']
+   */
+  ignoredPatterns?: string[];
+
+  /**
+   * Additional module sources to treat as React Native
+   * @example ['react-native-gesture-handler', 'react-native-reanimated']
+   */
+  additionalNativeSources?: string[];
+
+  /**
+   * Additional module sources to treat as React DOM
+   * @example ['react-dom/client']
+   */
+  additionalDomSources?: string[];
+}
+
+/**
+ * Input for batch file analysis
+ */
+export interface FileInput {
+  /** File path */
+  path: string;
+  /** File content (source code) */
+  content: string;
+}
+
+/**
+ * Primitive rule definition
+ */
+export interface PrimitiveRule {
+  /** Name of the primitive/component */
+  name: string;
+  /** Module source it comes from */
+  source: string;
+  /** Platform it belongs to */
+  platform: Platform;
+  /** Optional description of why it's platform-specific */
+  description?: string;
+}
+
+/**
+ * Rule set containing primitives for a specific platform
+ */
+export interface PrimitiveRuleSet {
+  /** Platform these rules apply to */
+  platform: Platform;
+  /** List of primitive rules */
+  primitives: PrimitiveRule[];
+  /** Module sources that indicate this platform */
+  sources: string[];
+}

package/src/utils/fileClassifier.ts

@@ -0,0 +1,135 @@
+import { FileType } from '../types';
+import * as path from 'path';
+
+/**
+ * Extension patterns for classification
+ * Order matters - more specific patterns should come first
+ */
+const EXTENSION_PATTERNS: Array<{ pattern: RegExp; type: FileType }> = [
+  // Platform-specific component files
+  { pattern: /\.web\.(tsx|jsx)$/, type: 'web' },
+  { pattern: /\.native\.(tsx|jsx)$/, type: 'native' },
+  { pattern: /\.ios\.(tsx|jsx)$/, type: 'native' },
+  { pattern: /\.android\.(tsx|jsx)$/, type: 'native' },
+
+  // Style files (can be .ts or .tsx)
+  { pattern: /\.styles?\.(tsx?|jsx?)$/, type: 'styles' },
+
+  // Type definition files
+  { pattern: /\.types?\.(ts|tsx)$/, type: 'types' },
+  { pattern: /types\.(ts|tsx)$/, type: 'types' },
+  { pattern: /\.d\.ts$/, type: 'types' },
+
+  // Shared component files (generic .tsx/.jsx without platform suffix)
+  { pattern: /\.(tsx|jsx)$/, type: 'shared' },
+];
+
+/**
+ * Files that should be classified as 'other' regardless of extension
+ */
+const EXCLUDED_PATTERNS: RegExp[] = [
+  /\.test\.(tsx?|jsx?)$/,
+  /\.spec\.(tsx?|jsx?)$/,
+  /\.stories\.(tsx?|jsx?)$/,
+  /\.config\.(ts|js)$/,
+  /index\.(ts|tsx|js|jsx)$/,
+];
+
+/**
+ * Classifies a file based on its path and extension
+ *
+ * @param filePath - The file path to classify
+ * @returns The file type classification
+ *
+ * @example
+ * classifyFile('Button.tsx') // 'shared'
+ * classifyFile('Button.web.tsx') // 'web'
+ * classifyFile('Button.native.tsx') // 'native'
+ * classifyFile('Button.styles.tsx') // 'styles'
+ * classifyFile('types.ts') // 'types'
+ */
+export function classifyFile(filePath: string): FileType {
+  const fileName = path.basename(filePath);
+
+  // Check if this file should be excluded from component analysis
+  for (const pattern of EXCLUDED_PATTERNS) {
+    if (pattern.test(fileName)) {
+      return 'other';
+    }
+  }
+
+  // Match against extension patterns
+  for (const { pattern, type } of EXTENSION_PATTERNS) {
+    if (pattern.test(fileName)) {
+      return type;
+    }
+  }
+
+  return 'other';
+}
+
+/**
+ * Checks if a file is a component file that should be analyzed
+ *
+ * @param filePath - The file path to check
+ * @returns True if the file is a component file (.tsx or .jsx)
+ */
+export function isComponentFile(filePath: string): boolean {
+  const fileType = classifyFile(filePath);
+  return fileType === 'shared' || fileType === 'web' || fileType === 'native';
+}
+
+/**
+ * Checks if a file is a shared (cross-platform) component file
+ * These are the files that should NOT contain platform-specific imports
+ *
+ * @param filePath - The file path to check
+ * @returns True if the file is a shared component file
+ */
+export function isSharedFile(filePath: string): boolean {
+  return classifyFile(filePath) === 'shared';
+}
+
+/**
+ * Checks if a file is platform-specific
+ *
+ * @param filePath - The file path to check
+ * @returns True if the file is web or native specific
+ */
+export function isPlatformSpecificFile(filePath: string): boolean {
+  const fileType = classifyFile(filePath);
+  return fileType === 'web' || fileType === 'native';
+}
+
+/**
+ * Gets the expected platform for a file
+ *
+ * @param filePath - The file path to check
+ * @returns The expected platform, or null for shared/other files
+ */
+export function getExpectedPlatform(filePath: string): 'web' | 'native' | null {
+  const fileType = classifyFile(filePath);
+  if (fileType === 'web') return 'web';
+  if (fileType === 'native') return 'native';
+  return null;
+}
+
+/**
+ * Extracts the base component name from a file path
+ *
+ * @param filePath - The file path
+ * @returns The base component name without platform suffix or extension
+ *
+ * @example
+ * getBaseName('Button.web.tsx') // 'Button'
+ * getBaseName('Button.native.tsx') // 'Button'
+ * getBaseName('Button.tsx') // 'Button'
+ */
+export function getBaseName(filePath: string): string {
+  const fileName = path.basename(filePath);
+  return fileName
+    .replace(/\.(web|native|ios|android)\.(tsx|jsx|ts|js)$/, '')
+    .replace(/\.styles?\.(tsx|jsx|ts|js)$/, '')
+    .replace(/\.types?\.(tsx|ts)$/, '')
+    .replace(/\.(tsx|jsx|ts|js)$/, '');
+}

package/src/utils/importParser.ts

@@ -0,0 +1,235 @@
+import * as ts from 'typescript';
+import { ImportInfo, Platform } from '../types';
+import { REACT_NATIVE_SOURCES, REACT_DOM_SOURCES } from '../rules';
+
+/**
+ * Options for import parsing
+ */
+export interface ImportParserOptions {
+  /** Additional sources to treat as React Native */
+  additionalNativeSources?: string[];
+  /** Additional sources to treat as React DOM */
+  additionalDomSources?: string[];
+}
+
+/**
+ * Determines the platform for a given import source
+ */
+export function getPlatformForSource(
+  source: string,
+  options?: ImportParserOptions
+): Platform {
+  const nativeSources = new Set([
+    ...REACT_NATIVE_SOURCES,
+    ...(options?.additionalNativeSources ?? []),
+  ]);
+
+  const domSources = new Set([
+    ...REACT_DOM_SOURCES,
+    ...(options?.additionalDomSources ?? []),
+  ]);
+
+  // Check for exact matches first
+  if (nativeSources.has(source)) return 'react-native';
+  if (domSources.has(source)) return 'react-dom';
+
+  // Check for prefix matches (e.g., 'react-native-xxx')
+  if (source.startsWith('react-native')) return 'react-native';
+  if (source.startsWith('react-dom')) return 'react-dom';
+
+  return 'neutral';
+}
+
+/**
+ * Parses import statements from TypeScript/JavaScript source code
+ *
+ * @param sourceCode - The source code to parse
+ * @param filePath - Optional file path for better error messages
+ * @param options - Parser options
+ * @returns Array of import information
+ */
+export function parseImports(
+  sourceCode: string,
+  filePath: string = 'unknown.tsx',
+  options?: ImportParserOptions
+): ImportInfo[] {
+  const imports: ImportInfo[] = [];
+
+  // Create a source file from the code
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    sourceCode,
+    ts.ScriptTarget.Latest,
+    true,
+    filePath.endsWith('.tsx') || filePath.endsWith('.jsx')
+      ? ts.ScriptKind.TSX
+      : ts.ScriptKind.TS
+  );
+
+  // Walk the AST to find import declarations
+  const visit = (node: ts.Node): void => {
+    if (ts.isImportDeclaration(node)) {
+      const importInfo = parseImportDeclaration(node, sourceFile, options);
+      imports.push(...importInfo);
+    }
+
+    // Also check for require() calls
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'require' &&
+      node.arguments.length === 1 &&
+      ts.isStringLiteral(node.arguments[0])
+    ) {
+      const source = node.arguments[0].text;
+      const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+        node.getStart()
+      );
+
+      imports.push({
+        name: 'require',
+        source,
+        platform: getPlatformForSource(source, options),
+        line: line + 1,
+        column: character + 1,
+        isDefault: false,
+        isNamespace: true,
+        isTypeOnly: false,
+      });
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+
+  return imports;
+}
+
+/**
+ * Parses a single import declaration into ImportInfo objects
+ */
+function parseImportDeclaration(
+  node: ts.ImportDeclaration,
+  sourceFile: ts.SourceFile,
+  options?: ImportParserOptions
+): ImportInfo[] {
+  const imports: ImportInfo[] = [];
+
+  // Get the module specifier (the source)
+  if (!ts.isStringLiteral(node.moduleSpecifier)) {
+    return imports;
+  }
+
+  const source = node.moduleSpecifier.text;
+  const platform = getPlatformForSource(source, options);
+  const isTypeOnly = node.importClause?.isTypeOnly ?? false;
+
+  const importClause = node.importClause;
+  if (!importClause) {
+    // Side-effect import: import 'module'
+    return imports;
+  }
+
+  // Default import: import X from 'module'
+  if (importClause.name) {
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+      importClause.name.getStart()
+    );
+
+    imports.push({
+      name: importClause.name.text,
+      source,
+      platform,
+      line: line + 1,
+      column: character + 1,
+      isDefault: true,
+      isNamespace: false,
+      isTypeOnly,
+    });
+  }
+
+  // Named and namespace imports
+  const namedBindings = importClause.namedBindings;
+  if (namedBindings) {
+    if (ts.isNamespaceImport(namedBindings)) {
+      // Namespace import: import * as X from 'module'
+      const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+        namedBindings.name.getStart()
+      );
+
+      imports.push({
+        name: namedBindings.name.text,
+        source,
+        platform,
+        line: line + 1,
+        column: character + 1,
+        isDefault: false,
+        isNamespace: true,
+        isTypeOnly,
+      });
+    } else if (ts.isNamedImports(namedBindings)) {
+      // Named imports: import { X, Y as Z } from 'module'
+      for (const element of namedBindings.elements) {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+          element.name.getStart()
+        );
+
+        const importedName = element.propertyName?.text ?? element.name.text;
+        const localName = element.name.text;
+
+        imports.push({
+          name: localName,
+          originalName: element.propertyName ? importedName : undefined,
+          source,
+          platform,
+          line: line + 1,
+          column: character + 1,
+          isDefault: false,
+          isNamespace: false,
+          isTypeOnly: isTypeOnly || element.isTypeOnly,
+        });
+      }
+    }
+  }
+
+  return imports;
+}
+
+/**
+ * Filters imports to only those from platform-specific sources
+ */
+export function filterPlatformImports(
+  imports: ImportInfo[],
+  platform?: Platform
+): ImportInfo[] {
+  return imports.filter((imp) => {
+    if (imp.platform === 'neutral') return false;
+    if (platform && imp.platform !== platform) return false;
+    return true;
+  });
+}
+
+/**
+ * Gets all unique import sources from a list of imports
+ */
+export function getUniqueSources(imports: ImportInfo[]): string[] {
+  return [...new Set(imports.map((imp) => imp.source))];
+}
+
+/**
+ * Groups imports by their source module
+ */
+export function groupImportsBySource(
+  imports: ImportInfo[]
+): Map<string, ImportInfo[]> {
+  const grouped = new Map<string, ImportInfo[]>();
+
+  for (const imp of imports) {
+    const existing = grouped.get(imp.source) ?? [];
+    existing.push(imp);
+    grouped.set(imp.source, existing);
+  }
+
+  return grouped;
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './fileClassifier';
+export * from './importParser';