@idealyst/tooling 1.2.3

package/src/analyzers/platformImports.ts

@@ -0,0 +1,395 @@
+import {
+  AnalyzerOptions,
+  AnalysisResult,
+  FileInput,
+  FileType,
+  ImportInfo,
+  Severity,
+  Violation,
+  ViolationType,
+} from '../types';
+import { classifyFile } from '../utils/fileClassifier';
+import { parseImports } from '../utils/importParser';
+import {
+  REACT_NATIVE_PRIMITIVE_NAMES,
+  REACT_NATIVE_SOURCES,
+  isReactNativePrimitive,
+} from '../rules/reactNativePrimitives';
+import {
+  REACT_DOM_PRIMITIVE_NAMES,
+  REACT_DOM_SOURCES,
+  isReactDomPrimitive,
+} from '../rules/reactDomPrimitives';
+
+/**
+ * Default analyzer options
+ */
+const DEFAULT_OPTIONS: Required<AnalyzerOptions> = {
+  severity: 'error',
+  additionalNativePrimitives: [],
+  additionalDomPrimitives: [],
+  ignoredPrimitives: [],
+  ignoredPatterns: [],
+  additionalNativeSources: [],
+  additionalDomSources: [],
+};
+
+/**
+ * Check if a file path matches any of the ignored patterns
+ */
+function matchesIgnoredPattern(
+  filePath: string,
+  patterns: string[]
+): boolean {
+  if (patterns.length === 0) return false;
+
+  for (const pattern of patterns) {
+    // Simple glob matching - convert glob to regex
+    const regexPattern = pattern
+      .replace(/\*\*/g, '{{GLOBSTAR}}')
+      .replace(/\*/g, '[^/]*')
+      .replace(/{{GLOBSTAR}}/g, '.*')
+      .replace(/\?/g, '.');
+
+    const regex = new RegExp(regexPattern);
+    if (regex.test(filePath)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Creates a violation object
+ */
+function createViolation(
+  type: ViolationType,
+  primitive: string,
+  source: string,
+  filePath: string,
+  line: number,
+  column: number,
+  severity: Severity
+): Violation {
+  const messages: Record<ViolationType, string> = {
+    'native-in-shared': `React Native primitive '${primitive}' from '${source}' should not be used in shared files. Use a .native.tsx file instead.`,
+    'dom-in-shared': `React DOM primitive '${primitive}' from '${source}' should not be used in shared files. Use a .web.tsx file instead.`,
+    'native-in-web': `React Native primitive '${primitive}' from '${source}' should not be used in web-specific files.`,
+    'dom-in-native': `React DOM primitive '${primitive}' from '${source}' should not be used in native-specific files.`,
+  };
+
+  return {
+    type,
+    primitive,
+    source,
+    filePath,
+    line,
+    column,
+    message: messages[type],
+    severity,
+  };
+}
+
+/**
+ * Check if an import should be flagged as a React Native primitive
+ */
+function isNativePrimitive(
+  importInfo: ImportInfo,
+  additionalPrimitives: string[]
+): boolean {
+  const name = importInfo.originalName ?? importInfo.name;
+
+  // Check built-in primitives
+  if (isReactNativePrimitive(name)) return true;
+
+  // Check additional primitives
+  if (additionalPrimitives.includes(name)) return true;
+
+  // Check if the source is a known React Native source
+  const nativeSources: Set<string> = new Set([...REACT_NATIVE_SOURCES]);
+  if (nativeSources.has(importInfo.source)) {
+    // Any import from react-native that's a component (starts with uppercase)
+    if (/^[A-Z]/.test(name)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if an import should be flagged as a React DOM primitive
+ */
+function isDomPrimitive(
+  importInfo: ImportInfo,
+  additionalPrimitives: string[]
+): boolean {
+  const name = importInfo.originalName ?? importInfo.name;
+
+  // Check built-in primitives
+  if (isReactDomPrimitive(name)) return true;
+
+  // Check additional primitives
+  if (additionalPrimitives.includes(name)) return true;
+
+  return false;
+}
+
+/**
+ * Analyze a single file for platform import violations
+ *
+ * @param filePath - Path to the file being analyzed
+ * @param sourceCode - The source code content
+ * @param options - Analyzer options
+ * @returns Analysis result with violations
+ *
+ * @example
+ * ```typescript
+ * const result = analyzePlatformImports(
+ *   'src/components/Button.tsx',
+ *   sourceCode,
+ *   { severity: 'error' }
+ * );
+ *
+ * if (result.violations.length > 0) {
+ *   for (const v of result.violations) {
+ *     console.error(`${v.filePath}:${v.line}:${v.column} - ${v.message}`);
+ *   }
+ * }
+ * ```
+ */
+export function analyzePlatformImports(
+  filePath: string,
+  sourceCode: string,
+  options?: AnalyzerOptions
+): AnalysisResult {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const fileType = classifyFile(filePath);
+  const violations: Violation[] = [];
+
+  // Skip ignored files
+  if (matchesIgnoredPattern(filePath, opts.ignoredPatterns)) {
+    return {
+      filePath,
+      fileType,
+      violations: [],
+      imports: [],
+      passed: true,
+    };
+  }
+
+  // Skip non-component files
+  if (fileType === 'other' || fileType === 'styles' || fileType === 'types') {
+    return {
+      filePath,
+      fileType,
+      violations: [],
+      imports: [],
+      passed: true,
+    };
+  }
+
+  // Parse imports
+  const imports = parseImports(sourceCode, filePath, {
+    additionalNativeSources: opts.additionalNativeSources,
+    additionalDomSources: opts.additionalDomSources,
+  });
+
+  // Build ignored primitives set
+  const ignoredPrimitives = new Set(opts.ignoredPrimitives);
+
+  // Analyze each import
+  for (const imp of imports) {
+    // Skip type-only imports
+    if (imp.isTypeOnly) continue;
+
+    // Skip ignored primitives
+    const primitiveName = imp.originalName ?? imp.name;
+    if (ignoredPrimitives.has(primitiveName)) continue;
+
+    // Check for violations based on file type
+    switch (fileType) {
+      case 'shared':
+        // Shared files should not use platform-specific imports
+        if (isNativePrimitive(imp, opts.additionalNativePrimitives)) {
+          violations.push(
+            createViolation(
+              'native-in-shared',
+              primitiveName,
+              imp.source,
+              filePath,
+              imp.line,
+              imp.column,
+              opts.severity
+            )
+          );
+        }
+        if (isDomPrimitive(imp, opts.additionalDomPrimitives)) {
+          violations.push(
+            createViolation(
+              'dom-in-shared',
+              primitiveName,
+              imp.source,
+              filePath,
+              imp.line,
+              imp.column,
+              opts.severity
+            )
+          );
+        }
+        break;
+
+      case 'web':
+        // Web files should not use React Native imports
+        if (isNativePrimitive(imp, opts.additionalNativePrimitives)) {
+          violations.push(
+            createViolation(
+              'native-in-web',
+              primitiveName,
+              imp.source,
+              filePath,
+              imp.line,
+              imp.column,
+              opts.severity
+            )
+          );
+        }
+        break;
+
+      case 'native':
+        // Native files should not use React DOM imports
+        if (isDomPrimitive(imp, opts.additionalDomPrimitives)) {
+          violations.push(
+            createViolation(
+              'dom-in-native',
+              primitiveName,
+              imp.source,
+              filePath,
+              imp.line,
+              imp.column,
+              opts.severity
+            )
+          );
+        }
+        break;
+    }
+  }
+
+  return {
+    filePath,
+    fileType,
+    violations,
+    imports,
+    passed: violations.length === 0,
+  };
+}
+
+/**
+ * Analyze multiple files for platform import violations
+ *
+ * @param files - Array of files to analyze
+ * @param options - Analyzer options
+ * @returns Array of analysis results
+ *
+ * @example
+ * ```typescript
+ * const results = analyzeFiles(
+ *   [
+ *     { path: 'Button.tsx', content: buttonSource },
+ *     { path: 'Button.web.tsx', content: webSource },
+ *     { path: 'Button.native.tsx', content: nativeSource },
+ *   ],
+ *   { severity: 'warning' }
+ * );
+ *
+ * const failed = results.filter(r => !r.passed);
+ * ```
+ */
+export function analyzeFiles(
+  files: FileInput[],
+  options?: AnalyzerOptions
+): AnalysisResult[] {
+  return files.map((file) =>
+    analyzePlatformImports(file.path, file.content, options)
+  );
+}
+
+/**
+ * Get a summary of analysis results
+ */
+export interface AnalysisSummary {
+  totalFiles: number;
+  passedFiles: number;
+  failedFiles: number;
+  totalViolations: number;
+  violationsByType: Record<ViolationType, number>;
+  violationsBySeverity: Record<Severity, number>;
+}
+
+/**
+ * Summarize analysis results
+ *
+ * @param results - Array of analysis results
+ * @returns Summary statistics
+ */
+export function summarizeResults(results: AnalysisResult[]): AnalysisSummary {
+  const violationsByType: Record<ViolationType, number> = {
+    'native-in-shared': 0,
+    'dom-in-shared': 0,
+    'native-in-web': 0,
+    'dom-in-native': 0,
+  };
+
+  const violationsBySeverity: Record<Severity, number> = {
+    error: 0,
+    warning: 0,
+    info: 0,
+  };
+
+  let totalViolations = 0;
+
+  for (const result of results) {
+    for (const violation of result.violations) {
+      totalViolations++;
+      violationsByType[violation.type]++;
+      violationsBySeverity[violation.severity]++;
+    }
+  }
+
+  return {
+    totalFiles: results.length,
+    passedFiles: results.filter((r) => r.passed).length,
+    failedFiles: results.filter((r) => !r.passed).length,
+    totalViolations,
+    violationsByType,
+    violationsBySeverity,
+  };
+}
+
+/**
+ * Format a violation for console output
+ */
+export function formatViolation(violation: Violation): string {
+  const severityPrefix =
+    violation.severity === 'error'
+      ? 'ERROR'
+      : violation.severity === 'warning'
+        ? 'WARN'
+        : 'INFO';
+
+  return `${severityPrefix}: ${violation.filePath}:${violation.line}:${violation.column} - ${violation.message}`;
+}
+
+/**
+ * Format all violations from results for console output
+ */
+export function formatViolations(results: AnalysisResult[]): string[] {
+  const lines: string[] = [];
+
+  for (const result of results) {
+    for (const violation of result.violations) {
+      lines.push(formatViolation(violation));
+    }
+  }
+
+  return lines;
+}

package/src/index.ts

@@ -0,0 +1,142 @@
+/**
+ * @idealyst/tooling
+ *
+ * Code analysis and validation utilities for Idealyst Framework.
+ * Provides tools for babel plugins, CLI, and MCP to validate cross-platform code.
+ *
+ * Also provides component documentation generation:
+ * - analyzeComponents(): Generate a component registry from TypeScript source
+ * - analyzeTheme(): Extract theme values (intents, sizes, etc.)
+ * - idealystDocsPlugin(): Vite plugin for virtual module support
+ */
+
+// Types
+export * from './types';
+
+// Component Documentation (also available via @idealyst/tooling/docs)
+export {
+  analyzeComponents,
+  analyzeTheme,
+  // Babel plugin compatibility
+  loadThemeKeys,
+  resetThemeCache,
+  type BabelThemeKeys,
+  // Types
+  type ComponentRegistry,
+  type ComponentDefinition,
+  type PropDefinition,
+  type ThemeValues,
+  type ComponentAnalyzerOptions,
+} from './analyzer';
+
+// Vite Plugin (also available via @idealyst/tooling/vite)
+export { idealystDocsPlugin, generateComponentRegistry } from './vite-plugin';
+export type { IdealystDocsPluginOptions } from './analyzer/types';
+
+// Analyzers
+export {
+  analyzePlatformImports,
+  analyzeFiles,
+  summarizeResults,
+  formatViolation,
+  formatViolations,
+  type AnalysisSummary,
+} from './analyzers';
+
+// Rules
+export {
+  // React Native
+  REACT_NATIVE_SOURCES,
+  REACT_NATIVE_PRIMITIVES,
+  REACT_NATIVE_PRIMITIVE_NAMES,
+  REACT_NATIVE_RULE_SET,
+  isReactNativePrimitive,
+  getReactNativePrimitive,
+  // React DOM
+  REACT_DOM_SOURCES,
+  REACT_DOM_PRIMITIVES,
+  REACT_DOM_PRIMITIVE_NAMES,
+  REACT_DOM_RULE_SET,
+  HTML_INTRINSIC_ELEMENTS,
+  HTML_ELEMENT_NAMES,
+  isReactDomPrimitive,
+  isHtmlElement,
+  getReactDomPrimitive,
+} from './rules';
+
+// Utilities
+export {
+  classifyFile,
+  isComponentFile,
+  isSharedFile,
+  isPlatformSpecificFile,
+  getExpectedPlatform,
+  getBaseName,
+  parseImports,
+  getPlatformForSource,
+  filterPlatformImports,
+  getUniqueSources,
+  groupImportsBySource,
+  type ImportParserOptions,
+} from './utils';
+
+// =============================================================================
+// Runtime Placeholders - These get replaced by the Vite plugin at build time
+// =============================================================================
+
+import type { ComponentRegistry, ComponentDefinition } from './analyzer/types';
+
+/**
+ * Component registry placeholder.
+ * This empty object is replaced at build time by the idealystDocsPlugin
+ * with the actual component metadata extracted from your codebase.
+ *
+ * @example
+ * ```ts
+ * import { componentRegistry } from '@idealyst/tooling';
+ *
+ * // Access component definitions
+ * const buttonDef = componentRegistry['Button'];
+ * console.log(buttonDef.description);
+ * console.log(buttonDef.props);
+ * ```
+ */
+export const componentRegistry: ComponentRegistry = {};
+
+/**
+ * List of all component names in the registry.
+ * Replaced at build time by the Vite plugin.
+ */
+export const componentNames: string[] = [];
+
+/**
+ * Get components filtered by category.
+ * Replaced at build time by the Vite plugin.
+ */
+export function getComponentsByCategory(category: string): string[] {
+  return Object.entries(componentRegistry)
+    .filter(([_, def]) => def.category === category)
+    .map(([name]) => name);
+}
+
+/**
+ * Get prop configuration for a component (useful for playgrounds).
+ * Replaced at build time by the Vite plugin.
+ */
+export function getPropConfig(componentName: string): Record<string, any> {
+  const def = componentRegistry[componentName];
+  if (!def) return {};
+
+  return Object.entries(def.props).reduce((acc, [key, prop]) => {
+    if (prop.values && prop.values.length > 0) {
+      acc[key] = { type: 'select', options: prop.values, default: prop.default };
+    } else if (prop.type === 'boolean') {
+      acc[key] = { type: 'boolean', default: prop.default ?? false };
+    } else if (prop.type === 'string') {
+      acc[key] = { type: 'text', default: prop.default ?? '' };
+    } else if (prop.type === 'number') {
+      acc[key] = { type: 'number', default: prop.default ?? 0 };
+    }
+    return acc;
+  }, {} as Record<string, any>);
+}

package/src/rules/index.ts

@@ -0,0 +1,2 @@
+export * from './reactNativePrimitives';
+export * from './reactDomPrimitives';